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

IUIAutomationTextRange

COM
IIDa543cc6a-f4ae-494b-8239-c814481187a8継承元IUnknown自前メソッド開始 vtbl3

公式ドキュメント

IUIAutomationTextPattern インターフェイスをサポートするコンテナー内の連続したテキスト範囲へのアクセスを提供します。クライアントアプリケーションは、IUIAutomationTextRange インターフェイスを使用して、テキスト範囲からの選択、比較、および埋め込みオブジェクトの取得を行うことができます。

メソッド 18

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

vtbl 3 HRESULT Clone(IUIAutomationTextRange** clonedRange)

元の範囲と同一で、元のすべてのプロパティを継承した新しい IUIAutomationTextRange を取得します。

clonedRangeIUIAutomationTextRange**out新しいテキスト範囲へのポインターを受け取ります。

戻り値

Type: HRESULT

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

解説(Remarks)

新しい範囲は、元の範囲とは独立して操作できます。

vtbl 4 HRESULT Compare(IUIAutomationTextRange* range, BOOL* areSame)

このテキスト範囲が別のテキスト範囲と同じエンドポイントを持つかどうかを示す値を取得します。(IUIAutomationTextRange.Compare)

rangeIUIAutomationTextRange*inこの範囲と比較するテキスト範囲へのポインター。
areSameBOOL*outテキスト範囲が同じエンドポイントを持つ場合は TRUE を、そうでない場合は FALSE を受け取ります。

戻り値

Type: HRESULT

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

解説(Remarks)

このメソッドは、範囲内のテキストではなく、2 つのテキスト範囲のエンドポイントを比較します。範囲は、同じエンドポイントを共有している場合に同一とみなされます。2 つのテキスト範囲のエンドポイントが異なる場合、両方の範囲のテキストがまったく同じであっても、それらは同一ではありません。

vtbl 5 HRESULT CompareEndpoints(TextPatternRangeEndpoint srcEndPoint, IUIAutomationTextRange* range, TextPatternRangeEndpoint targetEndPoint, INT* compValue)

このテキスト範囲の開始または終了エンドポイントが、別のテキスト範囲の開始または終了エンドポイントと同じかどうかを示す値を取得します。

srcEndPointTextPatternRangeEndpointinこのテキスト範囲の開始と終了のどちらのエンドポイントを比較するかを示す値。
rangeIUIAutomationTextRange*in比較するテキスト範囲へのポインター。
targetEndPointTextPatternRangeEndpointinrange の開始と終了のどちらのエンドポイントを比較するかを示す値。
compValueINT*out呼び出し元のエンドポイントがターゲットのエンドポイントよりもテキスト内で前に位置する場合は負の値を、呼び出し元のエンドポイントがターゲットのエンドポイントと同じ位置にある場合は 0 を、呼び出し元のエンドポイントがターゲットのエンドポイントよりもテキスト内で後に位置する場合は正の値を受け取ります。

戻り値

Type: HRESULT

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

vtbl 6 HRESULT ExpandToEnclosingUnit(TextUnit textUnit)

指定したテキスト単位でテキスト範囲を正規化します。範囲は、指定した単位より小さい場合は拡張され、指定した単位より長い場合は短縮されます。(IUIAutomationTextRange.ExpandToEnclosingUnit)

textUnitTextUnitin行や段落などのテキスト単位。

戻り値

Type: HRESULT

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

解説(Remarks)

スクリーンリーダーなどのクライアントアプリケーションは、このメソッドを使用して、挿入ポイントまたはキャレット位置に存在する完全な単語、文、または段落を取得します。

ExpandToEnclosingUnit メソッドは、その名前とは異なり、必ずしもテキスト範囲を拡張するわけではありません。代わりに、範囲が指定したテキスト単位を包含するようにエンドポイントを移動することで、テキスト範囲を「正規化」します。範囲は、指定した単位より小さい場合は拡張され、指定した単位より長い場合は短縮されます。範囲がすでに指定した単位のちょうど整数個分である場合は、変更されません。次の図は、ExpandToEnclosingUnit が範囲のエンドポイントを移動してテキスト範囲を正規化する方法を示しています。

Diagram showing endpoints before and after ExpandToEnclosingUnit

ExpandToEnclosingUnit の前後のエンドポイントを示す図

指定したテキスト単位がコントロールでサポートされていない場合、ExpandToEnclosingUnit は既定で次に大きいサポートされているテキスト単位を使用します。

