Mensagem WM_POINTERDOWN

Postado quando um ponteiro faz contato sobre a área do cliente de uma janela. Essa mensagem de entrada tem como alvo a janela sobre a qual o ponteiro faz contato, e o ponteiro é capturado implicitamente para a janela para que a janela continue a receber entrada para o ponteiro até que ele quebre o contato.

Uma janela recebe essa mensagem por meio da sua função WindowProc.

![Importante]
Os aplicativos da área de trabalho devem estar cientes do DPI. Se seu aplicativo não estiver ciente do DPI, as coordenadas de tela contidas em mensagens de ponteiro e estruturas relacionadas poderão parecer imprecisas devido à virtualização de DPI. A virtualização de DPI fornece suporte de dimensionamento automático para aplicativos que não têm reconhecimento de DPI e estão ativos por padrão (os usuários podem desativá-lo). Para obter mais informações, confira Escrevendo aplicativos Win32 de Alto DPI.

#define WM_POINTERDOWN                   0x0246

Parâmetros

wParam

Contém informações sobre o ponteiro. Use as macros a seguir para recuperar informações do parâmetro wParam.

• GET_POINTERID_WPARAM(wParam): o identificador do ponteiro.

• IS_POINTER_NEW_WPARAM(wParam): um sinalizador que indica se essa mensagem representa a primeira entrada gerada por um novo ponteiro.

• IS_POINTER_INRANGE_WPARAM(wParam): um sinalizador que indica se essa mensagem foi gerada por um ponteiro durante sua vida útil. Esse sinalizador não é definido em mensagens que indicam que o ponteiro deixou o intervalo de detecção

• IS_POINTER_INCONTACT_WPARAM(wParam): um sinalizador que indica se essa mensagem foi gerada por um ponteiro que está em contato com a superfície da janela. Esse sinalizador não é definido em mensagens que indicam um ponteiro pairando.

• IS_POINTER_PRIMARY_WPARAM(wParam): indica que este ponteiro foi designado como primário.

• IS_POINTER_FIRSTBUTTON_WPARAM(wParam): um sinalizador que indica se há uma ação primária.

  • Isso é análogo a um botão esquerdo do mouse para baixo.
  • Um ponteiro de toque terá esse conjunto quando estiver em contato com a superfície do digitalizador.
  • Um ponteiro de caneta terá esse conjunto quando estiver em contato com a superfície do digitalizador sem botões pressionados.

• IS_POINTER_SECONDBUTTON_WPARAM(wParam): um sinalizador que indica se há uma ação secundária.

  • Isso é análogo a um botão direito do mouse para baixo.
  • Um ponteiro de caneta terá esse conjunto quando estiver em contato com a superfície do digitalizador com o botão do cano da caneta pressionado.

• IS_POINTER_THIRDBUTTON_WPARAM(wParam): um sinalizador que indica se há uma ou mais ações terciárias com base no tipo de ponteiro; Por exemplo, um aplicativo pode determinar os estados dos botões de uma caneta chamando GetPointerPenInfo e examinando os sinalizadores que especificam os estados do botão.

• IS_POINTER_FOURTHBUTTON_WPARAM(wParam): um sinalizador que indica se o ponteiro especificado tomou a quarta ação. Os aplicativos que desejam responder à quarta ação devem recuperar informações específicas do tipo de ponteiro para determinar se o primeiro botão estendido do mouse (XButton1) está pressionado.

• IS_POINTER_FIFTHBUTTON_WPARAM(wParam): um sinalizador que indica se o ponteiro especificado executou a quinta ação. Os aplicativos que desejam responder à quinta ação devem recuperar informações específicas do tipo de ponteiro para determinar se o segundo botão estendido do mouse (XButton2) está pressionado.

  Consulte Sinalizadores de ponteiro para obter mais detalhes.

  Observação

  Um ponteiro pairando não tem nenhum dos sinalizadores de botão definidos. Isso é análogo a um movimento do mouse sem botões do mouse para baixo. Um aplicativo pode determinar os estados dos botões de uma caneta pairando, por exemplo, chamando GetPointerPenInfo e examinando os sinalizadores que especificam os estados do botão.

lParam

Contém a localização do ponto do ponteiro.

Observação

Como o ponteiro pode fazer contato com o dispositivo em uma área não trivial, essa localização do ponto pode ser uma simplificação de uma área mais complexa do ponteiro. Sempre que possível, um aplicativo deve usar as informações completas da área do ponteiro em vez da localização do ponto.

Utilize as seguintes macros para obter as coordenadas físicas da tela do ponto.

• GET_X_LPARAM(lParam): a coordenada x (ponto horizontal).
• GET_Y_LPARAM(lParam): a coordenada y (ponto vertical).

Valor retornado

Se um aplicativo processar essa mensagem, ela deverá retornar zero.

Se o aplicativo não processar essa mensagem, ele deverá chamar DefWindowProc.

Comentários

![Importante]
Quando uma janela perde a captura de um ponteiro e recebe a notificação WM_POINTERCAPTURECHANGED , normalmente não recebe mais notificações. Por esse motivo, é importante que você não faça suposições com base em WM_POINTERDOWN/pares uniformemente WM_POINTERUP ou WM_POINTERENTER/notificações WM_POINTERLEAVE notificações.

Cada ponteiro tem um identificador de ponteiro exclusivo durante sua vida útil. A vida útil de um ponteiro começa quando ele é detectado pela primeira vez.

