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

  • [アーティクル]

IAccessible::accNavigate メソッドは、コンテナー内の別の UI 要素に移動し、オブジェクトを取得します。 このメソッドは省略可能です。

メモaccNavigate メソッドは非推奨であり、使用しないでください。 クライアントは、 AccessibleChildren、 get_accChild、 get_accParent、 IEnumVARIANT などの他のメソッドとプロパティを使用する必要があります。
 

構文

HRESULT accNavigate(
  [in]          long    navDir,
  [in]          VARIANT varStart,
  [out, retval] VARIANT *pvarEndUpAt
);

パラメーター

[in] navDir

型: long

移動する方向を指定します。 この方向は、 左 または右などの空間順、または次や前などの 論理 順序です。 この値は、 ナビゲーション定数の 1 つです。

[in] varStart

型: VARIANT

ナビゲーションの開始オブジェクトがオブジェクト自体であるか、オブジェクトの子の 1 つであるかを指定します。 このパラメーターは、CHILDID_SELF (オブジェクトから開始する場合) または子 ID (オブジェクトの子要素のいずれかから開始する場合) のいずれかです。 VARIANT の初期化の詳細については、「パラメーターでの子 ID の使用方法」を参照してください。

[out, retval] pvarEndUpAt

型: VARIANT*

[out, retval]変換先オブジェクトに関する情報を受け取る VARIANT 構造体のアドレス。 次の表では、 pvarEnd で返される情報について説明します。

vt メンバー 値メンバー
VT_EMPTY
 [なし] : 指定した方向に UI 要素がありませんでした。
VT_I4
 lVal には、UI 要素の子 ID が含まれています。
VT_DISPATCH
 pdispVal には、UI 要素の IDispatch のアドレスが含まれています。

戻り値

型: HRESULT

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

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

エラー 説明
S_FALSE
 指定した方向に screen 要素が見つかりませんでした。
DISP_E_MEMBERNOTFOUND
 オブジェクトは、このメソッドをサポートしていません。
E_INVALIDARG
 引数が有効ではありません。

注釈

ナビゲーションは、空間と論理の両方で、常にコンテナー内の UI 要素に制限されます。 空間ナビゲーションでは、クライアントは開始オブジェクト (varStart) の兄弟にのみ移動します。 論理ナビゲーションで使用されるナビゲーション フラグに応じて、クライアントは子または開始オブジェクトの兄弟に移動します。

accNavigate メソッドは、定義された画面の場所を持つ UI 要素と、定義された画面の場所を持たない非表示オブジェクトを取得します。

このメソッドは、選択またはフォーカスを変更しません。 フォーカスを変更したり、オブジェクトを選択したりするには、 IAccessible::accSelect を使用します。

画面上の要素を走査するときにループを防ぐために、 accNavigate は、最後の要素にNAVDIR_NEXTを指定したとき、または最初の要素にNAVDIR_PREVIOUSしたときに、 VT_EMPTY を含 むS_FALSE を返します。

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

メニュー、メニュー項目、ポップアップ メニューなどの一部のシステム定義 UI 要素では、非表示オブジェクトへのナビゲーションが可能です。 ただし、他のシステム定義 UI 要素では、これをサポートしていません。 サーバーは、非表示のオブジェクトへの移動をサポートするかどうかを選択でき、スキップするか公開することができます。

accNavigate を使用してオブジェクト間を移動する場合、クライアント アプリケーションはプロセス後の戻り値を返す必要があります。 後処理手順の目的は、クライアントに IAccessible インターフェイス ポインターと子 ID を与えて、UI 要素の IAccessible メソッドとプロパティを使用できるようにすることです。

次の表では、次の条件に基づいて、 IAccessible::accNavigate の考えられるシナリオについて説明します。

  • 定義された開始点 (完全なオブジェクトまたは単純な要素から始めるかどうか)
  • 返された結果 ( IDispatch またはVT_I4子 ID)
  • IAccessible インターフェイス ポインターと子 ID を持つには、クライアント アプリケーションが実行する必要がある後処理
これらのテーブルでは、 startID と endID が子 ID (単純な要素) VT_I4であり、 pStartAcc と pEndAcc が CHILDID_SELF (完全なオブジェクト) でVT_I4されているとします。

次の表では、次のNAVDIR_ フラグについて説明します。NEXT、PREVIOUS、LEFT、RIGHT、UP、DOWN。 ナビゲーション フラグの詳細については、「 ナビゲーション定数」を参照してください。

