Funzione GetPointerFrameTouchInfo (winuser.h)
Ottiene l'intero frame di informazioni basate sul tocco per i puntatori specificati (di tipo PT_TOUCH) associati al messaggio corrente.
Sintassi
BOOL GetPointerFrameTouchInfo(
[in] UINT32 pointerId,
[in, out] UINT32 *pointerCount,
[out] POINTER_TOUCH_INFO *touchInfo
);
Parametri
[in] pointerId
Identificatore del puntatore per il quale recuperare le informazioni sul frame.
[in, out] pointerCount
Puntatore a una variabile che specifica il numero di strutture nel buffer a cui touchInfo punta. Se GetPointerFrameTouchInfo ha esito positivo, puntatoreCount viene aggiornato con il numero totale di puntatori nel frame.
[out] touchInfo
Indirizzo di una matrice di strutture POINTER_TOUCH_INFO per ricevere le informazioni sul puntatore. Questo parametro può essere NULL se *pointerCount è zero.
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 determinino altrimenti.
GetPointerFrameTouchInfo recupera l'intero frame di input del puntatore associato a un messaggio puntatore (di tipo PT_TOUCH). Usare GetPointerTouchInfo per recuperare informazioni per un singolo puntatore associato a un messaggio di puntatore.
Il frame contiene solo puntatori attualmente di proprietà della stessa finestra del puntatore specificato.
Le informazioni restituite da GetPointerFrameTouchInfo 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 quando vengono generati, alcuni messaggi potrebbero essere uniti in un messaggio di WM_POINTERUPDATE . Usare GetPointerFrameTouchInfoHistory per recuperare la cronologia dei messaggi 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 salva il sovraccarico del recupero e dell'elaborazione dei messaggi rimanenti uno per uno. Tuttavia, la funzione SkipPointerFrameMessages deve essere usata con attenzione e solo quando il chiamante può essere sicuro che nessun'altra entità nel thread del chiamante dovrebbe visualizzare i messaggi del puntatore rimanenti uno per uno quando vengono recuperati.
Si noti che le informazioni recuperate sono associate al frame del puntatore di recente recuperato dal thread chiamante. Una volta recuperato il messaggio successivo, le informazioni associate al frame del puntatore precedente potrebbero non essere più disponibili.
Se il frame del puntatore non contiene puntatori aggiuntivi oltre al puntatore specificato, questa funzione riesce e restituisce solo le informazioni per il puntatore specificato.
Se le informazioni associate al frame del puntatore non sono più disponibili, questa funzione non riesce con l'ultimo errore impostato su ERROR_NO_DATA.
Se il thread chiamante non possiede la finestra a cui è stato recapitato il messaggio del puntatore, questa funzione non riesce con l'ultimo errore impostato su ERROR_ACCESS_DENIED.
Se il puntatore specificato non è di tipo PT_TOUCH, questa funzione ha esito negativo con l'ultimo errore impostato su ERROR_DATATYPE_MISMATCH.
Per le app con aree client e non client, il frame di input può includere sia dati client che non client. Per distinguere tra i dati client e non client, è necessario eseguire hit test nella finestra di destinazione.
È consigliabile filtrare i dati dal frame di input:
- 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
| Requisito | Valore |
|---|---|
| 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 (introdotta in Windows 10, versione 10.0.14393) |