Funzione GetPointerFramePenInfoHistory (winuser.h)

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

Sintassi

BOOL GetPointerFramePenInfoHistory(
  [in]            UINT32           pointerId,
  [in, out]       UINT32           *entriesCount,
  [in, out]       UINT32           *pointerCount,
  [out, optional] POINTER_PEN_INFO *penInfo
);

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 in cui penInfo punta. Se GetPointerFramePenInfoHistory 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 in cui penInfo punta. Se GetPointerFramePenInfoHistory ha esito positivo, pointerCount viene aggiornato con il numero totale di puntatori in ogni fotogramma.

[out, optional] penInfo

Indirizzo di una matrice bidimensionale di strutture POINTER_PEN_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_PEN_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 GetPointerFramePenInfo sono associate al messaggio di puntatore (PT_PEN) 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 (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 è uguale a quella restituita dalla funzione GetPointerFramePenInfo .

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.

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

Vedi anche

Funzioni

GetPointerFramePenInfo

GetPointerPenInfo

GetPointerPenInfoHistory