Uma mensagem WM_POINTERENTER é gerada se um ponteiro pairado for detectado. Uma mensagem WM_POINTERDOWN seguida de uma mensagem WM_POINTERENTER é gerada se um ponteiro sem foco for detectado.

Durante sua vida útil, um ponteiro pode gerar uma série de mensagens WM_POINTERUPDATE enquanto está pairando ou em contato.

A vida útil de um ponteiro termina quando ele não é mais detectado. Isso gera uma mensagem WM_POINTERLEAVE .

Quando um ponteiro é abortado, POINTER_FLAG_CANCELED é definido.

Uma mensagem WM_POINTERLEAVE também pode ser gerada quando um ponteiro não capturado se move para fora dos limites de uma janela.

Para obter a posição horizontal e vertical de um ponteiro, use o seguinte:

xPos = GET_X_LPARAM(lParam); 
yPos = GET_Y_LPARAM(lParam);

Para converter o parâmetro lParam em uma estrutura POINTS, use a macro MAKEPOINTS.

Para recuperar mais informações associadas à mensagem, use a função GetPointerInfo.

Para determinar os estados de chave do modificador de teclado associados a essa mensagem, use a função GetKeyState. Por exemplo, para detectar que a tecla ALT foi pressionada, verifique se GetKeyState(VK_MENU) < 0.

Observe que se o aplicativo não processar essa mensagem, DefWindowProc pode gerar uma ou mais mensagens WM_GESTURE se a sequência de entrada deste e, possivelmente, outros ponteiros é reconhecida como um gesto. Se um gesto não for reconhecido, DefWindowProc pode gerar entrada do mouse.

Se um aplicativo consome seletivamente alguma entrada de ponteiro e passa o restante para DefWindowProc, o comportamento resultante é indefinido.

Quando uma janela perde a captura de um ponteiro e recebe a notificação WM_POINTERCAPTURECHANGED , ela normalmente não receberá mais notificações. Portanto, é importante que uma janela não faça suposições de seu status de ponteiro, independentemente de receber notificações DOWN / UP ou ENTER / LEAVE emparelhadas uniformemente.

Exemplos

O exemplo de código a seguir mostra como usar IS_POINTER_FIRSTBUTTON_WPARAM, GET_X_LPARAM, GET_Y_LPARAM e IS_POINTER_SECONDBUTTON_WPARAMpara recuperar as informações relevantes associadas à mensagem WM_POINTERDOWN.

int xPos = GET_X_LPARAM(lParam);
int yPos = GET_Y_LPARAM(lParam);

if (IS_POINTER_PRIMARYBUTTON_WPARAM(wParam))
{
    // process pointer down, similar to mouse left button down
}
else if (IS_POINTER_SECONDARYBUTTON_WPARAM(wParam))
{
    // process pointer down, similar to mouse right button down
}

O exemplo de código a seguir mostra como usar GET_POINTERID_WPARAM para recuperar a ID do ponteiro da mensagem WM_POINTERDOWN.

POINTER_INFO pointerInfo;
UINT32       pointerId = GET_POINTERID_WPARAM(wParam);

// Retrieve common pointer information
if (!GetPointerInfo(pointerId, &pointerInfo))
{
    // failure, call GetLastError()
}
else
{
    // success, process pointerInfo
}

O exemplo de código a seguir mostra como manipular diferentes tipos de ponteiro, como toque, caneta ou dispositivos apontadores padrão.

POINTER_TOUCH_INFO   touchInfo;
POINTER_PEN_INFO     penInfo;
POINTER_INFO         pointerInfo;
UINT32               pointerId = GET_POINTERID_WPARAM(wParam);
POINTER_TYPE         pointerType = PT_POINTER;

// default to unhandled to enable call to DefWindowProc
fHandled = FALSE;

if (!GetPointerType(pointerId, &pointerType))
{
    // failure, call GetLastError()
    // set PT_POINTER to fall to default case below
    pointerType = PT_POINTER;
}

switch (pointerType)
{
case PT_TOUCH:
    // Retrieve touch information
    if (!GetPointerTouchInfo(pointerId, &touchInfo))
    {
        // failure, call GetLastError()
    }
    else
    {
        // success, process touchInfo
        // mark as handled to skip call to DefWindowProc
        fHandled = TRUE;
    }
    break;
case PT_PEN:
    // Retrieve pen information
    if (!GetPointerPenInfo(pointerId, &penInfo))
    {
        // failure, call GetLastError()
    }
    else
    {
        // success, process penInfo
        // mark as handled to skip call to DefWindowProc
        fHandled = TRUE;
    }
    break;
default:
    if (!GetPointerInfo(pointerId, &pointerInfo)) 
    {
        // failure.
    } 
    else 
    {
        // success, proceed with pointerInfo.
        fHandled = HandleGenericPointerMessage(&pointerInfo);
    }
    break;
}

Requisitos

Confira também

Mensagens

Referência

Sinalizadores de ponteiro

GET_POINTERID_WPARAM

IS_POINTER_NEW_WPARAM

IS_POINTER_INRANGE_WPARAM

IS_POINTER_INCONTACT_WPARAM

IS_POINTER_PRIMARY_WPARAM

IS_POINTER_FIRSTBUTTON_WPARAM

IS_POINTER_SECONDBUTTON_WPARAM

IS_POINTER_THIRDBUTTON_WPARAM

IS_POINTER_FOURTHBUTTON_WPARAM

IS_POINTER_FIFTHBUTTON_WPARAM