Funzione GetPointerFrameInfo (winuser.h)

Ottiene l'intero frame di informazioni per i puntatori specificati associati al messaggio corrente.

Sintassi

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

Parametri

[in] pointerId

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

[in, out] pointerCount

Puntatore a una variabile che specifica il conteggio delle strutture nel buffer a cui punta pointerInfo. Se GetPointerFrameInfo ha esito positivo, puntatoreCount viene aggiornato con il numero totale di puntatori nel frame.

[out] pointerInfo

Indirizzo di una matrice di strutture POINTER_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.

GetPointerFrameInfo recupera l'intero frame di input del puntatore associato a un messaggio di puntatore. Usare GetPointerInfo per recuperare informazioni per un singolo puntatore associato a un messaggio del puntatore.

Il frame contiene solo puntatori attualmente 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 quando vengono generati, alcuni messaggi potrebbero essere uniti in un messaggio di WM_POINTERUPDATE . Usare GetPointerFrameInfoHistory 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 (in cui l'input è stato originariamente recapitato o dove il messaggio è stato inoltrato) 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 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

Vedi anche

Funzioni

GetPointerFrameInfoHistory

GetPointerInfo

GetPointerInfoHistory