IAccessible::accHitTest メソッド (oleacc.h)

[アーティクル]
08/25/2023

IAccessible::accHitTest メソッドは、画面上の特定のポイントに表示される子要素または子オブジェクトを取得します。すべてのビジュアルオブジェクトでこのメソッドがサポートされていますが、サウンドオブジェクトではサポートされていません。クライアントアプリケーションでこのメソッドが直接呼び出されることはほとんどありません。ある時点で表示されるアクセス可能なオブジェクトを取得するには、このメソッドを内部的に呼び出す AccessibleObjectFromPoint 関数を使用します。

構文

HRESULT accHitTest(
  [in]          long    xLeft,
  [in]          long    yTop,
  [out, retval] VARIANT *pvarChild
);

パラメーター

[in] xLeft

型: long

ヒットテストされるポイントの画面座標を指定します。 x 座標は左から右に増加します。画面座標を使用する場合、原点は画面の左上隅であることに注意してください。

[in] yTop

型: long

ヒットテストされるポイントの画面座標を指定します。 y 座標は上から下に増加します。画面座標を使用する場合、原点は画面の左上隅であることに注意してください。

[out, retval] pvarChild

型: VARIANT*

[out, retval]xLeft および yTop で指定されたポイントに表示されるオブジェクトを識別する VARIANT のアドレス。 pvarID で返される情報は、accHitTest メソッドが呼び出されているオブジェクトに対する指定されたポイントの位置によって異なります。

ポイントの位置	vt メンバー	値メンバー
オブジェクトの境界の外側、およびオブジェクトの外接する四角形の内側または外側。	VT_EMPTY	[なし] :
オブジェクト内で、子要素または子オブジェクト内には含まれません。	VT_I4	lVal がCHILDID_SELF。
子要素内。	VT_I4	lVal には子 ID が含まれています。
子オブジェクト内。	VT_DISPATCH	pdispVal が子オブジェクトの IDispatch インターフェイスポインターに設定されている

戻り値

型: HRESULT

成功した場合は、S_OK を返します。

成功しなかった場合は、次のテーブルの値の 1 つ、または別の標準 COM エラーコードを返します。サーバーはこれらの値を返しますが、クライアントは常に出力パラメーターをチェックして、有効な値が含まれていることを確認する必要があります。詳細については、「 IAccessible 戻り値の確認」を参照してください。

エラー	説明
S_FALSE	ポイントはオブジェクトの境界の外側にあります。 pvarID の vt メンバーがVT_EMPTY。
DISP_E_MEMBERNOTFOUND	オブジェクトは、このメソッドをサポートしていません。
E_INVALIDARG	引数が有効ではありません。

クライアント開発者への注意: pvarID の vt メンバーがVT_EMPTY場合、サーバーはS_FALSEを返しますが、pvarID-vt> がVT_EMPTYで戻り値がS_OK場合もクライアントが処理する必要があります。

注釈

テスト対象のポイントがオブジェクトの子の 1 つにあり、この子が IAccessible インターフェイス自体をサポートしている場合、このメソッドは IAccessible インターフェイスポインターを返す必要があります。ただし、 IAccessible インターフェイスポインターまたは子 ID を処理するには、クライアントを準備する必要があります。詳細については、「パラメーターでの子 ID の使用方法」を参照してください。

accLocation は外接する四角形を返すので、その四角形内のすべてのポイントがオブジェクトの実際の境界内にあるわけではありません。外接する四角形内の一部のポイントがオブジェクト上にない場合があります。 1 つの項目にアイコンの四角形とアイコンのテキスト用の別の四角形がある大きなアイコンモードのリストビュー項目など、四角形以外のオブジェクトの場合、accHitTest でテストすると、IAccessible::accLocation によって取得されたオブジェクトの外接する四角形の座標が失敗する可能性があります。

他の IAccessible メソッドや関数と同様に、クライアントはユーザーアクションのために IAccessible インターフェイスポインターのエラーを受け取る可能性があります。詳細については、「 IAccessible インターフェイスポインターのエラーの受信」を参照してください。

特定の状況でこの方法を使用する場合は、追加の使用メモが適用されます。詳細については、「ヒットテストのナビゲーション」と「画面の場所」を参照してください。

サーバーの例

次のコード例は、カスタムリストボックスに対して可能な実装を示しています。


// m_pControl is the control that returns this accessible object. 
// m_hwnd is the HWND of the control window. 
//  
HRESULT STDMETHODCALLTYPE AccServer::accHitTest( 
    long xLeft,
    long yTop,
    VARIANT *pvarChild) 

{
    POINT pt;
    pt.x = xLeft;
    pt.y = yTop;

    // Not in our window. 
    if (WindowFromPoint(pt) != m_hwnd)
    {
        pvarChild->vt = VT_EMPTY;
        return S_FALSE;
    }

    else  // In our window; return list item, or self if in blank space. 
    {
        pvarChild->vt = VT_I4;
        ScreenToClient(m_hwnd, &pt);
        // IndexFromY returns the 0-based index of the item at that point, 
        // or -1 if the point is not on any item.
        int index = m_pControl->IndexFromY(pt.y);
        if (index >= 0)
        {
            // Increment, because the child array is 1-based. 
            pvarChild->lVal = index + 1;
        }
        else
        {
            pvarChild->lVal = CHILDID_SELF;

        }
        return S_OK;
    }
};

クライアントの例

次の関数例では、 pAcc で表されるリスト内の画面上の指定したポイントにある項目を選択します。 1 つの選択が必要であると見なされます。


HRESULT SelectItemAtPoint(IAccessible* pAcc, POINT point)
{
    if (pAcc == NULL)
    {
        return E_INVALIDARG;
    }
    VARIANT varChild;

    HRESULT hr = pAcc->accHitTest(point.x, point.y, &varChild);        
    if ((hr == S_OK) && (varChild.lVal != CHILDID_SELF))
    {
        return pAcc->accSelect((SELFLAG_TAKEFOCUS | SELFLAG_TAKESELECTION), varChild);
    }
    return S_FALSE;
}

要件

要件	値
サポートされている最小のクライアント	Windows 2000 Professional [デスクトップアプリのみ]
サポートされている最小のサーバー	Windows Server 2003 (デスクトップアプリのみ)
対象プラットフォーム	Windows
ヘッダー	oleacc.h
Library	Oleacc.lib
[DLL]	Oleacc.dll
再頒布可能パッケージ	SP6 以降および Windows 95 を使用した Windows NT 4.0 のアクティブなアクセシビリティ 1.3 RDK