Win32 API 日本語リファレンス
ホーム › UI.Accessibility › IUIAutomationTreeWalker

IUIAutomationTreeWalker

COM
📘 Microsoft Learn (日本語) · English
IID4042c624-389c-4afc-a630-9df854a541fc継承元IUnknown自前メソッド開始 vtbl3

公式ドキュメント

UI Automation クライアントアプリケーションがデスクトップ上の UI Automation 要素を表示およびナビゲートするために使用するプロパティとメソッドを公開します。

解説(Remarks)

UI Automation クライアントは、デスクトップ上の要素をツリー構造に配置された IUIAutomation オブジェクトの集合として扱います。IUIAutomationTreeWalker インターフェイスを使用すると、クライアントアプリケーションはツリーのビューを選択し、GetFirstChildElement や GetNextSiblingElement などのメソッドを使って指定した方向に要素から要素へと移動することでナビゲートできます。

IUIAutomationTreeWalker を使ったツリーのナビゲーションはプロセス間呼び出しを引き起こす可能性があり、IUIAutomationElement::FindAll や IUIAutomationElement::FindFirst メソッドを使って要素を検索する場合ほど効率的ではありません。

クライアントアプリケーションが自身のユーザーインターフェイス内の要素を検索する可能性がある場合は、すべての UI Automation 呼び出しを別のスレッドで行う必要があります。

メソッド 13

vtbl = vtable インデックス(0始まり)。HSP等からCOMメソッドをインデックス指定で呼ぶ際に使用します。0〜2 は IUnknown。

vtbl 3 HRESULT GetParentElement(IUIAutomationElement* element, IUIAutomationElement** parent)

指定した UI Automation 要素の親要素を取得します。

elementIUIAutomationElement*in親を取得する対象の要素へのポインター。
parentIUIAutomationElement**out親要素へのポインターを受け取ります。親要素が存在しない場合は NULL を受け取ります。

戻り値

型: HRESULT

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

解説(Remarks)

Microsoft UI Automation ツリーの構造は、デスクトップ上に表示される UI 要素の変化に応じて変化します。親要素として返された要素が、以降のパスでも親として返される保証はありません。

vtbl 4 HRESULT GetFirstChildElement(IUIAutomationElement* element, IUIAutomationElement** first)

指定した UI Automation 要素の最初の子要素を取得します。

elementIUIAutomationElement*in最初の子を取得する対象の要素へのポインター。
firstIUIAutomationElement**out最初の子要素へのポインターを受け取ります。

戻り値

型: HRESULT

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

解説(Remarks)

要素は、現在のビュー条件に一致しないために要素ツリーのナビゲート時には返されない子要素を追加で持つことがあります。

Microsoft UI Automation ツリーの構造は、デスクトップ上に表示される UI 要素の変化に応じて変化します。最初の子要素として返された要素が、以降のパスでも最初の子として返される保証はありません。

vtbl 5 HRESULT GetLastChildElement(IUIAutomationElement* element, IUIAutomationElement** last)

指定した UI Automation 要素の最後の子要素を取得します。

elementIUIAutomationElement*in最後の子を取得する対象の要素へのポインター。
lastIUIAutomationElement**out最後の子要素へのポインターを受け取ります。

戻り値

型: HRESULT

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

解説(Remarks)

要素は、現在のビュー条件に一致しないために要素ツリーのナビゲート時には返されない子要素を追加で持つことがあります。

Microsoft UI Automation ツリーの構造は、デスクトップ上に表示される UI 要素の変化に応じて変化します。最後の子要素として返された要素が、以降のパスでも最後の子として返される保証はありません。

vtbl 6 HRESULT GetNextSiblingElement(IUIAutomationElement* element, IUIAutomationElement** next)

指定した UI Automation 要素の次の兄弟要素を取得します。

elementIUIAutomationElement*in次の兄弟を取得する対象の要素へのポインター。
nextIUIAutomationElement**out次の兄弟要素へのポインターを受け取ります。兄弟要素が存在しない場合は NULL を受け取ります。

戻り値

型: HRESULT

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

解説(Remarks)

