IRawElementProviderWindowlessSite

Microsoft ActiveX コントロールサイトは、Microsoft UI Automation 対応の ActiveX コントロールがアクセシビリティを表現できるようにするために、このインターフェイスを実装します。

このコントロールサイトが所有するウィンドウレスの Microsoft ActiveX コントロールに隣接するフラグメントのフラグメントポインターを取得します。

Type: HRESULT

このメソッドが成功した場合は S_OK を返します。それ以外の場合は HRESULT エラーコードを返します。direction が NavigateDirection_FirstChild または NavigateDirection_LastChild(これらはこのメソッドでは無効です)の場合、戻り値は E_INVALIDARG になります。要求された方向に隣接フラグメントが存在しない場合、メソッドは S_OK を返し、ppRetVal に NULL を設定します。

フラグメントの親を返すには、IRawElementProviderFragment インターフェイスを実装するオブジェクトが Navigate メソッドを実装できる必要があります。ウィンドウレスの ActiveX コントロールは、親オブジェクトのアクセシブルツリー内での自身の位置を特定できない場合があるため、Navigate の実装は困難です。GetAdjacentFragment メソッドを使用すると、ウィンドウレスの ActiveX コントロールは自身のサイトに隣接フラグメントを問い合わせ、そのフラグメントを Navigate を呼び出したクライアントに返すことができます。

プロバイダーは通常、IRawElementProviderFragment::Navigate メソッドの処理の一部としてこのメソッドを呼び出します。

例

次の C++ コード例は、GetAdjacentFragment メソッドの実装方法を示しています。

IFACEMETHODIMP CProviderWindowlessSite::GetAdjacentFragment(
        enum NavigateDirection direction, IRawElementProviderFragment **ppFragment)   
{
    if (ppFragment == NULL)
    {
        return E_INVALIDARG;
    }
    
    *ppFragment = NULL;
    HRESULT hr = S_OK;

    switch (direction)
    {
        case NavigateDirection_Parent:
            {  
                IRawElementProviderSimple *pSimple = NULL;

                // アプリケーション定義の関数を呼び出して
                // 親プロバイダーインターフェイスを取得します。
                hr = GetParentProvider(&pSimple);  
                if (SUCCEEDED(hr))  
                {  
                    // 親の IRawElementProviderFragment インターフェイスを取得します。
                    hr = pSimple->QueryInterface(IID_PPV_ARGS(ppFragment));  
                    pSimple->Release();  
                } 
            }  
            break;  
  
        case NavigateDirection_FirstChild:
        case NavigateDirection_LastChild:
            hr = E_INVALIDARG;
            break;

        // 隣接フラグメントが存在しないため、NavigateDirection_NextSibling と
        // NavigateDirection_PreviousSibling は無視します。
        default:  
            break;  
    }  
  
    return hr;  
}   

ウィンドウレスの Microsoft ActiveX コントロールサイトに固有の Microsoft UI Automation ランタイム ID を取得します。

Type: HRESULT

このメソッドが成功した場合は S_OK を返します。それ以外の場合は HRESULT エラーコードを返します。

UI Automation フラグメントは、フラグメントの一意な ID を返すために IRawElementProviderFragment::GetRuntimeId メソッドを実装する必要があります。ウィンドウレスの ActiveX コントロールは、ActiveX コントロールコンテナー内の他のウィンドウレスコントロールの中で自身を一意なものとして識別できる必要があるため、これは困難です。この問題を解決するには、ウィンドウレスサイトは、定数 UiaAppendRuntimeId の後にこのウィンドウレスサイトに固有の整数値を続けた SAFEARRAY を作成することで、GetRuntimeIdPrefix メソッドを実装する必要があります。

これにより、フラグメントは、ウィンドウレスの ActiveX コントロール内の他のすべてのフラグメントに対して一意な整数値を追加し、それをクライアントに返すことができます。

たとえば、サイトは次の内容の SAFEARRAY を返す場合があります: { UiaAppendRuntimeId, 3 }。これはコンテナー内の 3 番目の ActiveX コントロールを表す可能性があります。フラグメントプロバイダーの GetRuntimeId メソッドは、次の内容の SAFEARRAY を作成できます: { UiaAppendRuntimeId, 3, 5 }。これは ActiveX コンテナー内の 5 番目のフラグメントを表す可能性があります。SAFEARRAY 全体が、ActiveX コントロールコンテナー全体に対して一意な ID となります。

プロバイダーは通常、GetRuntimeId メソッドの処理の一部としてこのメソッドを呼び出します。

例

次の C++ コード例は、GetRuntimeIdPrefix メソッドの実装方法を示しています。

IFACEMETHODIMP CProviderWindowlessSite::GetRuntimeIdPrefix(   
     SAFEARRAY **ppsaPrefix)   
{   
    if (ppsaPrefix == NULL) 
    {
        return E_INVALIDARG;
    }

    // m_siteIndex はウィンドウレスコントロールのサイトの
    // インデックスです。コントロールコンテナーによって定義されます。
    int rId[] = { UiaAppendRuntimeId, m_siteIndex };
    SAFEARRAY *psa = SafeArrayCreateVector(VT_I4, 0, 2);  
    if (psa == NULL)
    {
        return E_OUTOFMEMORY;
    }

    for (LONG i = 0; i < 2; i++)
    {
        SafeArrayPutElement(psa, &i, (void*)&(rId[i]));
    }

    *ppsaPrefix = psa;  
    return S_OK;  
}