ホーム › UI.Accessibility › IUIAutomationTextPattern

IUIAutomationTextPattern

COM

📘 Microsoft Learn (日本語) · English

IID32eba289-3583-42c9-9c59-3b6d9a1e9b6a継承元IUnknown自前メソッド開始 vtbl3

公式ドキュメント

テキストを含むコントロールへのアクセスを提供します。

メソッド 6

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

vtbl 3 HRESULT RangeFromPoint(POINT pt, IUIAutomationTextRange** range)

指定されたスクリーン座標に最も近い、退化した(空の)テキスト範囲を取得します。(IUIAutomationTextPattern.RangeFromPoint)

pt	POINT	in	位置をスクリーン座標で含む構造体です。
range	IUIAutomationTextRange**	out	指定された位置に最も近い退化したテキスト範囲へのポインターを受け取ります。

戻り値

型: HRESULT

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

解説(Remarks)

スクリーン座標が画像、ハイパーリンク、Microsoft Excel スプレッドシート、またはその他の埋め込みオブジェクトの座標内にある場合は、子オブジェクトを囲むテキスト範囲が返されます。

非表示のテキストは無視されないため、このメソッドは指定された座標に最も近い可視テキストから退化した範囲を取得します。

Windows Internet Explorer 9 における RangeFromPoint の実装は、期待される結果を返しません。代わりに、クライアントは次の手順を実行する必要があります。

GetVisibleRanges メソッドを呼び出して、可視テキスト範囲の配列を取得します。
配列内の各テキスト範囲について、IUIAutomationTextRange::GetBoundingRectangles を呼び出して外接矩形を取得します。
外接矩形を調べて、特定のスクリーン座標を占めるテキスト範囲を見つけます。

vtbl 4 HRESULT RangeFromChild(IUIAutomationElement* child, IUIAutomationTextRange** range)

画像、ハイパーリンク、Microsoft Excel スプレッドシート、またはその他の埋め込みオブジェクトなどの子要素を囲むテキスト範囲を取得します。

child	IUIAutomationElement*	in	テキスト範囲に囲まれる子要素へのポインターです。
range	IUIAutomationTextRange**	out	子要素を囲むテキスト範囲へのポインターを受け取ります。

戻り値

型: HRESULT

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

解説(Remarks)

子要素を囲む範囲にテキストが存在しない場合は、退化した(空の)範囲が返されます。

child パラメーターは、IUIAutomationTextPattern に関連付けられた要素の子であるか、または IUIAutomationTextRange の子の配列に含まれるものです。

vtbl 5 HRESULT GetSelection(IUIAutomationTextRangeArray** ranges)

テキストベースのコントロールで現在選択されているテキストを表すテキスト範囲のコレクションを取得します。(IUIAutomationTextPattern.GetSelection)

ranges

IUIAutomationTextRangeArray**

out

テキスト範囲のコレクションへのポインターを受け取ります。

戻り値

型: HRESULT

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

解説(Remarks)

コントロールが複数の連続しないテキストスパンの選択をサポートしている場合、ranges コレクションには選択された各スパンに対して 1 つのテキスト範囲が格納されます。

コントロールに単一の選択テキストスパンのみが含まれる場合、ranges コレクションには単一のテキスト範囲が格納されます。

コントロールにテキスト挿入ポイントが含まれているがテキストが選択されていない場合、ranges コレクションにはテキスト挿入ポイントの位置に退化した(空の)テキスト範囲が格納されます。

コントロールにテキスト挿入ポイントが含まれていない場合、またはテキスト選択をサポートしていない場合、ranges は NULL に設定されます。

コントロールがテキスト選択をサポートしているかどうかをテストするには、IUIAutomationTextPattern::SupportedTextSelection プロパティを使用します。

vtbl 6 HRESULT GetVisibleRanges(IUIAutomationTextRangeArray** ranges)

テキストベースのコントロールから、それぞれが可視テキストの連続したスパンを表す、互いに素なテキスト範囲の配列を取得します。(IUIAutomationTextPattern.GetVisibleRanges)

ranges

IUIAutomationTextRangeArray**

out

テキストベースのコントロール内の可視テキスト範囲のコレクションへのポインターを受け取ります。

戻り値

型: HRESULT

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

解説(Remarks)

