Funzione GetPointerFramePenInfo (winuser.h)
Ottiene l'intero frame di informazioni basate su penna per i puntatori specificati (di tipo PT_PEN) associati al messaggio corrente.
Sintassi
BOOL GetPointerFramePenInfo(
[in] UINT32 pointerId,
[in, out] UINT32 *pointerCount,
[out] POINTER_PEN_INFO *penInfo
);
Parametri
[in] pointerId
Identificatore del puntatore per il quale recuperare le informazioni sui frame.
[in, out] pointerCount
Puntatore a una variabile che specifica il numero di strutture nel buffer a cui punta penInfo. Se GetPointerFramePenInfo ha esito positivo, pointerCount viene aggiornato con il numero totale di puntatori nel frame.
[out] penInfo
Indirizzo di una matrice di strutture POINTER_PEN_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 specificino diversamente.
GetPointerFramePenInfo recupera l'intero frame di input del puntatore associato a un messaggio puntatore (di tipo PT_PEN). Utilizzare GetPointerPenInfo per recuperare informazioni per un singolo puntatore associato a un messaggio del puntatore.
Il frame contiene solo puntatori di proprietà della stessa finestra del puntatore specificato.
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 GetPointerFramePenInfoHistory 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 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.
Si noti che le informazioni recuperate sono associate al frame del puntatore recuperato più di recente dal thread chiamante. Dopo che il thread chiamante recupera 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 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 è stato recapitato il messaggio del puntatore, questa funzione ha esito negativo con l'ultimo errore impostato su ERROR_ACCESS_DENIED.
Se il puntatore specificato non è di tipo PT_PEN, 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 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
| 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 |