次の方法で共有

GetPointerFramePenInfoHistory 関数 (winuser.h)

  • [アーティクル]

現在のメッセージに関連付けられている指定したポインター ( 型PT_PEN) のペンベースの情報 (合体入力フレームを含む) のフレーム全体を取得します。

構文

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

パラメーター

[in] pointerId

フレーム情報を取得するポインターの識別子。

[in, out] entriesCount

penInfo が指す 2 次元配列内の行数を指定する変数へのポインター。 GetPointerFramePenInfoHistory が成功した場合、entriesCount は履歴で使用可能なフレームの合計数で更新されます。

[in, out] pointerCount

penInfo が指す 2 次元配列内の列数を指定する変数へのポインター。 GetPointerFramePenInfoHistory が成功した場合、pointerCount は各フレーム内のポインターの合計数で更新されます。

[out, optional] penInfo

ポインター情報を受け取る POINTER_PEN_INFO 構造体の 2 次元配列のアドレス。 *entriesCount と *pointerCount の両方が 0 の場合、このパラメーターは NULL にすることができます。

この配列は、POINTER_PEN_INFO[*entriesCount][*pointerCount] として解釈されます。

戻り値

関数が成功した場合、戻り値は 0 以外です。

関数が失敗した場合は、0 を返します。 詳細なエラー情報を得るには、GetLastError を呼び出します。

解説

並列モード デバイスは、フレーム内のポインター入力を報告する場合があります。つまり、1 つの入力レポート内のデバイスからのすべてのポインターの状態と位置をシステムに報告できます。 アプリケーション固有の要件で特に指示がない限り、アプリケーションはフレーム全体を 1 つの入力として表示することをお勧めします。

GetPointerFramePenInfo によって返される情報は、呼び出し元のスレッドによって取得された最新のポインター (PT_PEN) メッセージに関連付けられます。 呼び出し元のスレッドによって次のメッセージが取得されると、前のメッセージに関連付けられている情報が使用できなくなる可能性があります。

アプリケーションがポインター入力メッセージを生成ほど速く処理しない場合は、一部のメッセージが WM_POINTERUPDATE メッセージに結合される可能性があります。 GetPointerFramePenInfoHistory を使用して、最新のWM_POINTERUPDATE メッセージからメッセージ履歴 (結合された入力フレームを含む) を取得します。

情報のフレーム全体を取得すると、アプリケーションは SkipPointerFrameMessages 関数を呼び出して、取得待ちのこのフレームに関連付けられている残りのポインター メッセージをスキップできます。 これにより、残りのメッセージを 1 つずつ取得して処理するオーバーヘッドがアプリケーションに節約されます。 ただし、 SkipPointerFrameMessages 関数は慎重に使用する必要があります。呼び出し元は、呼び出し元のスレッド上の他のエンティティが、取得時に残りのポインター メッセージを 1 つずつ表示することを期待していないことを確認できる場合にのみ使用してください。

フレームには、指定したポインターと同じウィンドウによって現在所有されているポインターのみが含まれます。

取得された情報は、履歴エントリごとに 1 行、フレーム内のポインターごとに 1 つの列を持つ 2 次元配列を表します。

取得された情報は、逆の時系列順に表示され、返された配列の最初の行に最新のエントリが表示されます。 最新のエントリは、 GetPointerFramePenInfo 関数によって返されるエントリと同じです。

指定されたバッファー内の行数が、使用可能なすべての履歴エントリを保持するのに不十分な場合、この関数は、最新のエントリを含むバッファーと、使用可能なエントリの合計数を含む *entriesCount で成功します。

ポインター フレームに、指定したポインター以外に追加のポインターが含まれない場合、この関数は成功し、指定されたポインターの情報のみを返します。

ポインター フレームに関連付けられている情報が使用できなくなった場合、この関数は最後のエラーが ERROR_NO_DATA に設定されて失敗します。

呼び出し元のスレッドが、ポインター メッセージが配信されたウィンドウ (入力が最初に配信されたウィンドウ、またはメッセージが転送された場所) を所有していない場合、この関数は最後のエラーを ERROR_ACCESS_DENIED に設定して失敗します。

指定したポインターが 型PT_PENでない場合、この関数は最後のエラーが ERROR_DATATYPE_MISMATCH に設定されて失敗します。

クライアント領域とクライアント以外の領域の両方を持つアプリの場合、入力フレームにはクライアントデータとクライアント以外のデータの両方を含めることができます。 クライアント データとクライアント以外のデータを区別するには、ターゲット ウィンドウでヒット テストを実行する必要があります。

入力フレームからデータをフィルター処理する場合は、次のことをお勧めします。

  • ポインターの接触 (POINTER_FLAG_INCONTACTのないPOINTER_FLAG_UPDATE) を含まない更新ごとに、ヒット テストを実行して、入力がクライアントかクライアント以外かを判断します。
  • 新しい連絡先 (POINTER_FLAG_DOWN) ごとに、ヒット テストを実行して、入力がクライアントかクライアント以外かを判断し、この情報を追跡します。
  • ポインターの連絡先 (POINTER_FLAG_INCONTACTを含むPOINTER_FLAG_UPDATE) を含む更新ごとに、追跡情報を使用して、入力がクライアントか非クライアントかを判断します。
  • POINTER_FLAG_UPごとに、追跡情報を使用して入力がクライアントか非クライアントかを判断し、追跡データからこのポインターをクリアします。

要件

   
サポートされている最小のクライアント Windows 8 [デスクトップ アプリのみ]
サポートされている最小のサーバー Windows Server 2012 [デスクトップ アプリのみ]
対象プラットフォーム Windows
ヘッダー winuser.h (Windows.h を含む)
Library User32.lib
[DLL] User32.dll

関連項目

関数

GetPointerFramePenInfo

GetPointerPenInfo

GetPointerPenInfoHistory