Função GetPointerFrameInfoHistory (winuser.h)
Obtém todo o quadro de informações (incluindo quadros de entrada unidos) para os ponteiros especificados associados à mensagem atual.
Sintaxe
BOOL GetPointerFrameInfoHistory(
[in] UINT32 pointerId,
[in, out] UINT32 *entriesCount,
[in, out] UINT32 *pointerCount,
[out] POINTER_INFO *pointerInfo
);
Parâmetros
[in] pointerId
Um identificador do ponteiro para o qual recuperar informações de quadro.
[in, out] entriesCount
Um ponteiro para uma variável que especifica a contagem de linhas na matriz bidimensional para a qual pointerInfo aponta. Se GetPointerFrameInfoHistory for bem-sucedido, entriesCount será atualizado com a contagem total de quadros disponíveis no histórico.
[in, out] pointerCount
Um ponteiro para uma variável que especifica a contagem de colunas na matriz bidimensional para a qual pointerInfo aponta. Se GetPointerFrameInfoHistory for bem-sucedido, pointerCount será atualizado com a contagem total de ponteiros em cada quadro.
[out] pointerInfo
Endereço de uma matriz bidimensional de estruturas POINTER_INFO para receber as informações do ponteiro. Esse parâmetro poderá ser NULL se *entriesCount e *pointerCount forem zero.
Essa matriz é interpretada como POINTER_INFO[*entriesCount][*pointerCount].
Valor retornado
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.
As informações retornadas por GetPointerFrameInfo 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 GetPointerFrameInfoHistory para recuperar o histórico de mensagens (incluindo quadros de entrada unidos) 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.
O quadro contém apenas ponteiros que pertencem atualmente à mesma janela que o ponteiro especificado.
As informações recuperadas representam uma matriz bidimensional com uma linha para cada entrada de histórico e uma coluna para cada ponteiro no quadro.
As informações recuperadas aparecem em ordem cronológica inversa, com a entrada mais recente na primeira linha da matriz retornada. A entrada mais recente é a mesma retornada pela função GetPointerFrameInfo .
Se a contagem de linhas no buffer fornecido for insuficiente para manter todas as entradas de histórico disponíveis, essa função terá êxito com o buffer que contém as entradas mais recentes e *entriesCount contendo a contagem total de entradas 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 (em que a entrada foi entregue originalmente ou onde a mensagem foi encaminhada) para a qual a mensagem de ponteiro foi entregue, essa função falhará com o último erro definido como ERROR_ACCESS_DENIED.
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
| 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) |