最小の単位から最大の単位への順序は次のとおりです。

ExpandToEnclosingUnit は、表示テキストと非表示テキストの両方を考慮します。

unitTextUnit::Format の場合の範囲の動作

unit 値としての TextUnit::Format は、範囲内のテキストで共有されるテキスト属性(またはフォーマット)に基づいて範囲を拡張または移動するように、テキスト範囲の境界を配置します。ただし、Format テキスト単位は、画像やハイパーリンクなどの埋め込みオブジェクトの境界を越えてテキスト範囲を移動または拡張することはありません。詳細については、UI Automation のテキスト単位 または テキストコンテンツに対する UI Automation のサポート を参照してください。

vtbl 7 HRESULT FindAttribute(UIA_TEXTATTRIBUTE_ID attr, VARIANT val, BOOL backward, IUIAutomationTextRange** found)

指定したテキスト属性値を持つテキスト範囲のサブセットを取得します。

attrUIA_TEXTATTRIBUTE_IDin取得するテキスト範囲のサブセットに対応するテキスト属性の識別子。テキスト属性 ID の一覧については、テキスト属性識別子を参照してください。
valVARIANTin属性の値。この値は、属性に指定された型と一致している必要があります。
backwardBOOLin最初に出現するテキスト範囲ではなく最後に出現するテキスト範囲を返す場合は TRUE、そうでない場合は FALSE
foundIUIAutomationTextRange**out一致する属性と属性値を持つテキスト範囲へのポインターを受け取ります。一致するものがない場合は NULL

戻り値

Type: HRESULT

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

解説(Remarks)

FindAttribute メソッドは、テキストが非表示か表示かにかかわらず、一致するテキストを取得します。テキストの表示状態を確認するには、UIA_IsHiddenAttributeId を使用してください。

vtbl 8 HRESULT FindText(LPWSTR text, BOOL backward, BOOL ignoreCase, IUIAutomationTextRange** found)

指定したテキストを含むテキスト範囲のサブセットを取得します。

textLPWSTRin検索するテキスト。
backwardBOOLin最初に出現するテキスト範囲ではなく最後に出現するテキスト範囲を返す場合は TRUE、そうでない場合は FALSE
ignoreCaseBOOLin大文字と小文字を区別しない場合は TRUE、そうでない場合は FALSE
foundIUIAutomationTextRange**outテキスト範囲へのポインターを受け取ります。一致するものが見つからない場合は NULL

戻り値

Type: HRESULT

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

解説(Remarks)

非表示テキストと表示テキストは区別されません。

vtbl 9 HRESULT GetAttributeValue(UIA_TEXTATTRIBUTE_ID attr, VARIANT* value)

テキスト範囲全体にわたる、指定したテキスト属性の値を取得します。

attrUIA_TEXTATTRIBUTE_IDinテキスト属性の識別子。テキスト属性 ID の一覧については、テキスト属性識別子を参照してください。
valueVARIANT*out指定した属性の値を受け取ります。

戻り値

Type: HRESULT

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

解説(Remarks)

このメソッドで取得される値の型は、attr パラメーターによって異なります。 たとえば、attr パラメーターに UIA_FontNameAttributeId を設定して GetAttributeValue を呼び出すと、テキスト範囲のフォント名を表す文字列が返され、attrUIA_IsItalicAttributeId を設定して GetAttributeValue を呼び出すとブール値が返されます。

attr で指定した属性がサポートされていない場合、value パラメーターは IUIAutomation::ReservedNotSupportedValue プロパティに相当する値を受け取ります。

テキスト範囲には、特定の属性に対して複数の値が含まれることがあります。たとえば、テキスト範囲に複数のフォントが含まれる場合、FontName 属性は複数の値を持ちます。複数の値を持つ属性は 混合属性 (mixed attribute) と呼ばれます。 特定の属性が混合属性かどうかは、GetAttributeValue から取得した値を UIAutomation::ReservedMixedAttributeValue プロパティと比較することで判断できます。

GetAttributeValue メソッドは、テキストが非表示か表示かにかかわらず、属性値を取得します。 テキストの表示状態を確認するには、UIA_ IsHiddenAttributeId を使用してください。

vtbl 10 HRESULT GetBoundingRectangles(SAFEARRAY** boundingRects)

