Funzione GetPointerFrameInfoHistory (winuser.h)

Articolo
08/27/2023

Ottiene l'intero frame di informazioni (inclusi i frame di input uniti) per i puntatori specificati associati al messaggio corrente.

Sintassi

BOOL GetPointerFrameInfoHistory(
  [in]      UINT32       pointerId,
  [in, out] UINT32       *entriesCount,
  [in, out] UINT32       *pointerCount,
  [out]     POINTER_INFO *pointerInfo
);

Parametri

[in] pointerId

Identificatore del puntatore per il quale recuperare le informazioni sui frame.

[in, out] entriesCount

Puntatore a una variabile che specifica il numero di righe nella matrice bidimensionale a cui punta pointerInfo. Se GetPointerFrameInfoHistory ha esito positivo, entriesCount viene aggiornato con il numero totale di fotogrammi disponibili nella cronologia.

[in, out] pointerCount

Puntatore a una variabile che specifica il numero di colonne nella matrice bidimensionale a cui punta pointerInfo. Se GetPointerFrameInfoHistory ha esito positivo, pointerCount viene aggiornato con il numero totale di puntatori in ogni fotogramma.

[out] pointerInfo

Indirizzo di una matrice bidimensionale di strutture POINTER_INFO per ricevere le informazioni sul puntatore. Questo parametro può essere NULL se *entriesCount e *pointerCount sono entrambi zero.

Questa matrice viene interpretata come POINTER_INFO[*entriesCount][*pointerCount].

Valore restituito

Se la funzione ha esito positivo, il valore restituito è diverso da zero.

Se la funzione ha esito negativo, il valore restituito è zero. Per informazioni dettagliate sull'errore, chiamare GetLastError.

Commenti

I dispositivi in modalità parallela possono segnalare l'input del puntatore nei fotogrammi, ovvero possono segnalare lo stato e la posizione di tutti i puntatori da tale dispositivo in un singolo report di input al sistema. Idealmente, le applicazioni devono visualizzare l'intero frame come singolo input, a meno che i requisiti specifici dell'applicazione non specificino diversamente.

Le informazioni restituite da GetPointerFrameInfo sono associate al messaggio del puntatore più recente recuperato dal thread chiamante. Quando il messaggio successivo viene recuperato dal thread chiamante, le informazioni associate al messaggio precedente potrebbero non essere più disponibili.

Se l'applicazione non elabora i messaggi di input del puntatore con la stessa velocità con cui vengono generati, alcuni messaggi potrebbero essere uniti in un messaggio di WM_POINTERUPDATE . Usare GetPointerFrameInfoHistory per recuperare la cronologia dei messaggi (inclusi i frame di input uniti) dal messaggio di WM_POINTERUPDATE più recente.

Dopo aver recuperato l'intero frame di informazioni, l'applicazione può quindi chiamare la funzione SkipPointerFrameMessages per ignorare i messaggi del puntatore rimanenti associati a questo frame in sospeso. In questo modo l'applicazione consente di risparmiare il sovraccarico di recupero ed elaborazione dei messaggi rimanenti uno alla sola. Tuttavia, la funzione SkipPointerFrameMessages deve essere usata con attenzione e solo quando il chiamante può assicurarsi che nessun'altra entità nel thread del chiamante visualizzi i messaggi del puntatore rimanenti uno per uno quando vengono recuperati.

Il frame contiene solo puntatori di proprietà della stessa finestra del puntatore specificato.

Le informazioni recuperate rappresentano una matrice bidimensionale con una riga per ogni voce di cronologia e una colonna per ogni puntatore nel frame.

Le informazioni recuperate vengono visualizzate in ordine cronologico inverso, con la voce più recente nella prima riga della matrice restituita. La voce più recente corrisponde a quella restituita dalla funzione GetPointerFrameInfo .

Se il numero di righe nel buffer specificato non è sufficiente per contenere tutte le voci della cronologia disponibili, questa funzione ha esito positivo con il buffer contenente le voci più recenti e *entriesCount contenente il numero totale di voci disponibili.

Se il frame del puntatore non contiene puntatori aggiuntivi oltre al puntatore specificato, questa funzione ha esito positivo e restituisce solo le informazioni per il puntatore specificato.

Se le informazioni associate al frame del puntatore non sono più disponibili, questa funzione ha esito negativo con l'ultimo errore impostato su ERROR_NO_DATA.

Se il thread chiamante non è proprietario della finestra (in cui l'input è stato originariamente recapitato o in cui è stato inoltrato il messaggio) a cui è stato recapitato il messaggio del puntatore, questa funzione ha esito negativo con l'ultimo errore impostato su ERROR_ACCESS_DENIED.

Per le app con aree client e non client, il frame di input può includere sia dati client che non client. Per distinguere i dati client e non client, è necessario eseguire hit testing nella finestra di destinazione.

Se si desidera filtrare i dati dal frame di input, è consigliabile quanto segue:

Per ogni aggiornamento che non include un contatto puntatore (un POINTER_FLAG_UPDATE senza POINTER_FLAG_INCONTACT), hit test per determinare se l'input è client o non client.
Per ogni nuovo contatto (POINTER_FLAG_DOWN), hit test per determinare se l'input è client o non client e tenere traccia di queste informazioni.
Per ogni aggiornamento che include un contatto puntatore (un POINTER_FLAG_UPDATE con POINTER_FLAG_INCONTACT), usare le informazioni di rilevamento per determinare se l'input è client o non client.
Per ogni POINTER_FLAG_UP, usare le informazioni di rilevamento per determinare se l'input è client o non client e quindi cancellare questo puntatore dai dati di rilevamento.

Requisiti


Client minimo supportato	Windows 8 [solo app desktop]
Server minimo supportato	Windows Server 2012 [solo app desktop]
Piattaforma di destinazione	Windows
Intestazione	winuser.h (include Windows.h)
Libreria	User32.lib
DLL	User32.dll
Set di API	ext-ms-win-rtcore-ntuser-wmpointer-l1-1-0 (introdotto in Windows 10, versione 10.0.14393)

Vedi anche

Funzioni

GetPointerFrameInfo

GetPointerInfo

GetPointerInfoHistory

Condividi tramite