UI オートメーション クライアント アプリケーションの作成

ルート要素

UI オートメーション ツリーのルート要素はデスクトップです。この要素は、IUIAutomation::GetRootElement メソッドまたは IUIAutomation::GetRootElementBuildCache メソッドのいずれかを呼び出すことで取得できます。どちらのメソッドも IUIAutomationElement インターフェイス ポインターを取得します。その後、IUIAutomationTreeWalker メソッドを呼び出してツリーを下位方向に移動したり、他のメソッド (IUIAutomationElement::FindFirst や IUIAutomationElement::FindAll など) を呼び出して子孫要素を検索したりできます。

座標位置から

画面座標 (この例のカーソル位置など) がわかっている場合は、IUIAutomation::ElementFromPoint メソッドを呼び出して、IUIAutomationElement インターフェイスを取得できます。

ウィンドウ ハンドルから

ウィンドウ ハンドル (HWND) から IUIAutomationElement インターフェイスを取得するには、IUIAutomation::ElementFromHandle メソッドを呼び出します。

フォーカスが設定されたコントロールから

IUIAutomation::GetFocusedElement メソッドを呼び出すことで、フォーカスが設定されているコントロールを表す IUIAutomationElement インターフェイスを取得できます。

プロパティを取得する

一部ジェネリック プロパティとコントロール パターンのすべてのプロパティは、IUIAutomationElement インターフェイスまたはコントロール パターンのインターフェイスのプロパティとして使用でき、IUIAutomationElement::get_CurrentName や IUIAutomationDockPattern::get_CachedDockPosition などのアクセサー メソッドを使用して取得できます。

また、次に示すメソッドによって、現在のプロパティまたはキャッシュされたプロパティを取得できます。

• IUIAutomationElement::GetCurrentPropertyValue
• IUIAutomationElement::GetCurrentPropertyValueEx
• IUIAutomationElement::GetCachedPropertyValue
• IUIAutomationElement::GetCachedPropertyValueEx

これらのメソッドにより、あらゆるプロパティにアクセスできます。ただし、これらのメソッドでは値が VARIANT 構造体で返されるのに対し、個別のプロパティのアクセサーでは、返される値が適切な型にキャストされます。

プロパティとその詳細の完全な一覧については、「UI オートメーションの仕様と Community Promise」を参照してください。

プロパティ ID

ジェネリック アクセサー メソッドを使用するときは、UIAutomationClient.h で定義されたプロパティ ID を使用してプロパティを指定することも必要です。この ID は、プロパティ値の取得時、プロパティ条件の構築時、およびプロパティ変更イベントの購読時に、プロパティを指定するために使用します。

プロパティの既定値

UI オートメーション プロバイダーがプロパティを実装していない場合、UI オートメーション システムでは、そのプロパティの既定値を提供できます。たとえば、コントロールのプロバイダーが、UIA_HelpTextPropertyId というプロパティ ID で識別されるプロパティをサポートしていなければ、UI オートメーションは空文字列を返します。同様に、プロバイダーが UIA_IsDockPatternAvailablePropertyId で識別されるプロパティをサポートしていなければ、UI オートメーションは FALSE を返します。

IUIAutomationElement::GetCurrentPropertyValue メソッドと IUIAutomationElement::GetCurrentPropertyValueEx メソッドの違い (または同様のメソッド ペアの違い) は、後者のメソッドでは既定値が返されないように指定できる点にあります。既定値が返されない場合の戻り値は、プロパティがサポートされていないことを示す特殊な一意の定数になります。この値を受け取るときに、アプリケーションでは独自の値を提供するか、単純にプロパティを無視することができます。

HRESULT InvokeElement(IUIAutomationElement *pElement)

{

    IUIAutomationInvokePattern * pInvoke;

    HRESULT hr = pElement->GetCurrentPatternAs(UIA_InvokePatternId,

                 __uuidof(IUIAutomationInvokePattern),

                 (void **)&pInvoke);

    if(FAILED(hr) || pInvoke == NULL)

    {

        return hr;

    }

    hr = pInvoke->Invoke();

    pInvoke->Release();

    return hr;

}

