Compartilhar via

Função GetPointerFrameTouchInfo (winuser.h)

  • Artigo

Obtém todo o quadro de informações baseadas em toque para os ponteiros especificados (do tipo PT_TOUCH) associados à mensagem atual.

Sintaxe

BOOL GetPointerFrameTouchInfo(
  [in]      UINT32             pointerId,
  [in, out] UINT32             *pointerCount,
  [out]     POINTER_TOUCH_INFO *touchInfo
);

Parâmetros

[in] pointerId

Um identificador do ponteiro para o qual recuperar informações de quadro.

[in, out] pointerCount

Um ponteiro para uma variável que especifica a contagem de estruturas no buffer para o qual touchInfo aponta. Se GetPointerFrameTouchInfo for bem-sucedido, pointerCount será atualizado com a contagem total de ponteiros no quadro.

[out] touchInfo

Endereço de uma matriz de estruturas POINTER_TOUCH_INFO para receber as informações do ponteiro. Esse parâmetro poderá ser NULL se *pointerCount for zero.

Retornar valor

Se a função for bem-sucedida, o valor retornado será diferente de zero.

Se a função falhar, o valor retornado será zero. Para obter informações de erro estendidas, chame GetLastError.

Comentários

Os dispositivos de modo paralelo podem relatar a entrada de ponteiro em quadros, ou seja, eles podem relatar o estado e a posição de todos os ponteiros desse dispositivo em um único relatório de entrada para o sistema. O ideal é que os aplicativos exibam todo o quadro como uma única entrada, a menos que os requisitos específicos do aplicativo determinem o contrário.

GetPointerFrameTouchInfo recupera todo o quadro de entrada do ponteiro associado a uma mensagem de ponteiro (do tipo PT_TOUCH). Use GetPointerTouchInfo para recuperar informações de um único ponteiro associado a uma mensagem de ponteiro.

O quadro contém apenas ponteiros que pertencem atualmente à mesma janela que o ponteiro especificado.

As informações retornadas por GetPointerFrameTouchInfo estão associadas à mensagem de ponteiro mais recente recuperada pelo thread de chamada. Quando a próxima mensagem é recuperada pelo thread de chamada, as informações associadas à mensagem anterior podem não estar mais disponíveis.

Se o aplicativo não processar mensagens de entrada de ponteiro tão rápido quanto são geradas, algumas mensagens poderão ser agrupadas em uma mensagem WM_POINTERUPDATE . Use GetPointerFrameTouchInfoHistory para recuperar o histórico de mensagens da mensagem de WM_POINTERUPDATE mais recente.

Depois de recuperar todo o quadro de informações, o aplicativo pode chamar a função SkipPointerFrameMessages para ignorar as mensagens de ponteiro restantes associadas a esse quadro que estão pendentes de recuperação. Isso salva o aplicativo da sobrecarga de recuperar e processar as mensagens restantes uma a uma. No entanto, a função SkipPointerFrameMessages deve ser usada com cuidado e somente quando o chamador puder ter certeza de que nenhuma outra entidade no thread do chamador espera ver as mensagens de ponteiro restantes uma a uma conforme elas são recuperadas.

Observe que as informações recuperadas estão associadas ao quadro de ponteiro recuperado mais recentemente pelo thread de chamada. Depois que o thread de chamada recuperar sua próxima mensagem, as informações associadas ao quadro de ponteiro anterior poderão não estar mais disponíveis.

Se o quadro de ponteiro não contiver ponteiros adicionais além do ponteiro especificado, essa função terá êxito e retornará apenas as informações do ponteiro especificado.

Se as informações associadas ao quadro de ponteiro não estiverem mais disponíveis, essa função falhará com o último erro definido como ERROR_NO_DATA.

Se o thread de chamada não possuir a janela à qual a mensagem de ponteiro foi entregue, essa função falhará com o último erro definido como ERROR_ACCESS_DENIED.

Se o ponteiro especificado não for do tipo PT_TOUCH, essa função falhará com o último erro definido como ERROR_DATATYPE_MISMATCH.

Para aplicativos que têm áreas cliente e não cliente, o quadro de entrada pode incluir dados de cliente e não cliente. Para diferenciar entre dados de cliente e não cliente, você deve executar testes de clique na janela de destino.

Recomendamos o seguinte se você quiser filtrar dados do quadro de entrada:

  • Para cada atualização que não inclui um contato de ponteiro (um POINTER_FLAG_UPDATE sem POINTER_FLAG_INCONTACT), pressione o teste para determinar se a entrada é cliente ou não cliente.
  • Para cada novo contato (POINTER_FLAG_DOWN), faça o teste de clique para determinar se a entrada é cliente ou não cliente e acompanhar essas informações.
  • Para cada atualização que inclui um contato de ponteiro (um POINTER_FLAG_UPDATE com POINTER_FLAG_INCONTACT), use as informações de acompanhamento para determinar se a entrada é cliente ou não cliente.
  • Para cada POINTER_FLAG_UP, use as informações de rastreamento para determinar se a entrada é cliente ou não cliente e, em seguida, desmarque esse ponteiro dos dados de rastreamento.

Requisitos

Requisito Valor
Cliente mínimo com suporte Windows 8 [somente aplicativos da área de trabalho]
Servidor mínimo com suporte Windows Server 2012 [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-rtcore-ntuser-wmpointer-l1-1-0 (introduzido no Windows 10, versão 10.0.14393)

Confira também

Funções

GetPointerFrameTouchInfoHistory

GetPointerTouchInfo

GetPointerTouchInfoHistory