要素は、現在のビュー条件に一致しないために要素ツリーのナビゲート時には返されない兄弟要素を追加で持つことがあります。

Microsoft UI Automation ツリーの構造は、デスクトップ上に表示される UI 要素の変化に応じて変化します。次の兄弟要素として返された要素が、以降のパスでも次の兄弟として返される保証はありません。

vtbl 7 HRESULT GetPreviousSiblingElement(IUIAutomationElement* element, IUIAutomationElement** previous)

指定した UI Automation 要素の前の兄弟要素を取得します。

elementIUIAutomationElement*in前の兄弟を取得する対象の要素へのポインター。
previousIUIAutomationElement**out前の兄弟要素へのポインターを受け取ります。兄弟要素が存在しない場合は NULL を受け取ります。

戻り値

型: HRESULT

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

解説(Remarks)

要素は、現在のビュー条件に一致しないために要素ツリーのナビゲート時には返されない兄弟要素を追加で持つことがあります。

Microsoft UI Automation ツリーの構造は、デスクトップ上に表示される UI 要素の変化に応じて変化します。前の兄弟要素として返された要素が、以降のパスでも前の兄弟として返される保証はありません。

vtbl 8 HRESULT NormalizeElement(IUIAutomationElement* element, IUIAutomationElement** normalized)

ツリービュー内で、指定した Microsoft UI Automation 要素に最も近い先祖要素を取得します。

elementIUIAutomationElement*in正規化を開始する起点となる要素へのポインター。
normalizedIUIAutomationElement**outツリービュー内で指定した要素に最も近い先祖要素へのポインターを受け取ります。

戻り値

型: HRESULT

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

解説(Remarks)

要素は、ビュー条件(以前の IUIAutomationTreeWalker::Condition の呼び出しで指定されたもの)を満たす要素に到達するまでツリー内の先祖チェーンを上方向にたどることで正規化されます。ただし最初に、渡された要素が正規化条件に一致するかどうかがテストされます。一致する場合は、渡された要素が先祖でなくてもその要素が返されます。

一致する要素が見つからない場合、このメソッドは UIA_E_ELEMENTNOTAVAILABLE を返します。

このメソッドは、ヒットテストによって UI Automation 要素への参照を取得するアプリケーションに役立ちます。アプリケーションは特定の種類の要素のみを扱いたい場合があり、IUIAutomationTreeWalker::Normalize を使用することで、最初にどの要素が取得されても(たとえばスクロールバーが入力フォーカスを得た場合など)、最終的に目的の要素(コンテンツ要素など)のみが取得されるようにできます。

vtbl 9 HRESULT GetParentElementBuildCache(IUIAutomationElement* element, IUIAutomationCacheRequest* cacheRequest, IUIAutomationElement** parent)

指定した UI Automation 要素の親要素を取得し、プロパティとコントロールパターンをキャッシュします。

elementIUIAutomationElement*in親を取得する対象の要素へのポインター。
cacheRequestIUIAutomationCacheRequest*in返される要素にキャッシュするプロパティとコントロールパターンを指定するキャッシュ要求へのポインター。
parentIUIAutomationElement**out親要素へのポインターを受け取ります。親要素が存在しない場合は NULL を受け取ります。

戻り値

型: HRESULT

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

解説(Remarks)

Microsoft UI Automation ツリーの構造は、デスクトップ上に表示される UI 要素の変化に応じて変化します。親要素として返された要素が、以降のパスでも親として返される保証はありません。

vtbl 10 HRESULT GetFirstChildElementBuildCache(IUIAutomationElement* element, IUIAutomationCacheRequest* cacheRequest, IUIAutomationElement** first)

指定した UI Automation 要素の最初の子要素を取得し、プロパティとコントロールパターンをキャッシュします。

elementIUIAutomationElement*in最初の子を取得する対象の要素へのポインター。
cacheRequestIUIAutomationCacheRequest*in返される要素にキャッシュするプロパティとコントロールパターンを指定するキャッシュ要求へのポインター。
firstIUIAutomationElement**out最初の子要素へのポインターを受け取ります。子要素が存在しない場合は NULL を受け取ります。