可視テキストが 1 つの連続したテキストスパンで構成されている場合、ranges 配列にはすべての可視テキストを表す単一のテキスト範囲が格納されます。

可視テキストが複数の互いに素なテキストスパンで構成されている場合、ranges 配列には、最初の可視スパンから最後の可視スパンまで、各可視スパンに対して 1 つのテキスト範囲が格納されます。可視テキストの互いに素なスパンは、テキストベースのコントロールの内容が重なり合ったウィンドウやその他のオブジェクトによって部分的に隠されている場合や、複数のページまたは列を持つテキストベースのコントロールの内容が部分的にスクロールされて表示範囲外にある場合に発生することがあります。

テキストが表示されていない場合、すべてのテキストがスクロールされて表示範囲外にある場合、またはテキストベースのコントロールにテキストが含まれていない場合、IUIAutomationTextPattern::GetVisibleRanges は退化した(空の)テキスト範囲を取得します。

vtbl 7 HRESULT get_DocumentRange(IUIAutomationTextRange** range)

ドキュメントの本文を囲むテキスト範囲を取得します。(IUIAutomationTextPattern.get_DocumentRange)

range

IUIAutomationTextRange**

out

ドキュメント全体を表すテキスト範囲を受け取るインターフェイスポインタへのポインタである。

解説(Remarks)

ヘッダー、脚注、注釈などの一部の補助的なテキストは含まれないことがあります。

vtbl 8 HRESULT get_SupportedTextSelection(SupportedTextSelection* supportedTextSelection)

コントロールがサポートするテキスト選択の種類を指定する値を取得します。(IUIAutomationTextPattern.get_SupportedTextSelection)

supportedTextSelection

SupportedTextSelection*

out

この関数が返るときに、SupportedTextSelection オブジェクトへのポインターが格納されます。

戻り値

型: HRESULT

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

出典・ライセンス: 上記「公式ドキュメント」の内容は 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_IUIAutomationTextPattern "{32EBA289-3583-42C9-9C59-3B6D9A1E9B6A}"
#usecom global IUIAutomationTextPattern IID_IUIAutomationTextPattern "{}"
#comfunc global IUIAutomationTextPattern_RangeFromPoint              3 int,sptr
#comfunc global IUIAutomationTextPattern_RangeFromChild              4 sptr,sptr
#comfunc global IUIAutomationTextPattern_GetSelection                5 sptr
#comfunc global IUIAutomationTextPattern_GetVisibleRanges            6 sptr
#comfunc global IUIAutomationTextPattern_get_DocumentRange           7 sptr
#comfunc global IUIAutomationTextPattern_get_SupportedTextSelection  8 var
; ※数字は vtbl インデックス(0始まり)。0/1/2 は IUnknown(QueryInterface/AddRef/Release)。
; ※このインターフェースは直接 CoCreateInstance するクラスIDが無いため "{}"(他メソッド/アクティベーションで取得)。
; ※出力/バッファ引数は var(変数直渡し)。varptr 方式にも切替可。
; ※ハンドル/void*等の不透明ポインタは IronHSP では intptr 指定が可能。#define global IID_IUIAutomationTextPattern "{32EBA289-3583-42C9-9C59-3B6D9A1E9B6A}"
#usecom global IUIAutomationTextPattern IID_IUIAutomationTextPattern "{}"
#comfunc global IUIAutomationTextPattern_RangeFromPoint              3 int,sptr
#comfunc global IUIAutomationTextPattern_RangeFromChild              4 sptr,sptr
#comfunc global IUIAutomationTextPattern_GetSelection                5 sptr
#comfunc global IUIAutomationTextPattern_GetVisibleRanges            6 sptr
#comfunc global IUIAutomationTextPattern_get_DocumentRange           7 sptr
#comfunc global IUIAutomationTextPattern_get_SupportedTextSelection  8 sptr
; ※数字は vtbl インデックス(0始まり)。0/1/2 は IUnknown(QueryInterface/AddRef/Release)。
; ※このインターフェースは直接 CoCreateInstance するクラスIDが無いため "{}"(他メソッド/アクティベーションで取得)。
; ※出力/バッファ引数はポインタ方式(token=sptr / 呼び出しは varptr(変数))。
; ※ハンドル/void*等の不透明ポインタは IronHSP では intptr 指定が可能。