開始ポイント 返される結果 戻り値の後処理
pStartAcc、startID endID のVT_I4 endIDを渡すpStartAcc でget_accChildを呼び出します。 get_accChildに記載されている通常の手順に従います。
pStartAcc、startID VT_DISPATCH pEndAcc iDispatch インターフェイス ポインターを pEndAcc の IAccessible インターフェイス ポインターに変換するには、標準の手順を使用します。
pStartAcc、CHILDID_SELF endID のVT_I4 pStartAcc で get_accParentを呼び出し、CHILDID_SELFを渡して endID の親の IAccessible インターフェイス ポインターを取得します。 次に、その IAccessible インターフェイス ポインターで get_accChildを呼び出し、endID を渡します。 get_accChildに記載されている通常の手順に従います。
pStartAcc、CHILDID_SELF VT_DISPATCH pEndAcc iDispatch インターフェイス ポインターを pEndAcc の IAccessible インターフェイス ポインターに変換するには、標準の手順を使用します。
 

次の表では、ナビゲーション フラグ のNAVDIR_FIRSTCHILD と NAVDIR_LASTCHILDについて説明します。 開始点が単純な要素である場合、最初または最後の子に移動するためのエントリは含まれません。単純な要素に子を含めることはできません。

開始ポイント 返される結果 戻り値の後処理
pStartAcc、CHILDID_SELF endID のVT_I4 pStartAcc で get_accChildを呼び出し、endID を渡します。 get_accChildに記載されている通常の手順に従います。
pStartAcc、CHILDID_SELF VT_DISPATCH pEndAcc iDispatch インターフェイス ポインターを pEndAcc の IAccessible インターフェイス ポインターに変換するには、標準の手順を使用します。
 

詳細については、「 オブジェクト ナビゲーションのプロパティとメソッド」を参照してください。

サーバーの例

次の例は、リスト 項目が子要素であるカスタム リスト ボックスの メソッドの実装の可能性を示しています。 

// m_pControl is the control that returns this accessible object. 
// m_pStdAccessibleObject is the standard accessible object for the window 
//    that contains the control. 

HRESULT STDMETHODCALLTYPE AccServer::accNavigate( 
    long navDir,
    VARIANT varStart,
    VARIANT *pvarEndUpAt)
{
    // Default value. 
    pvarEndUpAt->vt = VT_EMPTY;

    if (varStart.vt != VT_I4)
    {
        return E_INVALIDARG;
    }

    switch (navDir)
    {
    case NAVDIR_FIRSTCHILD:
        if (varStart.lVal == CHILDID_SELF)
        {
            pvarEndUpAt->vt = VT_I4;
            pvarEndUpAt->lVal = 1;
        }
        else  // Starting with child. 
        {
            return S_FALSE;
        }
        break;

    case NAVDIR_LASTCHILD:
        if (varStart.lVal == CHILDID_SELF)
        {
            pvarEndUpAt->vt = VT_I4;
            pvarEndUpAt->lVal = m_pControl->GetCount();
        }
        else  // Starting with child.           
        {
            return S_FALSE;
        }
        break;

    case NAVDIR_NEXT:   
    case NAVDIR_DOWN:
        if (varStart.lVal != CHILDID_SELF)
        {
            pvarEndUpAt->vt = VT_I4;
            pvarEndUpAt->lVal = varStart.lVal + 1;
            // Out of range. 
            if (pvarEndUpAt->lVal > m_pControl->GetCount())
            {
                pvarEndUpAt->vt = VT_EMPTY;
                return S_FALSE;
            }
        }
        else  // Call through to method on standard object. 
        {
            return m_pStdAccessibleObject->accNavigate(navDir, varStart, pvarEndUpAt);
        }
        break;

    case NAVDIR_PREVIOUS:
    case NAVDIR_UP:
        if (varStart.lVal != CHILDID_SELF)
        {
            pvarEndUpAt->vt = VT_I4;
            pvarEndUpAt->lVal = varStart.lVal - 1;
            // Out of range. 
            if (pvarEndUpAt->lVal <1)
            {
                pvarEndUpAt->vt = VT_EMPTY;
                return S_FALSE;
            }
        }
        else  // Call through to method on standard object. 
        {
            return m_pStdAccessibleObject->accNavigate(navDir, varStart, pvarEndUpAt);
        }
        break;

     // Unsupported directions. 
    case NAVDIR_LEFT:
    case NAVDIR_RIGHT:
        if (varStart.lVal == CHILDID_SELF)
        {
            return m_pStdAccessibleObject->accNavigate(navDir, varStart, pvarEndUpAt);
        }
        else 
        {
            pvarEndUpAt->vt = VT_EMPTY;
            return S_FALSE;
        }
        break;
    }
    return S_OK;
};

要件

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

こちらもご覧ください

Iaccessible

IAccessible::accSelect

IDispatch

オブジェクト ナビゲーションのプロパティとメソッド

バリアント