この例で IUIAutomationElement::GetCurrentPatternAs メソッドを使用しているのは、このメソッドでは QueryInterface メソッドが使用されるためです。

次のさらに複雑な例では、RangeValue パターンを使用して、コントロール (音量スライダーなど) を最大値に設定します。

HRESULT TurnItUp(IUIAutomationElement *pElement)

{

    IUIAutomationRangeValuePattern * pRangeVal;

    HRESULT hr = pElement->GetCurrentPatternAs(UIA_RangeValuePatternId,

                 __uuidof(IUIAutomationRangeValuePattern),

                 (void **)&pRangeVal);

    if(FAILED(hr) || pRangeVal == NULL)

    {

        return hr;

    }

    double max;

    hr = pRangeVal->get_CurrentMaximum(&max);

    if(SUCCEEDED(hr))

    {

        hr = pRangeVal->SetValue(max);

    }

    pRangeVal->Release();

    return hr;

}

上記の例ではどちらも、現在のパターンの取得時にエラーをチェックしているだけでなく、NULL もチェックしています。これは、NULL が、要求されたパターンをコントロールがサポートしていないときの有効な戻り値であるためです。

Find 系のメソッドを使用する

Find 系のメソッドでは、親要素、検索スコープ、および検索条件 (最も重要) の 3 つが必要です。条件は、CUIAutomation オブジェクトのさまざまな API を呼び出して作成します。単純なプロパティ条件を作成できます。また、それらの条件を And、Or、および Not の各演算子と組み合わせて、より複雑な条件を作成することもできます。

条件を作成したら、検索の開始要素と、検索スコープを指定する必要があります。FindFirst メソッドまたは FindAll メソッドを呼び出す要素が、検索の開始要素です。通常、検索スコープには、要素自体、要素の子、または要素の子孫の 3 つのうち、1 つを選択します。一般に、検索スコープはできるだけ限定して、パフォーマンスを向上し、検索対象ではない要素が検出される機会を減らします。

次の検索例では、FindFirst メソッドを使用して、名前付きのアプリケーション ウィンドウを検索しています。この例では、検索条件 (特定の名前) が非常に単純です。もちろん、条件を大幅に複雑にすることもできます。

IUIAutomationElement* GetTopLevelWindowByName(LPWSTR windowName)

{

    if (!windowName)

    {

        return NULL;

    }

    IUIAutomationElement* pRoot;

    IUIAutomationElement* pFound;

    VARIANT varProp;

    varProp.vt = VT_BSTR;

    varProp.bstrVal = SysAllocString(windowName);



    // デスクトップ要素を取得します。

    HRESULT hr = g_pAutomation->GetRootElement(&pRoot);



    // トップレベル要素を ("Program Manager" などの) 名前で取得します。

    if (pRoot)

    {

        IUIAutomationCondition* pCondition;

        g_pAutomation->CreatePropertyCondition(UIA_NamePropertyId, varProp, 

            &pCondition);

        pRoot->FindFirst(TreeScope_Children, pCondition, &pFound);

        pRoot->Release();

        pCondition->Release();

    }

    VariantClear(&varProp);

    return pFound;

}

次の例では、ボタン以外の呼び出し可能なコントロールをすべて検出するという、複雑な条件を示します。

IUIAutomationCondition * GetInvokableNonButtonCondition()