テキスト範囲内の、完全にまたは部分的に表示されている各テキスト行の外接する四角形のコレクションを取得します。(IUIAutomationTextRange.GetBoundingRectangles)

boundingRectsSAFEARRAY**outテキスト範囲内の、完全にまたは部分的に表示されている各テキスト行の外接する四角形の配列へのポインターを受け取ります。縮退した(空の)テキスト範囲、または完全に画面外にある、スクロールして見えなくなっている、もしくは重なり合うウィンドウによって隠されているテキスト範囲の場合は、空の配列が返されます。

戻り値

Type: HRESULT

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

解説(Remarks)

外接する四角形が SAFEARRAY にどのように格納されるかについては、セーフ配列を使用する際のベストプラクティスを参照してください。

vtbl 11 HRESULT GetEnclosingElement(IUIAutomationElement** enclosingElement)

テキスト範囲を囲む、最も内側の UI Automation 要素を返します。

enclosingElementIUIAutomationElement**out囲んでいる要素へのポインターを受け取ります。これは通常、テキスト範囲を提供するテキストプロバイダーです。ただし、テキストプロバイダーがテーブルやハイパーリンクなどの子要素をサポートしている場合、囲んでいる要素はテキストプロバイダーの子孫要素になることがあります。

戻り値

Type: HRESULT

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

vtbl 12 HRESULT GetText(INT maxLength, LPWSTR* text)

テキスト範囲のプレーンテキストを返します。

maxLengthINTin返す文字列の最大長。制限が不要な場合は -1。
textLPWSTR*out文字列へのポインターを受け取ります。指定した maxLength で切り詰められる場合があります。

戻り値

Type: HRESULT

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

vtbl 13 HRESULT Move(TextUnit unit, INT count, INT* moved)

指定した数のテキスト単位だけ、テキスト範囲を前方または後方に移動します。

unitTextUnitin文字、単語、段落などのテキスト単位の種類を指定する値。
countINTin移動するテキスト単位の数。正の値はテキスト範囲を前方に移動します。負の値はテキスト範囲を後方に移動します。0 の場合は何も起こりません。
movedINT*out実際に移動したテキスト単位の数を受け取ります。新しいテキスト範囲のいずれかのエンドポイントが、IUIAutomationTextPattern::DocumentRange メソッドで取得されるエンドポイントを超える場合、この値は要求した数より小さくなることがあります。後方に移動している場合、この値は負になることがあります。

戻り値

Type: HRESULT

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

解説(Remarks)

IUIAutomationTextRange::Move は、テキストの別の部分にまたがるようにテキスト範囲を移動します。テキスト自体は一切変更しません。

縮退していない(空でない)テキスト範囲の場合、IUIAutomationTextRange::Move は次の手順を実行して範囲を正規化し、移動します。

  1. テキスト範囲は、開始エンドポイントで縮退した(空の)範囲に折りたたまれます。
  2. 必要に応じて、結果として得られるテキスト範囲は、ドキュメント内で要求されたテキスト単位境界の先頭まで後方に移動されます。
  3. テキスト範囲は、ドキュメント内で要求された数のテキスト単位境界だけ前方または後方に移動されます。
  4. テキスト範囲は、終了エンドポイントを要求されたテキスト単位境界 1 つ分だけ前方に移動することで、縮退状態から拡張されます。
上記のいずれかの手順が失敗した場合、テキスト範囲は変更されないままになります。 テキスト範囲を要求された数のテキスト単位だけ移動できないものの、より少ない数のテキスト単位であれば移動できる場合、テキスト範囲はその少ない数のテキスト単位だけ移動され、moved には移動したテキスト単位の数が設定されます。

縮退したテキスト範囲の場合、IUIAutomationTextRange::Move は指定した数のテキスト単位だけテキスト挿入ポイントを移動するだけです。

テキスト範囲を移動する際、IUIAutomationTextRange::Move はテキスト内の埋め込みオブジェクトの境界を無視します。

IUIAutomationTextRange::Move は、非表示テキストと表示テキストの両方を考慮します。

テキストベースのコントロールが unit パラメーターで指定されたテキスト単位をサポートしていない場合、IUIAutomationTextRange::Move は次に大きいサポートされているテキスト単位で代替します。

テキスト単位のサイズは、最小の単位から最大の単位まで次のとおりです。

unitTextUnit::Format の場合の範囲の動作

