Share via

IViewObjectEx::QueryHitPoint メソッド (ocidl.h)

  • [アーティクル]

ポイントがオブジェクトの特定の側面内にあるかどうかを示します。

構文

HRESULT QueryHitPoint(
  [in]  DWORD   dwAspect,
  [in]  LPCRECT pRectBounds,
  [in]  POINT   ptlLoc,
  [in]  LONG    lCloseHint,
  [out] DWORD   *pHitResult
);

パラメーター

[in] dwAspect

要求された描画の側面。

[in] pRectBounds

格納しているウィンドウのクライアント座標内のオブジェクトの外接する四角形。 この四角形は計算され、コンテナーによって渡されるため、オブジェクトはヒット位置を意味のある形で解釈できます。

[in] ptlLoc

格納しているウィンドウのクライアント座標内のヒット位置。

[in] lCloseHint

コンテナーが閉じると見なす HIMETRIC 単位の推奨距離。 この値はヒントであり、オブジェクトは独自の方法で解釈できます。 オブジェクトは、このヒントを使用して、ヒット テストの実装の拡張性を選択するために、出力解像度を大まかに推測することもできます。

[out] pHitResult

HITRESULT 列挙値として表されるヒットに関する情報を返すポインター。

戻り値

このメソッドは、成功 したS_OK を返します。 その他の可能な戻り値は次のとおりです。

リターン コード 説明
E_FAIL
 このメソッドは、要求された側面には実装されません。 代わりに DVASPECT_CONTENT を使用してください。

注釈

四角形以外のオブジェクトでヒット検出をサポートするには、特定の場所がその描画面の 1 つ内にあるかどうかをオブジェクトに確認するための信頼性の高い方法が必要です。 この関数は、 IViewObjectEx::QueryHitPoint によって提供されます。

メモ このメソッドは IViewObjectEx インターフェイスの一部であるため、コンテナーは、必ずしもサーバーを起動しなくても、マウス ヒットがオブジェクトの上にあるかどうかを確認できます。 ヒットがオブジェクト内にある場合は、オブジェクトがインプレース アクティブ化され、サーバーが起動される可能性があります。
 
通常、コンテナーは最初に、特定の場所がオブジェクトの四角形の範囲内にあるかどうかを迅速に判断します。 場所がオブジェクトの四角形の範囲内にある場合、コンテナーは IViewObjectEx::QueryHitPoint を呼び出して、その場所が実際にオブジェクト内にあることを確認します。 ヒット位置は、コンテナー ウィンドウのクライアント座標で渡されます。 このメソッドを呼び出すと、オブジェクトが非アクティブになる可能性があるため、 IPointerInactive::OnInactiveSetCursor で発生するのと同様に、同じ座標系のオブジェクトの外接する四角形もこのメソッドに渡されます。

可能な戻り値は次のとおりです。

  • 外側、透明領域
  • ヒットと見なされるほど近い (小さいオブジェクトや薄いオブジェクトで使用される場合があります)
  • ヒット
IViewObjectEx::QueryHitPoint は、呼び出されるオブジェクトのサブオブジェクトには関係ありません。 マウスヒットがオブジェクト内にあったかどうかを示すだけです。

IViewObjectEx::QueryHitPoint は、オブジェクトがサポートする描画面に対して呼び出すことができます。 要求された描画の側面でサポートされていない場合は失敗します。

透明オブジェクトは、クリックがオブジェクト内の正確な場所に応じて、ユーザーが透明なオブジェクトまたはその背後にあるオブジェクトを選択できる複雑なヒット検出メカニズムを実装したい場合があります。 たとえば、十分な大きさのテキストを示す透明なテキスト ボックスを使用すると、ユーザーが文字の間をクリックしたときに、ビットマップなどの背後にあるオブジェクトを選択できます。 このため、 IViewObjectEx::QueryHitPoint によって返される情報には、ヒットが不透明な領域または透明な領域で発生したかどうかを示す情報が含まれています。

四角形以外の透明なヒット検出の例として、オブジェクトが背後にある透明な円コントロールがあります (次の例の線)。

円の内側と外側、および線の近くにある領域のヒット検出値を示す、斜めの線を通した円の図。

表示される値は、円に対するヒット テスト用です。灰色の領域はコントロールの一部ではありませんが、画像の周囲の領域が近いと見なされる領域を示すためにここに示されています。 各オブジェクトは、close の独自の定義を実装しますが、コンテナーによって提供されるヒントによって支援されるため、画像の拡大または縮小に合わせて近さを調整できます。

上の図では、[ヒット]、[閉じる]、および [透明] とマークされたポイントはすべて、円上のさまざまな強さのヒットになります。ただし、Transparent とマークされている点は除きます (ただし、線の場合は閉じます)。 これは、ヒットの異なる強さの影響を示しています。 行の要求が閉じられ、透明が近いよりも弱い間に円が透明に応答するため、線はヒットします。

実装者へのメモ

IViewObjectEx をサポートするオブジェクトは、少なくともDVASPECT_CONTENTの側面に対してこのメソッドを実装するために必要です。 オブジェクトは、情報を返す以外に、このメソッドに応答して他のアクションを実行しないでください。副作用はありません。

要件

要件 値
サポートされている最小のクライアント Windows 2000 Professional [デスクトップ アプリのみ]
サポートされている最小のサーバー Windows 2000 Server [デスクトップ アプリのみ]
対象プラットフォーム Windows
ヘッダー ocidl.h

こちらもご覧ください

HITRESULT

IPointerInactive::OnInactiveSetCursor

IViewObjectEx