UI オートメーション要素の取得
このトピックでは、UI 要素の IUIAutomationElement インターフェイスを取得するさまざまな方法について説明します。
IUIAutomationElement は、UI オートメーション ドキュメント コンテンツ クライアント サンプル アプリで使われます。
Root 要素
IUIAutomation::GetFocusedElement などのメソッドを使って要素を直接取得することはできますが、一部のクライアント アプリケーションでは、UI オートメーション ツリーと呼ばれる要素の階層構造のビューが必要です。 この階層のルート要素はデスクトップです。 この要素は、IUIAutomation::GetRootElement メソッドまたは IUIAutomation::GetRootElementBuildCache メソッドを使って取得できます。 どちらのメソッドも、IUIAutomationElement インターフェイス ポインターを取得します。 IUIAutomationElement::FindFirst や FindAll などのメソッドを使って、子孫要素を検索できます。
Note
一般に、取得を試みるのは、ルート要素の直接の子だけにする必要があります。 子孫を検索すると、数百または数千の要素の反復処理になる可能性があります。 下位レベルの特定の要素を取得しようとする場合、アプリケーション ウィンドウから、または下位レベルのコンテナーから検索を開始する必要があります。
条件
UI オートメーション要素の取得に使うほとんどの手法では、条件を指定する必要があります。 条件は、取得する要素を定義する基準のセットです。 条件は、IUIAutomationCondition インターフェイスによって表されます。
最も単純な条件である true 条件は、検索範囲内のすべての要素を返すように指定する定義済みのオブジェクトです。 false 条件は true 条件の逆であり、要素が見つからないようにするものなので、あまり役に立ちません。 IUIAutomation::CreateTrueCondition を使って、true 条件へのインターフェイスを取得できます。
IUIAutomation オブジェクトのプロパティとして使用できる定義済み条件として他に次の 3 つがあり、単独で、または他の条件と組み合わせて使用できます: IUIAutomation::ContentViewCondition、ControlViewCondition、RawViewCondition。 RawViewCondition は、単独で使われ、IUIAutomationElement::CurrentIsControlElement または CurrentIsContentElement プロパティによって要素をフィルター処理しないため、true 条件と同等です。
その他の条件は、それぞれがプロパティ値を指定する条件オブジェクトから作成されます。 たとえば、プロパティ条件では、要素が有効であることや、特定の制御パターンをサポートすることを指定することがあります。
ブール ロジックを使う条件は、IUIAutomation::CreateAndCondition、CreateOrCondition、CreateNotCondition、および関連メソッドを呼び出すことによって結合できます。
検索範囲
IUIAutomationElement::FindFirst または FindAll を使って実行される検索には、検索範囲と開始場所が必要です。
Note
これら 2 つのメソッドに関する説明は、IUIAutomationElement::FindFirstBuildCache と FindAllBuildCache にも当てはまります。
検索範囲では、開始位置の周囲の検索する領域を定義します。 これには、要素自体、兄弟、親、直接の子、子孫が含まれる場合があります。 Find メソッドでは、Microsoft UI オートメーション ツリーの上方への検索はサポートされていないことに注意してください。つまり、先祖要素は検索できません。
検索の範囲は、TreeScope 列挙型の値のビットごとの組み合わせによって定義されます。
既知の要素の検索
名前、オートメーション ID、またはその他のプロパティやプロパティの組み合わせによって識別される既知の要素を検索するには、IUIAutomationElement::FindFirst メソッドを使うのが最も簡単です。 検索対象の要素がアプリケーション ウィンドウの場合、検索の開始場所をルート要素にすることができます。
UI オートメーション要素を検索するこの方法は、自動化されたシナリオ テストの最も有用な方法になります。
既知の要素を検索する方法を示すコードの例については、「名前による要素の検索」をご覧ください。
サブツリー内の要素の検索
特定の条件を満たし、既知の要素に関連するすべての要素を検索するには、既知の要素に対して IUIAutomationElement::FindAll を呼び出すことができます。 たとえば、リストまたはメニューからリスト アイテムまたはメニュー項目を取得したり、ダイアログ ボックス内のすべてのコントロールを識別したりするには、このメソッドを使います。
サブツリー内の要素を検索する方法を示すコードの例については、「関連する要素の検索」をご覧ください。
サブツリーのウォーク
クライアントを使われる可能性があるアプリケーションに関する予備知識がない場合は、IUIAutomationTreeWalker を使って、対象となるすべての要素のサブツリーを構築できます。 たとえば、フォーカス変更イベントに応答して、クライアントでこれを行う場合があります。つまり、アプリケーションまたはコントロールが入力フォーカスを受け取ったら、UI オートメーション クライアントでフォーカスを受け取った要素の子と、おそらくすべての子孫を調べます。
UI オートメーション ツリーを走査すると大量のリソースが消費されることに注意してください。 ツリーの走査は、IUIAutomationElement::FindFirst、FindAll、または BuildUpdatedCache メソッドを使ったのではできない場合にのみ行うようにします。
IUIAutomation::CreateTreeWalker にカスタム条件を渡すことで、独自のツリー走査機能を定義できます。または基底の IUIAutomation のプロパティとして定義されている次のいずれかの定義済みオブジェクトを使用できます。
| オブジェクト | 目的 |
|---|---|
| ContentViewWalker | IUIAutomationElement::CurrentIsContentElement プロパティが TRUE である要素のみを検索します。 |
| ControlViewWalker | IUIAutomationElement::CurrentIsControlElement プロパティが TRUE である要素のみを検索します。 |
| RawViewWalker | すべての要素を検索します。 |
IUIAutomationTreeWalker を取得した後、IUIAutomationTreeWalker::GetXxx メソッドを呼び出してサブツリーの要素間を移動し、走査を開始する要素を渡します。
IUIAutomationTreeWalker::Normalize メソッドは、ビューの一部ではない別の要素からサブツリー内の要素に移動するために使用できます。 たとえば、IUIAutomation::ContentViewWalker を使ってサブツリーのビューを作成するとします。 アプリケーションは、スクロール バーが入力フォーカスを受け取ったという通知を受け取ります。 スクロール バーはコンテンツ要素ではないため、サブツリーのビューには存在しません。 しかし、スクロール バーを表す IUIAutomationElement を IUIAutomationTreeWalker::Normalize に渡して、コンテンツ ビュー内の最も近い先祖を取得できます。
IUIAutomationTreeWalker インターフェイスの使い方を示すコードの例については、「UI オートメーション ツリーを走査する方法」をご覧ください。
要素を取得する別の方法
検索とナビゲーションに加えて、次の方法で IUIAutomationElement を取得できます。
イベントから
アプリケーションが UI オートメーション イベントを受け取ったとき、イベント ハンドラーに渡されるソース オブジェクトは、IUIAutomationElement によって表されます。 たとえば、フォーカス変更イベントをサブスクライブしている場合、IUIAutomationFocusChangedEventHandler に渡されるソースは、フォーカスを受け取った要素です。 詳しくは、「UI オートメーション イベントへのサブスクライブ」をご覧ください。
ポイントから
画面の座標 (カーソル位置など) から IUIAutomationElement を取得するには、IUIAutomation::ElementFromPoint メソッドを使います。
ウィンドウ ハンドルから
HWND から IUIAutomationElement を取得するには、IUIAutomation::ElementFromHandle メソッドを使います。
フォーカスされたコントロールから
フォーカスが設定されているコントロールを表す IUIAutomationElement を取得するには、IUIAutomation::GetFocusedElement メソッドを使います。