IRawElementProviderFragment

リストボックスやリスト項目など、複数レベルの深さを持つ構造の一部である UI 要素上のメソッドとプロパティを公開します。Microsoft UI Automation プロバイダーによって実装されます。

フラグメントのルートノードは、IRawElementProviderFragmentRoot インターフェイスもサポートする必要があります。

UI Automation ツリー内で、指定された方向にある Microsoft UI Automation 要素を取得します。

型: HRESULT

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

このメソッドの UI Automation サーバー側の実装によって、UI Automation ツリーの構造が定義されます。

ナビゲーションは、該当する場合、親への上方向、最初および最後の子への下方向、次および前の兄弟への横方向でサポートされる必要があります。

各子ノードは 1 つの親のみを持ち、親から NavigateDirection_FirstChild および NavigateDirection_LastChild でたどれる兄弟の連鎖の中に配置される必要があります。

兄弟間の関係は、両方向で一貫している必要があります。すなわち、A が B の前の兄弟(NavigateDirection_PreviousSibling)であれば、B は A の次の兄弟(NavigateDirection_NextSibling)です。最初の子(NavigateDirection_FirstChild)には前の兄弟がなく、最後の子(NavigateDirection_LastChild)には次の兄弟がありません。

フラグメントのルートは、親や兄弟へのナビゲーションを有効にしません。フラグメントのルート間のナビゲーションは、既定のウィンドウプロバイダーによって処理されます。フラグメント内の要素は、同じフラグメント内の他の要素にのみナビゲートする必要があります。

例

次の例は、リスト項目プロバイダーの実装を示します。親、前の兄弟、次の兄弟の各プロバイダーのメンバー変数は、リストが作成されたときに初期化されています。

HRESULT STDMETHODCALLTYPE ListItemProvider::Navigate(NavigateDirection direction, IRawElementProviderFragment ** pRetVal)
{
    if (pRetVal == NULL) 
    {
        return E_INVALIDARG;
    }

    IRawElementProviderFragment* pFrag = NULL;
    switch(direction)
    {
        case NavigateDirection_Parent:
            pFrag = (IRawElementProviderFragment*)m_parentProvider;       
            break;

        case NavigateDirection_NextSibling:
            pFrag = (IRawElementProviderFragment*)m_nextSiblingProvider;
            break;

        case NavigateDirection_PreviousSibling:  
            pFrag = (IRawElementProviderFragment*)m_previousSiblingProvider;
            break;
    }
    *pRetVal = pFrag;
    if (pFrag != NULL) 
    {
        pFrag->AddRef();
    }
    return S_OK;
}              

要素のランタイム識別子を取得します。

型: HRESULT

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

実装は、ウィンドウ内でホストされるトップレベル要素に対しては NULL を返す必要があります。それ以外の要素は、UiaAppendRuntimeId(Uiautomationcoreapi.h で定義)に続けて、フラグメントのインスタンス内で一意の値を含む配列を返す必要があります。

例

リスト項目に対する次の実装は、UiaAppendRuntimeId 定数と、リスト内での項目のインデックスから構成されるランタイム識別子を返します。

HRESULT STDMETHODCALLTYPE ListItemProvider::GetRuntimeId(SAFEARRAY ** pRetVal)
{
    if (pRetVal == NULL) 
    {
        return E_INVALIDARG;
    }
    
    int rId[] = { UiaAppendRuntimeId, m_itemIndex };
    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]));
    }
    
    *pRetVal = psa;
    return S_OK;
}   

この要素の境界矩形を指定します。

境界矩形は、画面上の左上隅の位置とサイズによって定義されます。

要素の一部が隠れている場合や一部が画面外にある場合でも、クリッピングは不要です。矩形が実際に表示されているかどうかを示すために、IsOffscreen プロパティを設定する必要があります。

境界矩形内のすべての点が必ずしもクリック可能であるとは限りません。

例

次のリスト項目プロバイダーによる実装例は、項目の高さと、それを含むリストボックス内での位置に基づいて、項目の境界矩形を計算します。

HRESULT STDMETHODCALLTYPE ListItemProvider::get_BoundingRectangle(UiaRect * pRetVal)
{
    if (pRetVal == NULL) return E_INVALIDARG;

    UiaRect parentRect;
    HRESULT hr = m_parentProvider->get_BoundingRectangle(&parentRect);
    pRetVal->left = parentRect.left;
    pRetVal->top = parentRect.top + (m_pParentControl->m_itemHeight * m_itemIndex);
    pRetVal->width = parentRect.width;
    pRetVal->height = m_pParentControl->m_itemHeight;
    return S_OK;
}             

現在の要素をルートとする Microsoft UI Automation ツリーに埋め込まれているルートフラグメントの配列を取得します。

型: HRESULT

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

このメソッドは、現在の要素が別のオートメーションフレームワークをホストしている場合にのみ、フラグメントの配列を返します。ほとんどのプロバイダーは NULL を返します。

この要素にフォーカスを設定します。

型: HRESULT

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

Microsoft UI Automation フレームワークは、このメソッドを呼び出す前に、このフラグメントをホストするインターフェイスの部分が既にフォーカスされていることを保証します。実装は、内部的なフォーカス状態のみを更新する必要があります。たとえば、フォーカスを持っていることを示すためにリスト項目を再描画するなどです。UI Automation が親ウィンドウにフォーカスを設定しないようにしたい場合は、フラグメントのルートに対して IRawElementProviderSimple::ProviderOptions の中で ProviderOptions_ProviderOwnsSetFocus を設定します。

フラグメントのルートノードを指定します。

フラグメントのルートのプロバイダーは、自身の IRawElementProviderFragmentRoot 実装へのポインターを返す必要があります。

例

次のリスト項目プロバイダーの実装例は、親リストボックスのプロバイダーを返します。

HRESULT STDMETHODCALLTYPE ListItemProvider::get_FragmentRoot(IRawElementProviderFragmentRoot** pRetVal)
{
    if (pRetVal == NULL) return E_INVALIDARG;
    IRawElementProviderFragmentRoot* pRoot = static_cast<IRawElementProviderFragmentRoot*>(m_parentProvider);
    pRoot->AddRef();
    *pRetVal = pRoot;
    return S_OK;
}