GetPointerFramePenInfo-Funktion (winuser.h)

Ruft den gesamten Frame der stiftbasierten Informationen für die angegebenen Zeiger (vom Typ PT_PEN) ab, die der aktuellen Nachricht zugeordnet sind.

Syntax

BOOL GetPointerFramePenInfo(
  [in]      UINT32           pointerId,
  [in, out] UINT32           *pointerCount,
  [out]     POINTER_PEN_INFO *penInfo
);

Parameter

[in] pointerId

Ein Bezeichner des Zeigers, für den Frameinformationen abgerufen werden sollen.

[in, out] pointerCount

Ein Zeiger auf eine Variable, die die Anzahl der Strukturen im Puffer angibt, auf die penInfo verweist. Wenn GetPointerFramePenInfo erfolgreich ist, wird pointerCount mit der Gesamtanzahl der Zeiger im Frame aktualisiert.

[out] penInfo

Adresse eines Arrays von POINTER_PEN_INFO Strukturen, um die Zeigerinformationen zu empfangen. Dieser Parameter kann NULL sein, wenn *pointerCount null ist.

Rückgabewert

Wenn die Funktion erfolgreich ist, ist der Rückgabewert ungleich 0 (null).

Wenn die Funktion fehlerhaft ist, ist der Rückgabewert null. Um erweiterte Fehlerinformationen zu erhalten, rufen Sie GetLastError auf.

Hinweise

Geräte im Parallelmodus können Zeigereingaben in Frames melden, d. h., sie können den Zustand und die Position aller Zeiger von diesem Gerät in einem einzelnen Eingabebericht an das System melden. Im Idealfall sollten Anwendungen den gesamten Frame als einzelne Eingabe anzeigen, es sei denn, die anwendungsspezifischen Anforderungen sehen etwas anderes vor.

GetPointerFramePenInfo ruft den gesamten Zeigereingaberahmen ab, der einer Zeigernachricht (vom Typ PT_PEN) zugeordnet ist. Verwenden Sie GetPointerPenInfo , um Informationen für einen einzelnen Zeiger abzurufen, der einer Zeigernachricht zugeordnet ist.

Der Frame enthält nur Zeiger, die sich derzeit im Besitz desselben Fensters wie der angegebene Zeiger befinden.

Die von GetPointerFrameInfo zurückgegebenen Informationen sind der letzten Zeigernachricht zugeordnet, die vom aufrufenden Thread abgerufen wurde. Wenn die nächste Nachricht vom aufrufenden Thread abgerufen wird, sind die Informationen, die der vorherigen Nachricht zugeordnet sind, möglicherweise nicht mehr verfügbar.

Wenn die Anwendung Zeigereingabenachrichten nicht so schnell verarbeitet, wie sie generiert werden, werden einige Nachrichten möglicherweise zu einer WM_POINTERUPDATE Nachricht zusammengefasst. Verwenden Sie GetPointerFramePenInfoHistory , um den Nachrichtenverlauf aus der letzten WM_POINTERUPDATE Nachricht abzurufen.

Nachdem sie den gesamten Datenrahmen abgerufen hat, kann die Anwendung dann die SkipPointerFrameMessages-Funktion aufrufen, um die verbleibenden Zeigermeldungen zu überspringen, die diesem Frame zugeordnet sind und ausstehen. Dies spart der Anwendung den Mehraufwand beim Abrufen und Verarbeiten der verbleibenden Nachrichten nacheinander. Die SkipPointerFrameMessages-Funktion sollte jedoch mit Sorgfalt und nur verwendet werden, wenn der Aufrufer sicher sein kann, dass keine andere Entität im Thread des Aufrufers erwartet, dass die verbleibenden Zeigernachrichten nacheinander angezeigt werden, wenn sie abgerufen werden.

Beachten Sie, dass die abgerufenen Informationen dem zeigerframe zugeordnet sind, der zuletzt vom aufrufenden Thread abgerufen wurde. Sobald der aufrufende Thread seine nächste Nachricht abruft, sind die Informationen, die dem vorherigen Zeigerframe zugeordnet sind, möglicherweise nicht mehr verfügbar.

Wenn der Zeigerrahmen neben dem angegebenen Zeiger keine zusätzlichen Zeiger enthält, ist diese Funktion erfolgreich und gibt nur die Informationen für den angegebenen Zeiger zurück.

Wenn die dem Zeigerrahmen zugeordneten Informationen nicht mehr verfügbar sind, schlägt diese Funktion fehl, wenn der letzte Fehler auf ERROR_NO_DATA festgelegt ist.

Wenn der aufrufende Thread nicht besitzer des Fensters ist, in das die Zeigernachricht übermittelt wurde, schlägt diese Funktion fehl, wobei der letzte Fehler auf ERROR_ACCESS_DENIED festgelegt ist.

Wenn der angegebene Zeiger nicht vom Typ PT_PEN ist, schlägt diese Funktion fehl, wobei der letzte Fehler auf ERROR_DATATYPE_MISMATCH festgelegt ist.

Für Apps, die sowohl Client- als auch Nicht-Client-Bereiche haben, kann der Eingaberahmen sowohl Clientdaten als auch Nicht-Clientdaten enthalten. Um zwischen Client- und Nichtclientdaten zu unterscheiden, müssen Sie Treffertests im Zielfenster durchführen.

Wenn Sie Daten aus dem Eingaberahmen filtern möchten, empfehlen wir Folgendes:

• Für jedes Update, das keinen Zeigerkontakt (eine POINTER_FLAG_UPDATE ohne POINTER_FLAG_INCONTACT) enthält, wird ein Treffertest durchgeführt, um zu ermitteln, ob es sich bei der Eingabe um einen Client oder nicht um einen Client handelt.
• Treffertest für jeden neuen Kontakt (POINTER_FLAG_DOWN), um festzustellen, ob die Eingabe client- oder nicht clientseitig ist, und verfolgen Sie diese Informationen.
• Verwenden Sie für jedes Update, das einen Zeigerkontakt (eine POINTER_FLAG_UPDATE mit POINTER_FLAG_INCONTACT) enthält, die Nachverfolgungsinformationen, um zu bestimmen, ob es sich bei der Eingabe um einen Client oder nicht um einen Client handelt.
• Verwenden Sie für jeden POINTER_FLAG_UP die Nachverfolgungsinformationen, um zu bestimmen, ob es sich bei der Eingabe um Client oder Nicht-Client handelt, und löschen Sie dann diesen Zeiger aus den Nachverfolgungsdaten.

Anforderungen

Anforderung	Wert
Unterstützte Mindestversion (Client)	Windows 8 [nur Desktop-Apps]
Unterstützte Mindestversion (Server)	Windows Server 2012 [nur Desktop-Apps]
Zielplattform	Windows
Kopfzeile	winuser.h (windows.h einschließen)
Bibliothek	User32.lib
DLL	User32.dll

Siehe auch

Funktionen

GetPointerFramePenInfoHistory

GetPointerPenInfo

GetPointerPenInfoHistory