戻り値

型: HRESULT

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

解説(Remarks)

要素は、現在のビュー条件に一致しないために要素ツリーのナビゲート時には返されない子要素を追加で持つことがあります。

Microsoft UI Automation ツリーの構造は、デスクトップ上に表示される UI 要素の変化に応じて変化します。最初の子要素として返された要素が、以降のパスでも最初の子として返される保証はありません。

vtbl 11 HRESULT GetLastChildElementBuildCache(IUIAutomationElement* element, IUIAutomationCacheRequest* cacheRequest, IUIAutomationElement** last)

指定した UI Automation 要素の最後の子要素を取得し、プロパティとコントロールパターンをキャッシュします。

elementIUIAutomationElement*in最後の子を取得する対象の要素へのポインター。
cacheRequestIUIAutomationCacheRequest*in返される要素にキャッシュするプロパティとコントロールパターンを指定するキャッシュ要求へのポインター。
lastIUIAutomationElement**out最後の子要素へのポインターを受け取ります。子要素が存在しない場合は NULL を受け取ります。

戻り値

型: HRESULT

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

解説(Remarks)

要素は、現在のビュー条件に一致しないために要素ツリーのナビゲート時には返されない子要素を追加で持つことがあります。

Microsoft UI Automation ツリーの構造は、デスクトップ上に表示される UI 要素の変化に応じて変化します。最後の子要素として返された要素が、以降のパスでも最後の子として返される保証はありません。

vtbl 12 HRESULT GetNextSiblingElementBuildCache(IUIAutomationElement* element, IUIAutomationCacheRequest* cacheRequest, IUIAutomationElement** next)

指定した UI Automation 要素の次の兄弟要素を取得し、プロパティとコントロールパターンをキャッシュします。

elementIUIAutomationElement*in次の兄弟を取得する対象の要素へのポインター。
cacheRequestIUIAutomationCacheRequest*in返される要素にキャッシュするプロパティとコントロールパターンを指定するキャッシュ要求へのポインター。
nextIUIAutomationElement**out次の兄弟要素へのポインターを受け取ります。兄弟要素が存在しない場合は NULL を受け取ります。

戻り値

型: HRESULT

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

解説(Remarks)

要素は、現在のビュー条件に一致しないために要素ツリーのナビゲート時には返されない兄弟要素を追加で持つことがあります。

Microsoft UI Automation ツリーの構造は、デスクトップ上に表示される UI 要素の変化に応じて変化します。次の兄弟要素として返された要素が、以降のパスでも次の兄弟として返される保証はありません。

vtbl 13 HRESULT GetPreviousSiblingElementBuildCache(IUIAutomationElement* element, IUIAutomationCacheRequest* cacheRequest, IUIAutomationElement** previous)

指定した UI Automation 要素の前の兄弟要素を取得し、プロパティとコントロールパターンをキャッシュします。

elementIUIAutomationElement*in前の兄弟を取得する対象の要素へのポインター。
cacheRequestIUIAutomationCacheRequest*in返される要素にキャッシュするプロパティとコントロールパターンを指定するキャッシュ要求へのポインター。
previousIUIAutomationElement**out前の兄弟要素へのポインターを受け取ります。兄弟要素が存在しない場合は NULL を受け取ります。

戻り値

型: HRESULT

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

解説(Remarks)

要素は、現在のビュー条件に一致しないために要素ツリーのナビゲート時には返されない兄弟要素を追加で持つことがあります。

Microsoft UI Automation ツリーの構造は、デスクトップ上に表示される UI 要素の変化に応じて変化します。前の兄弟要素として返された要素が、以降のパスでも前の兄弟として返される保証はありません。

vtbl 14 HRESULT NormalizeElementBuildCache(IUIAutomationElement* element, IUIAutomationCacheRequest* cacheRequest, IUIAutomationElement** normalized)

ツリービュー内で、指定した Microsoft UI Automation 要素に最も近い先祖要素を取得し、要求されたプロパティとコントロールパターンをあらかじめ取得(プリフェッチ)して、プリフェッチした項目をキャッシュに格納します。

