IUIAutomationTextRange を使用したテキスト範囲へのアクセスと操作
このトピックでは、 IUIAutomationTextRange インターフェイスのプロパティとメソッドを使用して、テキスト ベースのコントロールのテキスト コンテンツにアクセスして操作する方法について説明します。
テキスト範囲とは
Microsoft UI オートメーション テキスト オブジェクト モデルは、テキスト範囲の概念に基づいています。 テキスト範囲は、 IUIAutomationTextRange インターフェイスを公開するオブジェクトであり、テキスト ベースのコントロール内の連続したテキスト範囲を表します。 各テキスト範囲には開始エンドポイントと終了エンドポイントの両方があり、2 つのエンドポイント間のすべてのテキスト コンテンツは範囲の一部と見なされます。 開始エンドポイントと終了エンドポイントが同じ場所にあるテキスト範囲は、 縮退 (または空) テキスト範囲と呼ばれます。 縮退したテキスト範囲は、コントロールのテキスト内の特定の位置 (テキスト挿入ポイントの位置など) をマークするために使用されます。
テキスト範囲オブジェクトの取得
クライアント アプリケーションは、 IUIAutomationTextPattern インターフェイスのプロパティとメソッドを使用してテキスト範囲オブジェクトを取得します。 IUIAutomationTextRangePattern::D ocumentRange プロパティは、テキスト ベースのコントロールのテキスト全体を表すテキスト範囲を取得しますが、他のメソッドは、選択したテキスト、表示されるテキスト、テキストに埋め込まれたオブジェクトなど、コンテンツの一部を表すテキスト範囲を取得します。
IUIAutomationTextRangePattern::GetVisibleRanges メソッドと GetSelection メソッドは、テキスト範囲オブジェクトの配列を取得できます。 重なり合うウィンドウまたはその他のオブジェクトによってコントロールが部分的に隠れている場合、 GetVisibleRanges は、部分的に表示されるテキスト行ごとにテキスト範囲オブジェクトを含む配列を返します。 同様に、テキスト ベースのコントロールで複数の結合されていないテキスト範囲の選択がサポートされている場合、 GetSelection は、選択した各スパンのテキスト範囲オブジェクトを含む配列を返します。
IUIAutomationTextRangePattern::RangeFromChild メソッドを使用すると、クライアント アプリケーションはテキスト コンテンツに埋め込まれたオブジェクトを囲むテキスト範囲を取得できます。 クライアントは、画像、テーブル、ハイパーリンクなどの埋め込みオブジェクトの IUIAutomationElement インターフェイス ポインターを指定し、メソッドは オブジェクトを囲むテキスト範囲を返します。 ただし、埋め込みオブジェクトにテキストが関連付けられていない場合、メソッドは縮退したテキスト範囲を返します。
クライアント アプリケーションでは、 IUIAutomationTextRangePattern::RangeFromPoint メソッドを使用して、指定した画面座標に最も近い表示テキストまたは埋め込みオブジェクトのテキスト範囲を取得できます。
テキスト範囲内のテキストの選択
IUIAutomationTextRange インターフェイスには、クライアント アプリケーションがテキスト ベースのコントロール内のテキストの選択を制御できるようにするメソッドが多数含まれています。
クライアント アプリケーションでは 、IUIAutomationTextRange::Select メソッドを使用して、テキスト範囲に対応するテキストを選択し、テキスト コントロールから前の選択範囲 (存在する場合) を削除できます。 テキスト範囲を縮退して Select を呼び出すと、テキストを選択せずに、挿入ポイントがテキスト範囲の場所に移動します。
コントロールが複数の分離したテキスト範囲の選択をサポートしている場合、クライアントは IUIAutomationTextRange::AddToSelection メソッドと RemoveFromSelection メソッドを使用して、選択したテキスト範囲のコレクションにテキスト範囲を追加し、そこから削除できます。 コントロールで一度に 1 つの選択したテキスト範囲のみがサポートされているが、選択操作によって複数の非結合テキスト範囲が選択される場合、メソッドは E_INVALIDOPERATION エラーを返すか、現在の選択範囲を拡張または切り捨てます。 クライアント アプリケーションは、 IUIAutomationTextPattern::SupportedTextSelection プロパティを確認することで、コントロールがテキストの単一または複数の範囲の選択をサポートしているか、まったくサポートされていないかを検出できます。
テキスト ベースのコントロールでテキストの挿入がサポートされている場合、コントロール内の縮退したテキスト範囲で IUIAutomationTextRange::AddToSelection または RemoveFromSelection を呼び出すと、挿入ポイントは移動されますが、テキストは選択されません。
テキスト範囲からのテキストの取得
クライアント アプリケーションでは、 IUIAutomationTextRange::GetText メソッドを使用して、テキスト範囲のプレーン テキストを取得できます。 プレーン テキストには、復帰や Unicode の左から右へのマーク (LRM) など、ソース テキストに含まれるすべての制御文字が含まれます。 プレーン テキストには、ソース テキストに存在する可能性がある HTML などのマークアップ タグは含まれません。 また、ソース テキスト内のすべてのエスケープ コードは、プレーン テキストに相当するものに変換されます。 たとえば、" " は単純なスペース文字に変換されます。
埋め込みオブジェクトがテキストの範囲にまたがる場合、プレーン テキストにはオブジェクトの内部テキストが含まれますが、代替テキスト (埋め込みオブジェクトの name プロパティ) は含まれません。 詳細については、「埋め込みオブジェクトUI オートメーション公開する方法」を参照してください。
IUIAutomationTextRange::FindText メソッドは、特定の文字列のテキスト範囲を検索し、見つかった場合は、文字列を含む新しいテキスト範囲を返します。
テキスト範囲からのテキスト属性の取得
テキスト属性は、テキスト ベースのコントロール内のテキストの書式設定スタイルを決定し、前景色、箇条書きスタイル、フォント サイズなどが含まれます。 UI オートメーションでは、多数のテキスト属性がサポートされ、サポートされている各属性の識別子が定義されます。 クライアント アプリケーションは、 IUIAutomationTextRange::GetAttributeValue メソッドの呼び出しで属性識別子を指定し、属性値を受け取る VARIANT 構造体へのポインターを指定することで、特定のテキスト属性の値のテキスト範囲を照会できます。 UI オートメーションがサポートする各テキスト属性の詳細については、「テキスト属性識別子」を参照してください。
GetAttributeValue によって取得される値は、テキスト範囲全体の属性の値を表します。 指定した属性に対して範囲内のすべてのテキストが同じ値を共有する場合、その値は GetAttributeValue によって返されます。 ただし、属性の値がテキスト範囲で異なる場合、GetAttributeValue は、ReservedMixedAttribute オブジェクトと呼ばれる静的トークン オブジェクトへの IUnknown ポインターを返します。 属性の値がテキスト範囲で異なるかどうかを検出するには、クライアント アプリケーションで GetAttributeValue の結果を、IUIAutomation::ReservedMixedAttributeValue プロパティから取得した ReservedMixedAttribute オブジェクトと比較する必要があります。
テキスト ベースのコントロールは、すべてのUI オートメーションテキスト属性をサポートする必要はありません。 クライアントが IUIAutomationTextRange::GetAttributeValue メソッドを呼び出し、サポートされていない属性の識別子を渡す場合、このメソッドは、ReservedNotSupported オブジェクトと呼ばれる静的トークン オブジェクトへの IUnknown ポインターを返します。 特定の属性がサポートされているかどうかを検出するには、クライアント アプリケーションで GetAttributeValue の結果を、IUIAutomation::ReservedNotSupportedValue プロパティから取得した ReservedNotSupported オブジェクトと比較する必要があります。
クライアント アプリケーションでは、 IUIAutomationTextRange::FindAttribute メソッドを使用して、特定のテキスト属性を持つテキストのテキスト範囲を検索できます。 見つかった場合、 メソッドは、一致するテキストを含む新しいテキスト範囲を返します。 FindAttribute は、テキストが表示されていない場合でも、一致するテキストのテキスト範囲を返します。
テキスト範囲から埋め込みオブジェクトを取得する
テキスト範囲には、テーブル、画像、ハイパーリンクなどの埋め込みオブジェクトを含めることができます。 クライアント アプリケーションは、 IUIAutomationTextRange::GetChildren メソッドを呼び出すことによって、範囲内のすべての埋め込みオブジェクトのコレクションを取得できます。 範囲と重複するが、その範囲で完全に囲まれていない埋め込みオブジェクトもコレクションに含まれます。 範囲に埋め込みオブジェクトが含まれない場合、 GetChildren は空のコレクションを取得します。
テキスト ベースのコントロールのプロバイダーによって異なりますが、 GetChildren メソッドは通常、埋め込み要素の子を返しません。 たとえば、テキスト範囲に多数の子セルを含むテーブルが含まれている場合、 GetChildren メソッドは通常、セル要素ではなく table 要素のみを返します。
パフォーマンスまたはアーキテクチャ上の理由から、 GetChildren は、テキスト範囲内のすべての埋め込みオブジェクトの IUIAutomationElement オブジェクトを取得できない場合があります。 代わりに、プロバイダーは仮想化された項目を含むコレクションを返す場合があります。 詳細については、「 仮想化アイテムの操作」を参照してください。
テキスト範囲の操作
IUIAutomationTextRange インターフェイスには、テキスト ベースのコントロール内のテキスト範囲を操作および移動するためのメソッドがいくつか用意されています。 IUIAutomationTextRange::Move、MoveEndpointByUnit、ExpandToEnclosingUnit メソッドは、文字、単語、段落など、指定したテキスト単位でテキスト範囲またはそのエンドポイントの 1 つを移動します。 詳細については、「UI オートメーション テキスト単位」を参照してください。
その名前にもかかわらず、 ExpandToEnclosingUnit メソッドは必ずしもテキスト範囲を展開するとは限りません。 代わりに、指定したテキスト単位が範囲に正確に含まれるようにエンドポイントを移動することで、テキスト範囲を "正規化" します。 指定した単位より小さい場合は範囲が拡張され、指定した単位より長い場合は短縮されます。 次の図は、 ExpandToEnclosingUnit が 範囲のエンドポイントを移動してテキスト範囲を正規化する方法を示しています。
テキスト範囲がテキスト単位の先頭から始まり、次のテキストユニット境界の先頭または前で終了する場合、終了エンドポイントは次のテキスト単位境界に移動します (前の図の 1 と 2 を参照)。
テキスト範囲がテキスト単位の先頭から始まり、次の単位境界以降で終了する場合、終了エンドポイントは、開始エンドポイントの後の次の単位境界に留まるか、後方に移動します (前の図の 3 と 4 を参照)。 開始エンドポイントと終了エンドポイントの間に複数のテキスト単位境界がある場合、終了エンドポイントは、開始エンドポイントの後の次の単位境界に後方に移動され、テキスト範囲の長さが 1 つのテキスト単位になります。
テキスト範囲がテキスト単位の中央から始まる場合、開始エンドポイントはテキスト単位の先頭に後方に移動し、終了エンドポイントは必要に応じて、開始エンドポイントの後の次の単位境界に前後に移動します (前の図の 5 から 8 を参照)。
IUIAutomationTextRange::Move メソッドが呼び出されると、プロバイダーは指定したテキスト単位でテキスト範囲を正規化します。 次に、プロバイダーは、指定した数のテキスト単位で範囲を後方または前方に移動します。 範囲を移動すると、プロバイダーはテキスト内の埋め込みオブジェクトの境界を無視します。 (ただし、単位境界自体は、埋め込みオブジェクトの存在によって影響を受ける可能性があります)。 次の図は、 Move メソッドが埋め込みオブジェクトとテキスト単位の境界を越えてテキスト範囲を単位単位で移動する方法を示しています。
IUIAutomationTextRange::MoveEndpointByUnit メソッドは、指定したテキスト単位でエンドポイントの 1 つを前後に移動します。 次の図は、エンドポイントがどのように前進するかを示しています。
IUIAutomationTextRange::MoveEndpointByRange メソッドを使用すると、クライアント アプリケーションはテキスト範囲の 1 つのエンドポイントを、2 番目のテキスト範囲の指定されたエンドポイントと同じ場所に設定できます。
テキスト範囲をビューにスクロールする
IUIAutomationTextRange::ScrollIntoView メソッドはテキスト範囲をスクロールして、テキストベースのコントロールのビューポートにテキストが表示されるようにします。 ScrollIntoView を呼び出すとき、クライアントはテキストをビューポートの上部と下部のどちらに配置するかを指定できます。
テキスト範囲の外側の要素の取得
クライアント アプリケーションでは、 IUIAutomationTextRange::GetEnclosingElement メソッドを 使用して、テキスト範囲を囲む最も内側の要素の IUIAutomation インターフェイス ポインターを取得できます。 外側の要素は、通常、テキスト範囲を提供するテキスト プロバイダーです。 ただし、テキスト プロバイダーがテーブルやハイパーリンクなどの子要素をサポートしている場合、外側の要素はテキスト プロバイダーの子孫である可能性があります。
テキスト範囲の比較と複製
IUIAutomationTextRange インターフェイスには、テキスト範囲を比較するための 2 つのメソッドが含まれています。 IUIAutomationTextRange::Compare メソッドは、2 つのテキスト範囲の開始エンドポイントと終了エンドポイントを比較し、両方のエンドポイントが同じ場合は TRUE を返します。 IUIAutomationTextRange::CompareEndpoints メソッドは、2 つの範囲の開始エンドポイントまたは終了エンドポイントを比較します。 エンドポイントが同じ場合、戻り値は 0、2 つのエンドポイントの相対位置を示す正の値または負の値です。
クライアント アプリケーションでは、 IUIAutomationTextRange::Clone メソッドを使用して、テキスト範囲の正確なコピーを作成できます。 新しいテキスト範囲は、元のテキスト範囲とは別に操作できます。
注釈の取得
テキストベースのコントロールで注釈がサポートされている場合は、テキスト範囲に注釈を含めることができます。 注釈にはさまざまな種類があります。 UIAutomationClient.h ヘッダー ファイルは、UI オートメーションがサポートする注釈の種類を識別する名前付き定数値のセットを定義します。 詳細については、「 注釈型識別子」を参照してください。
一部の種類の注釈は、 Annotation コントロール パターン (IUIAutomationAnnotationPattern インターフェイス) をサポートするオートメーション要素によって表されます。 他の種類の注釈は 、TextRange コントロール パターンを介して公開されます。 たとえば、プロバイダーは、IUIAutomationTextRange::GetAttributeValue メソッドでAnnotationType_SpellingErrorの AnnotationTypes テキスト属性と AnnotationObjects テキスト属性の null 値を返すことで、単純なスペル エラー インジケーターを公開できます。
テキスト範囲から注釈型を取得する
IUIAutomationTextRange::GetAttributeValue メソッドを使用して、テキスト範囲内に存在する注釈の種類の一覧を取得できます。 メソッドを呼び出すときは、 UIA_AnnotationTypesAttributeId のテキスト属性 ID と VARIANT 型のパラメーターへのポインターを指定します。 メソッドが戻ると、 VARIANT パラメーターには、テキスト範囲内の注釈の種類ごとに 1 つずつ、注釈型識別子のリストが含まれます。 詳細については、「 注釈型識別子」を参照してください。
テキスト範囲からすべての注釈を取得する
テキスト範囲から注釈を取得するには、 IUIAutomationTextRange::GetAttributeValue メソッドを呼び出して、 UIA_AnnotationObjectsAttributeId のテキスト属性 ID と VARIANT 型のパラメーターへのポインターを指定します。 メソッドから制御が戻ると、 VARIANT パラメーターには、オートメーション要素の配列を表す IUIAutomationElementArray インターフェイスが含まれます。これは、テキスト範囲内の注釈ごとに 1 つずつです。 IUIAutomationElementArray::Length プロパティは配列内の要素の数を示し、IUIAutomationElementArray::GetElement メソッドは特定の要素の IUIAutomationElement インターフェイスを取得します。
特定の注釈に関する情報の取得
特定の注釈に関する情報を取得するには、前のセクションで説明したように、最初に注釈要素の IUIAutomationElement インターフェイスを取得します。 次に、コントロール パターン ID が UIA_AnnotationPatternId の IUIAutomationElement::GetCurrentPatternAs メソッド、IID_IUIAutomationAnnotationPatternのインターフェイス識別子、および注釈の IUIAutomationAnnotation ポインターを受け取る変数のアドレスを呼び出して、注釈の IUIAutomationAnnotationPattern インターフェイスを取得します。 IUIAutomationAnnotation インターフェイスのプロパティを照会して、注釈の型名と型 ID、注釈作成者の名前、注釈の日付と時刻、注釈を付ける要素の IUIAutomationElement インターフェイスを取得します。
注釈ターゲット テキストの取得
通常、注釈はテキスト範囲内のテキストの一部のサブセットに適用されます。 注釈の IUIAutomationElement インターフェイスを取得した後、 インターフェイスを IUIAutomationTextRange2::RangeFromAnnotation メソッドに渡して、注釈のターゲットであるテキストを含むテキスト範囲を取得できます。
ビジュアル スタイルの取得
プロバイダーは 、スタイル コントロール パターンを実装して、特定のスタイル、塗りつぶしの色、塗りつぶしパターン、または図形を持つ UI 要素を記述します。 これは、多くの場合、このようなスタイルを持つドキュメント内の要素を記述する場合に特に便利です。 このようなスタイルは、多くの場合、障のあるお客様に役立つ情報を伝達します。たとえば、スタイルでは、特定の文字列を文書のタイトルとして記述したり、特定のフローチャート オブジェクトをひし形や円として記述したりできます。
IUIAutomationTextRange::GetAttributeValue メソッドを使用して、テキスト範囲で使用されるビジュアル スタイルの名前と識別子を取得できます。 UIA_StyleNameAttributeId テキスト属性を使用してスタイル名を取得し、UIA_StyleIdAttributeIdしてスタイル識別子を取得します。
ビジュアル スタイルをサポートするテキスト ベースのコントロールは 、Styles コントロール パターンを実装して、クライアントがコントロールで使用されるビジュアル スタイルに関する情報にアクセスできるようにします。 クライアントは 、IUIAutomationStylesPattern インターフェイスを介して Styles コントロール パターンにアクセスします。 このインターフェイスを取得するには、 IUIAutomationElement::GetCurrentPattern メソッドまたは GetCurrentPatternAs メソッドを呼び出し、 UIA_StylesPatternId をコントロール パターン識別子として指定します。
IUIAutomationStylesPattern インターフェイスには、ビジュアル スタイルに関する次の情報を提供するプロパティとメソッドが含まれています。
- ビジュアル スタイルの名前 ("標準" や "見出し 1" など)。
- ビジュアル スタイルの識別子。 詳細については、「 スタイル識別子」を参照してください。
- テキスト ベースのコントロールの塗りつぶしに使用する色。
- テキスト ベースのコントロールの塗りつぶしに使用するパターンの色。
- テキスト ベースのコントロールの図形。
- 拡張プロパティ。つまり、コントロール固有のスタイルの名前と値の一覧です。
テキスト範囲からのコンテキスト メニューの呼び出し
Windows 8.1以降では、テキスト範囲で IUIAutomationTextRange2 インターフェイスがサポートされる場合があります。 このインターフェイスでは、 ShowContextMenu メソッドがサポートされています。 このメソッドを呼び出して、テキスト範囲に関連付けられている任意のコンテキスト メニューを呼び出すことができます。 このシナリオは、テキスト範囲または IME 候補の選択の自動修正です。 このような場合は、ユーザー操作をサポートするコンテキスト メニューが表示されます。
関連トピック