Função MapWindowPoints (winuser.h)

Artigo
03/15/2023

A função MapWindowPoints converte (mapeia) um conjunto de pontos de um espaço de coordenadas relativo a uma janela para um espaço de coordenadas em relação a outra janela.

Sintaxe

int MapWindowPoints(
  [in]      HWND    hWndFrom,
  [in]      HWND    hWndTo,
  [in, out] LPPOINT lpPoints,
  [in]      UINT    cPoints
);

Parâmetros

[in] hWndFrom

Um identificador para a janela da qual os pontos são convertidos. Se esse parâmetro for NULL ou HWND_DESKTOP, presume-se que os pontos estejam nas coordenadas da tela.

[in] hWndTo

Um identificador para a janela na qual os pontos são convertidos. Se esse parâmetro for NULL ou HWND_DESKTOP, os pontos serão convertidos em coordenadas de tela.

[in, out] lpPoints

Um ponteiro para uma matriz de estruturas POINT que contêm o conjunto de pontos a serem convertidos. Os pontos estão em unidades de dispositivo. Esse parâmetro também pode apontar para uma estrutura RECT , nesse caso, o parâmetro cPoints deve ser definido como 2.

[in] cPoints

O número de estruturas POINT na matriz apontada pelo parâmetro lpPoints .

Retornar valor

Se a função for bem-sucedida, a palavra de baixa ordem do valor retornado será o número de pixels adicionados à coordenada horizontal de cada ponto de origem para calcular a coordenada horizontal de cada ponto de destino. (Além disso, se precisamente um de hWndFrom e hWndTo for espelhado, cada coordenada horizontal resultante será multiplicada por -1.) A palavra de alta ordem é o número de pixels adicionados à coordenada vertical de cada ponto de origem para calcular a coordenada vertical de cada ponto de destino.

Se a função falhar, o valor retornado será zero. Chame SetLastError antes de chamar esse método para diferenciar um valor retornado de erro de um valor retornado legítimo "0".

Comentários

Se hWndFrom ou hWndTo (ou ambos) forem janelas espelhadas (ou seja, tiverem WS_EX_LAYOUTRTL estilo estendido) e precisamente dois pontos forem passados em lpPoints, MapWindowPoints interpretará esses dois pontos como um RECT e possivelmente trocará automaticamente os campos esquerdo e direito desse retângulo para garantir que a esquerda não seja maior que a direita. Se qualquer número de pontos diferentes de 2 for passado em lpPoints, MapWindowPoints mapeará corretamente as coordenadas de cada um desses pontos separadamente, portanto, se você passar um ponteiro para uma matriz de mais de um retângulo em lpPoints, os novos retângulos poderão obter seu campo esquerdo maior que a direita. Portanto, para garantir a transformação correta das coordenadas do retângulo, você deve chamar MapWindowPoints com um ponteiro RECT por vez, conforme mostrado no exemplo a seguir:


   RECT        rc[10];

   for(int i = 0; i < (sizeof(rc)/sizeof(rc[0])); i++)
   {
       MapWindowPoints(hWnd1, hWnd2, (LPPOINT)(&rc[i]), (sizeof(RECT)/sizeof(POINT)) );
   }

Além disso, se você precisar mapear precisamente dois pontos independentes e não quiser que a lógica RECT seja aplicada a eles pelo MapWindowPoints, para garantir o resultado correto, você deve chamar MapWindowPoints com um ponteiro POINT por vez, conforme mostrado no exemplo a seguir:


   POINT pt[2];

   MapWindowPoints(hWnd1, hWnd2, &pt[0], 1);
   MapWindowPoints(hWnd1, hWnd2, &pt[1], 1);

Requisitos

Requisito	Valor
Cliente mínimo com suporte	Windows 2000 Professional [somente aplicativos da área de trabalho]
Servidor mínimo com suporte	Windows 2000 Server [somente aplicativos da área de trabalho]
Plataforma de Destino	Windows
Cabeçalho	winuser.h (inclua Windows.h)
Biblioteca	User32.lib
DLL	User32.dll
Conjunto de APIs	ext-ms-win-ntuser-window-l1-1-2 (introduzido no Windows 10, versão 10.0.10240)