{

    IUIAutomationCondition* pInvokableCondition;

    IUIAutomationCondition* pButtonCondition;

    IUIAutomationCondition* pNotButtonCondition;

    IUIAutomationCondition* pInvokableNotButtonCondition;



    // ボタン コントロール型のプロパティ条件を作成します。

    VARIANT varProp;

    varProp.vt = VT_I4;

    varProp.lVal = UIA_ButtonControlTypeId;

    g_pAutomation->CreatePropertyCondition(UIA_ControlTypePropertyId, varProp,

        &pButtonCondition);



    // InvokePattern をチェックするプロパティ条件を作成します。

    varProp.vt = VT_BOOL;

    varProp.boolVal = VARIANT_TRUE;

    g_pAutomation->CreatePropertyCondition(UIA_IsInvokePatternAvailablePropertyId,

        varProp, &pInvokableCondition);



    // ボタンに対する Not 条件を作成します。

    g_pAutomation->CreateNotCondition(pButtonCondition, &pNotButtonCondition);



    // 条件を組み合わせます。

    g_pAutomation->CreateAndCondition(pNotButtonCondition, pInvokableCondition,

        (&pInvokableNotButtonCondition);



    pInvokableCondition->Release();

    pButtonCondition->Release();

    pNotButtonCondition->Release();

    return pInvokableNotButtonCondition;

}

次のような理由から、FindFirst メソッドと FindAll メソッドのどちらを選択するかも重要になります。

• FindFirst では、検索で最初に一致する要素が返されます。これは、要素を 1 つだけ検索する (またはその必要がある) 場合に使用します。
• FindAll では、スコープ内で一致するすべての要素が検索されるまで続行されます。これは、一致する要素のコレクションが必要な場合に使用します。

注: 一般に、ルート要素から検索を開始する場合は、検索のスコープが子要素のみに限定されます。子孫やサブツリーを検索すると、要素の検索が数百回または数千回も繰り返される場合があるため、スタック オーバーフローが発生する可能性があります。下位レベルにある特定の要素を取得する場合は、アプリケーション ウィンドウまたは下位レベルのコンテナーから検索を開始します。

IUIAutomationTreeWalkers を使用する

ツリー全体をナビゲートするもう 1 つの方法は、ツリー ウォーカーを使用することです。ツリー ウォーカーでは、親、子、および兄弟ノードを移動するような、直接的なナビゲーション メソッドを使用して、ツリーのフィルター ビューをスキャンできます。組み込みのフィルター ビューには、次のようなものがあります。

• 未加工 (フィルターなし): すべての要素が表示されます。
• コントロール ビュー (既定値): 冗長な要素、またはレイアウト目的のみで使用される要素を除外します。
• コンテンツ ビュー: コントロール ビューよりもさらに選択的にコントロールをフィルター選択します。

ユーザーは、条件付きの独自のカスタム ビューを作成することもできます。

ツリーのスキャンは、探索アプリケーションによって行われます。また、特定要素の検出が困難でも、その要素に既知の安定したリレーションシップ (子や親など) が比較的見つかりやすい場合にも使用されます。

次の簡単な例では、pElement によって参照されるコントロールの最初の子要素までたどる方法を示します。

// コントロール ビュー ウォーカーを取得します。

IUIAutomationTreeWalker * pWalk;  

g_pAutomation->get_ControlViewWalker(&pWalk);



// 要素の最初の子要素に移動します。

IUIAutomationElement * pFirst;

pWalk->GetFirstChildElement(pElement, &pFirst);

キャッシュを要求する

キャッシュを要求するのは簡単です。CUIAutoamation::CreateCacheRequest メソッドを呼び出して空のキャッシュを取得してから、プロパティおよびパターンをこのキャッシュに追加します。必要に応じて、スコープやフィルター処理したツリーを追加して、要素のサブツリーの一部またはすべてをフェッチすることもできます。

キャッシュされているデータを取得する

キャッシュを設定したら、キャッシュを構築するメソッドの 1 つを呼び出すか、IUIAutomationElement::BuildUpdatedCache メソッドを呼び出せば、キャッシュされたプロパティ、パターン、および (場合によっては) 子要素全体が含まれているオートメーション要素が提供されます。このデータにはほぼ通常どおりにアクセスできます。ただし、IUIAutomationElement::get_CachedName、IUIAutomationElement::GetCachedPropertyValue、IUIAutomationElement::GetCachedPattern など、キャッシュ バージョンのメソッドを使用します。子要素またはサブツリーをキャッシュしている場合は、操作に大きな違いがあります。つまり、Find 系のメソッドやツリー ウォーカーを使用してナビゲートするのではなく、IUIAutomationElement::GetCachedParent メソッドおよび IUIAutomationElement::GetCachedChildren メソッドを使用します。

例

次の関数例では、キャッシュのさまざまな機能を示しています。この関数は、SelectionItem パターンをサポートする特定の要素の子要素すべての、Name パターンと SelectionItem パターンをプリフェッチします。その後、子要素全体をスキャンして、それぞれのキャッシュされた Name をチェックします。"T" という文字で始まる名前を持つすべての子要素を、Selection に追加します (この例のデザインは、リスト ボックスまたはリスト ビュー コントロールに最も適しています)。

HRESULT SelectT(IUIAutomationElement *pElement)

{

    IUIAutomationCacheRequest * pCacheReq;

    g_pAutomation->CreateCacheRequest(&pCacheReq);

    pCacheReq->AddProperty(UIA_NamePropertyId);

    pCacheReq->AddPattern(UIA_SelectionItemPatternId);

    pCacheReq->put_TreeScope(TreeScope_Children);



    // SelectionItem パターンをチェックするプロパティ条件を作成します。

    VARIANT varProp;

    varProp.vt = VT_BOOL;

    varProp.boolVal = VARIANT_TRUE;

    IUIAutomationCondition* pSelectableCondition;

    g_pAutomation->CreatePropertyCondition(

        UIA_IsSelectionItemPatternAvailablePropertyId,

        varProp, &pSelectableCondition);



    // そのプロパティをツリー フィルターとして設定します。

    pCacheReq->put_TreeFilter(pSelectableCondition);

    pSelectableCondition->Release();



    IUIAutomationElement * pCachedElement;

    HRESULT hr = pElement->BuildUpdatedCache(pCacheReq, &pCachedElement);

    if(FAILED(hr))

        return hr;

    pCacheReq->Release();



    // 先ほどプリフェッチした子要素を取得します。

    IUIAutomationElementArray *pCachedChildren;

    hr = pCachedElement->GetCachedChildren(&pCachedChildren);

    if(FAILED(hr) || pCachedChildren == NULL)

        return hr;



    int length;

    hr = pCachedChildren->get_Length(&length);

    if(FAILED(hr))

        return hr;



    // 子要素の配列全体を順番に処理します。

    for(int i = 0; i < length; i++)

    {

        IUIAutomationElement * pCachedChild;

        hr = pCachedChildren->GetElement(i, &pCachedChild);

        if(FAILED(hr) || pCachedChild == NULL)

            return hr;



        BSTR name;

        hr = pCachedChild->get_CachedName(&name);

        if(FAILED(hr))

            return hr;



        // 要素の名前が "T" で始まるものを選択します。

        if(name[0] == L'T')

        {

            IUIAutomationSelectionItemPattern * pSelectionItem;

            HRESULT hr = pCachedChild->GetCachedPatternAs(

                UIA_SelectionItemPatternId,

                __uuidof(IUIAutomationSelectionItemPattern),

                (void **)&pSelectionItem);

            if(SUCCEEDED(hr) && pSelectionItem != NULL)

            {

                pSelectionItem->AddToSelection();

                pSelectionItem->Release();

            }

        }

        

        SysFreeString(name);

        pCachedChild->Release();

    }



    pCachedChildren->Release();

    pCachedElement->Release();

    return S_OK;

}

イベントを購読する

クライアント アプリケーションは、AddAutomationEventHandler や AddFocusChangedEventHandler などのメソッドを使用してイベント ハンドラーに登録することによって、特定の種類のイベントを購読します。これらのメソッドでは、コールバック インターフェイスを受け取り、クライアントによって作成されるオブジェクトに実装します。その後、IUIAutomationEventHandler::HandleEvent などのメソッドが、イベントの発生時に適切なスレッドで呼び出されます。

シャットダウン時、または UI オートメーション イベントがアプリケーションの購読対象ではなくなったとき、UI オートメーション クライアントがイベントを削除します。クライアントは、RemoveAutomationEventHandler や RemoveFocusChangedEventHandler などの具体的な削除用メソッドを呼び出すか、すべてのイベントを削除する RemoveAllEventHandlers メソッドを呼び出します。

例

次のコード例では、IUIAutomationFocusChangedEventHandler インターフェイスを実装するクラスの宣言を示します。

class CFocusHandler : IUIAutomationFocusChangedEventHandler

{

public:

    CFocusHandler(void);

    ~CFocusHandler(void);



    // IUnknown メソッド

    ULONG STDMETHODCALLTYPE AddRef();

    ULONG STDMETHODCALLTYPE Release();

    HRESULT STDMETHODCALLTYPE QueryInterface(REFIID riid, void**ppInterface);



    // IUIAutomationFocusChangedEventHandler メソッド

    HRESULT STDMETHODCALLTYPE HandleFocusChangedEvent(IUIAutomationElement *sender);



    DWORD _refCount;

};

オブジェクトの IUIAutomationFocusChangedEventHandler::HandleFocusChangedEvent メソッド実装では、次の呼び出しが行われた後のすべてのフォーカス変更イベントが通知されます。

HRESULT AddFocusHandler(IUIAutomation* pAutomation)

{ 

    // CFocusHandler は次のインターフェイスを実装するクラスです。

    // IUIAutomationFocusChangedEventHandler

    CFocusHandler* pFocusHandler = new CFocusHandler();

    if (!pFocusHandler)

    {

        return E_OUTOFMEMORY;

    }

    IUIAutomationFocusChangedEventHandler* pHandler;

    pFocusHandler->QueryInterface(IID_IUIAutomationFocusChangedEventHandler, (void**)&pHandler);

    HRESULT hr = pAutomation->AddFocusChangedEventHandler(NULL, pHandler);

    pFocusHandler->Release();

    return hr;

}

プログラムからのアクセス

プログラムによるアクセスでは、従来のマウス入力やキーボード入力によって行われる相互作用や操作性を、コードで模倣する機能が提供されます。UI オートメーションは、次の 5 つのコンポーネントによりプログラムからのアクセスを可能にします。

• UI オートメーション ツリーは、UI 構造全体のナビゲーションを容易にします。ツリーは、ウィンドウ ハンドルのコレクションから構築されます。詳細については、http://msdn.microsoft.com/ja-jp/library/ms741931(VS.80).aspx を参照してください。
• オートメーションの各要素が、UI の個別のコンポーネントです。これらの要素は、多くの場合、ウィンドウ ハンドルよりも細かくなります。
• オートメーションのプロパティが、UI 要素に関する具体的な情報を提供します。詳細については、http://msdn.microsoft.com/ja-jp/library/ms752056.aspx を参照してください。
• コントロールのパターンが、コントロールの機能の特定の側面を定義します。パターンは、プロパティ、メソッド、イベント、および構造体に関する情報から構成することができます。詳細については、http://msdn.microsoft.com/ja-jp/library/ms752362.aspx を参照してください。
• オートメーションのイベントが、イベント通知と情報を提供します。詳細については、http://msdn.microsoft.com/ja-jp/library/ms748252(VS.80).aspx を参照してください。

自動テスト向けの主なプロパティ

UI 内の任意のコントロールを一意に識別して検索する機能は、自動テスト アプリケーションがその UI を処理する基盤となります。クライアントとプロバイダーによって使用されるいくつかの UI オートメーション プロパティが、この識別と検索を支援します。

注: AutomationId プロパティでは、オートメーション ツリー全体が一意に識別されるとは限りません。たとえば、アプリケーションには、複数のトップレベルのメニュー項目を持つメニュー コントロールが含まれ、さらに、それらのメニュー項目に複数の子メニュー項目が含まれている場合があります。これらの二次的なメニュー項目は、Item1、Item2、Item3 といった汎用的な手法で識別されることがあり、トップレベルのメニュー項目の間では、子項目の ID が重複してもかまいません。

UI オートメーション クライアントで倍率を変換する

UI オートメーション では論理座標を使用しません。次のメソッドとプロパティは、物理座標を返すか、物理座標をパラメーターとして受け取ります。

• IUIAutomation::ElementFromPoint
• IUIAutomation::ElementFromPointBuildCache
• IUIAutomationElement::GetClickablePoint
• IUIAutomationElement::CurrentBoundingRectangle
• IUIAutomationElement::CachedBoundingRectangle
• IRawElementProviderFragment::BoundingRectangle

既定では、96 dpi 以外の画面解像度で実行されている UI オートメーション アプリケーションは、これらのメソッドとプロパティから正しい結果を取得できません。たとえば、カーソル位置は論理座標で表現されるため、クライアントはこれらの座標を単に IUIAutomation::ElementFromPoint メソッドに渡すだけでは、カーソルの下にある要素を取得できません。また、アプリケーションは、クライアント領域外にはウィンドウを正しく配置できません。

この解決方法は次の 2 つの部分から構成されます。

• 起動時に Win32 関数の SetProcessDPIAware を呼び出して、クライアント アプリケーションに画面の解像度を認識させます。この関数は、プロセス全体に画面解像度を認識させます。そのため、プロセスに属しているすべてのウィンドウは倍率変換されません。
• GetPhysicalCursorPos 関数を呼び出して、現在のカーソルの座標を取得します。

ユーザー アカウント制御

Windows Vista で導入された革新的なセキュリティ機能の中に、標準ユーザー (管理者以外のユーザー) として実行していても、管理者権限を必要とするアプリケーションやサービスの実行が必ずしもブロックされない機能があります。

大部分のアプリケーションには、標準トークンまたは管理者トークンのいずれかが付与されます。アプリケーションを管理者アプリケーションとして識別できない場合、既定ではそのアプリケーションが標準アプリケーションとして起動されます。管理者アプリケーションとして識別されたアプリケーションが起動される場合、オペレーティング システムは、起動前に、権限を昇格してアプリケーションを実行するかどうかユーザーに同意を求めます。ユーザーがローカル管理者グループのメンバーであっても、同意を求めるメッセージが既定で表示されます。これは、実行に管理者資格が必要なアプリケーションやシステム コンポーネントが実行の許可を求めるまでは、管理者であっても、標準ユーザーとして実行されているためです。

高いユーザー権利が必要なタスク

管理者特権が必要なタスクを実行しようとすると、Windows Vista および Windows 7 では、続行するかどうかを確認するダイアログ ボックスが表示されます。このダイアログ ボックスはプロセス間通信から保護されているため、悪質なソフトウェアによってユーザー入力のシミュレーションが行われることはありません。同様に、通常、他のプロセスからデスクトップ ログオン画面にアクセスすることはできません。

UI オートメーション クライアントは、他のプロセスと通信する必要がありますが、一部のプロセスは高いレベルのユーザー権限で実行されている可能性があります。また、クライアントでは、通常は他のプロセスには表示されないシステム ダイアログ ボックスへのアクセスが必要になる場合があります。したがって、UI オートメーション クライアントはシステムによって信頼され、特別なユーザー権利で実行される必要があります。

高いレベルのユーザー権利で実行されているアプリケーションと通信できるように信頼されるには、アプリケーションに署名する必要があります。

マニフェスト ファイル

保護されたシステムの UI にアクセスするには、特別な属性を含むマニフェスト ファイルを備えたアプリケーションをビルドする必要があります。この UIAccess 属性は、次のように <requestedExecutionLevel> タグに含まれます。

<trustInfo xmlns="urn:0073chemas-microsoft-com:asm.v3"> 

    <security> 

        <requestedPrivileges> 

        <requestedExecutionLevel 

            level="highestAvailable" 

            UIAccess="true" /> 

        </requestedPrivileges> 

    </security> 

</trustInfo>

(このコードの level 属性の値は、単なる一例です)。

UIAccess 属性の値は、既定で "false" に設定されます。つまり、この属性を省略した場合、またはアセンブリのマニフェストが存在しない場合、アプリケーションは保護された UI にアクセスできません。