unit 値としての TextUnit::Format は、範囲内のテキストで共有されるテキスト属性(フォーマット)に基づいて範囲を拡張または移動するように、テキスト範囲の境界を配置します。ただし、フォーマットテキスト単位を使用しても、画像やハイパーリンクなどの埋め込みオブジェクトの境界を越えてテキスト範囲を移動または拡張することはありません。詳細については、UI Automation のテキスト単位またはテキストコンテンツに対する UI Automation のサポートを参照してください。
vtbl 14 HRESULT MoveEndpointByUnit(TextPatternRangeEndpoint endpoint, TextUnit unit, INT count, INT* moved)

ドキュメント範囲内で、テキスト範囲の一方のエンドポイントを指定した数のテキスト単位だけ移動します。

endpointTextPatternRangeEndpointin移動するエンドポイント(開始または終了)を指定する値。
unitTextUnitin行や段落など、移動に使用するテキスト単位を指定する値。
countINTin移動する単位の数。正の値はエンドポイントを前方に移動します。負の値は後方に移動します。0 の場合は何も起こりません。
movedINT*out実際に移動した単位の数を受け取ります。エンドポイントの移動がドキュメントの先頭または末尾に達した場合、この値は要求した数より小さくなることがあります。

戻り値

Type: HRESULT

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

解説(Remarks)

エンドポイントは、指定に従って、次に利用可能な単位境界まで前方または後方に移動されます。元の endpoint が指定したテキスト単位の境界にあった場合、endpoint は次の図に示すように、次に利用可能なテキスト単位境界まで移動されます。

Illustration showing endpoints of a text range moving 移動されるエンドポイントが同じテキスト範囲のもう一方の endpoint を越えた場合、もう一方の endpoint も移動され、縮退した範囲となり、endpoint の正しい順序(つまり、開始が常に終了以下であること)が保証されます。

指定したテキスト単位がコントロールでサポートされていない場合、MoveEndpointByUnit は次にサポートされているテキスト単位まで格下げします。

最小の単位から最大の単位への順序は次のとおりです。

unitTextUnit::Format の場合の範囲の動作

unit 値としての TextUnit::Format は、範囲内のテキストで共有されるテキスト属性(フォーマット)に基づいて範囲を拡張または移動するように、テキスト範囲の境界を配置します。ただし、フォーマットテキスト単位を使用しても、画像やハイパーリンクなどの埋め込みオブジェクトの境界を越えてテキスト範囲を移動または拡張することはありません。詳細については、UI Automation のテキスト単位またはテキストコンテンツに対する UI Automation のサポートを参照してください。
vtbl 15 HRESULT MoveEndpointByRange(TextPatternRangeEndpoint srcEndPoint, IUIAutomationTextRange* range, TextPatternRangeEndpoint targetEndPoint)

現在のテキスト範囲の一方のエンドポイントを、2 つ目のテキスト範囲の指定したエンドポイントへ移動します。(IUIAutomationTextRange.MoveEndpointByRange)

srcEndPointTextPatternRangeEndpointin現在のテキスト範囲のエンドポイント(開始または終了)。これが移動されるエンドポイントです。
rangeIUIAutomationTextRange*in現在のテキスト範囲と同じテキストプロバイダーからの 2 つ目のテキスト範囲。
targetEndPointTextPatternRangeEndpointin2 つ目のテキスト範囲のエンドポイント(開始または終了)。 現在のテキスト範囲の srcEndPoint は、このエンドポイントへ移動されます。

戻り値

Type: HRESULT

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

解説(Remarks)

移動されるエンドポイントが同じテキスト範囲のもう一方のエンドポイントを越えた場合、そのもう一方のエンドポイントも移動され、縮退した(空の)範囲となり、エンドポイントの正しい順序(つまり、開始が常に終了以下であること)が保証されます。

vtbl 16 HRESULT Select()

このテキスト範囲に対応するテキストの範囲を選択し、以前の選択をすべて解除します。(IUIAutomationTextRange.Select)

戻り値

Type: HRESULT

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

解説(Remarks)

縮退した(空の)テキスト範囲を表すテキスト範囲オブジェクトに対して Select メソッドが呼び出された場合、テキスト挿入ポイントはテキスト範囲の開始エンドポイントへ移動します。

vtbl 17 HRESULT AddToSelection()