elementIUIAutomationElement*in正規化を開始する起点となる要素へのポインター。
cacheRequestIUIAutomationCacheRequest*in返される要素にキャッシュするプロパティとコントロールパターンを指定するキャッシュ要求へのポインター。
normalizedIUIAutomationElement**outツリービュー内で指定した要素に最も近い先祖要素へのポインターを受け取ります。

戻り値

型: HRESULT

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

解説(Remarks)

要素は、ビュー条件(以前の IUIAutomationTreeWalker::Condition の呼び出しで指定されたもの)を満たす要素に到達するまでツリー内の先祖チェーンを上方向にたどることで正規化されます。ルート要素に到達した場合は、ビュー条件を満たさなくてもルート要素が返されます。

このメソッドは、ヒットテストによって UI Automation 要素への参照を取得するアプリケーションに役立ちます。アプリケーションは特定の種類の要素のみを扱いたい場合があり、IUIAutomationTreeWalker::NormalizeElement を使用することで、最初にどの要素が取得されても(たとえばスクロールバーが入力フォーカスを得た場合など)、最終的に目的の要素(コンテンツ要素など)のみが取得されるようにできます。

vtbl 15 HRESULT get_Condition(IUIAutomationCondition** condition)

UI Automation ツリーのビューを定義する条件を取得します。

conditionIUIAutomationCondition**outこのツリーウォーカーがビューを定義するために使用する条件を受け取るインターフェイスポインタへのポインタである。
出典・ライセンス: 上記「公式ドキュメント」の内容は Microsoft の Win32 API ドキュメント(MicrosoftDocs/sdk-api)を日本語に翻訳・改変したものです。© Microsoft Corporation. CC BY 4.0 で提供。
Microsoft 公式リファレンス: 英語 (en-us) · 日本語 (ja-jp) · 原文ソース (GitHub)

HSP用 COM定義

#usecom / #comfunc によるHSPのCOM呼び出し定義。数字は vtbl インデックス(0始まり)。クラスIDが無い場合 #usecom の末尾は "{}"、ある場合は "{CLSID}"。

#define global IID_IUIAutomationTreeWalker "{4042C624-389C-4AFC-A630-9DF854A541FC}"
#usecom global IUIAutomationTreeWalker IID_IUIAutomationTreeWalker "{}"
#comfunc global IUIAutomationTreeWalker_GetParentElement                     3 sptr,sptr
#comfunc global IUIAutomationTreeWalker_GetFirstChildElement                 4 sptr,sptr
#comfunc global IUIAutomationTreeWalker_GetLastChildElement                  5 sptr,sptr
#comfunc global IUIAutomationTreeWalker_GetNextSiblingElement                6 sptr,sptr
#comfunc global IUIAutomationTreeWalker_GetPreviousSiblingElement            7 sptr,sptr
#comfunc global IUIAutomationTreeWalker_NormalizeElement                     8 sptr,sptr
#comfunc global IUIAutomationTreeWalker_GetParentElementBuildCache           9 sptr,sptr,sptr
#comfunc global IUIAutomationTreeWalker_GetFirstChildElementBuildCache       10 sptr,sptr,sptr
#comfunc global IUIAutomationTreeWalker_GetLastChildElementBuildCache        11 sptr,sptr,sptr
#comfunc global IUIAutomationTreeWalker_GetNextSiblingElementBuildCache      12 sptr,sptr,sptr
#comfunc global IUIAutomationTreeWalker_GetPreviousSiblingElementBuildCache  13 sptr,sptr,sptr
#comfunc global IUIAutomationTreeWalker_NormalizeElementBuildCache           14 sptr,sptr,sptr
#comfunc global IUIAutomationTreeWalker_get_Condition                        15 sptr
; ※数字は vtbl インデックス(0始まり)。0/1/2 は IUnknown(QueryInterface/AddRef/Release)。
; ※このインターフェースは直接 CoCreateInstance するクラスIDが無いため "{}"(他メソッド/アクティベーションで取得)。
; ※ハンドル/void*等の不透明ポインタは IronHSP では intptr 指定が可能。