複数の互いに重ならない選択テキスト範囲をサポートするコントロールにおいて、選択されたテキスト範囲のコレクションにこのテキスト範囲を追加します。(IUIAutomationTextRange.AddToSelection)

戻り値

Type: HRESULT

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

解説(Remarks)

テキスト挿入ポイントは新しく選択されたテキストへ移動します。縮退した(空の)テキスト範囲を表すテキスト範囲オブジェクトに対して AddToSelection が呼び出された場合、テキスト挿入ポイントはテキスト範囲の開始エンドポイントへ移動します。

vtbl 18 HRESULT RemoveFromSelection()

複数の互いに重ならない選択をサポートするテキストコンテナーにおいて、既存の選択テキストのコレクションからこのテキスト範囲を削除します。

戻り値

Type: HRESULT

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

解説(Remarks)

テキスト挿入ポイントは、削除された強調表示の領域へ移動します。縮退したテキスト範囲を指定した場合も、挿入ポイントは移動します。

vtbl 19 HRESULT ScrollIntoView(BOOL alignToTop)

テキスト範囲がビューポート内に表示されるまで、テキストコントロールをスクロールさせます。

alignToTopBOOLinテキスト範囲がビューポートの上端にそろうようにテキストコントロールをスクロールする場合は TRUE、下端にそろえる場合は FALSE

戻り値

Type: HRESULT

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

解説(Remarks)

このメソッドは、非表示テキストと表示テキストの両方を考慮します。テキスト範囲が非表示の場合、テキストコントロールがスクロールするのは、その非表示テキストがビューポート内にアンカーを持っている場合のみです。

Microsoft UI Automation クライアントは、attr パラメーターに UIA_IsHiddenAttributeId を設定して IUIAutomationTextRange::GetAttributeValue を呼び出すことで、テキストの表示状態を確認できます。

vtbl 20 HRESULT GetChildren(IUIAutomationElementArray** children)

テキスト範囲内に含まれるすべての埋め込みオブジェクトのコレクションを取得します。(IUIAutomationTextRange.GetChildren)

childrenIUIAutomationElementArray**out範囲内に含まれるすべての子オブジェクトのコレクションへのポインターを受け取ります。範囲と重なっているものの完全には範囲内に収まっていない子も、コレクションに含まれます。子オブジェクトがない場合は、空のコレクションが返されます。

戻り値

Type: 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_IUIAutomationTextRange "{A543CC6A-F4AE-494B-8239-C814481187A8}"
#usecom global IUIAutomationTextRange IID_IUIAutomationTextRange "{}"
#comfunc global IUIAutomationTextRange_Clone                  3 sptr
#comfunc global IUIAutomationTextRange_Compare                4 sptr,var
#comfunc global IUIAutomationTextRange_CompareEndpoints       5 int,sptr,int,var
#comfunc global IUIAutomationTextRange_ExpandToEnclosingUnit  6 int
#comfunc global IUIAutomationTextRange_FindAttribute          7 int,int,int,sptr
#comfunc global IUIAutomationTextRange_FindText               8 wstr,int,int,sptr
#comfunc global IUIAutomationTextRange_GetAttributeValue      9 int,var
#comfunc global IUIAutomationTextRange_GetBoundingRectangles  10 var
#comfunc global IUIAutomationTextRange_GetEnclosingElement    11 sptr
#comfunc global IUIAutomationTextRange_GetText                12 int,var
#comfunc global IUIAutomationTextRange_Move                   13 int,int,var
#comfunc global IUIAutomationTextRange_MoveEndpointByUnit     14 int,int,int,var
#comfunc global IUIAutomationTextRange_MoveEndpointByRange    15 int,sptr,int
#comfunc global IUIAutomationTextRange_Select                 16
#comfunc global IUIAutomationTextRange_AddToSelection         17
#comfunc global IUIAutomationTextRange_RemoveFromSelection    18
#comfunc global IUIAutomationTextRange_ScrollIntoView         19 int
#comfunc global IUIAutomationTextRange_GetChildren            20 sptr
; ※数字は vtbl インデックス(0始まり)。0/1/2 は IUnknown(QueryInterface/AddRef/Release)。
; ※このインターフェースは直接 CoCreateInstance するクラスIDが無いため "{}"(他メソッド/アクティベーションで取得)。
; ※出力/バッファ引数は var(変数直渡し)。varptr 方式にも切替可。
; ※ハンドル/void*等の不透明ポインタは IronHSP では intptr 指定が可能。