TextPattern および埋め込みオブジェクトの概要

Note

このドキュメントは、System.Windows.Automation 名前空間で定義されているマネージド UI オートメーション クラスを使用する .NET Framework 開発者を対象としています。 UI オートメーションの最新情報については、Windows Automation API の「UI オートメーション」を参照してください。

この概要では、Microsoft UI オートメーションにより、テキスト ドキュメントまたはコンテナー内で埋め込みオブジェクトや子要素がどのように公開されているかについて説明します。

UI オートメーションでは、埋め込みオブジェクトは、テキスト以外の境界を持つ任意の要素です。たとえば、イメージ、ハイパーリンク、テーブル、ドキュメントの種類 (Microsoft Excel スプレッドシートや Microsoft Windows Media ファイルなど) があります。 これは、あるアプリケーションで要素が作成され、別のアプリケーション内に埋め込まれる (リンクされる) 標準的な定義とは異なります。 オブジェクトを元のアプリケーション内で編集できるかどうかは、UI オートメーションの状況とは無関係です。

埋め込みオブジェクトと UI オートメーション ツリー

埋め込みオブジェクトは、UI オートメーション ツリーのコントロール ビュー内では個々の要素として扱われます。 これらはテキスト コンテナーの子として公開され、UI オートメーションの他のコントロールと同じモデルを介してアクセスできます。

Embedded Table with Image in a Text Container テーブル、イメージ、ハイパーリンクの埋め込みオブジェクトを含むテキスト コンテナーの例

Content view for the preceding example 前のテキスト コンテナーの一部のコンテンツ ビューの例

TextPattern と TextPatternRange を使用した埋め込みオブジェクトの公開

TextPattern コントロール パターン クラスと TextPatternRange クラスを組み合わせて使用すると、埋め込みオブジェクトのナビゲーションと照会を容易にするメソッドとプロパティが公開されます。

テキスト コンテナーのテキスト コンテンツ (内部テキスト) と埋め込みオブジェクト (ハイパーリンクやテーブルのセルなど) は、連続する単一のテキスト ストリームとして、UI オートメーション ツリーのコントロール ビューとコンテンツ ビューの両方で公開されます。そのため、オブジェクトの境界は無視されます。 UI オートメーション クライアントがなんらかの方法で列挙、解釈、分析を目的としてテキストを取得している場合、テキスト コンテンツを含むテーブルやその他の埋め込みオブジェクトなど、特殊なケースについて、テキスト範囲を確認する必要があります。 これを行うには、 GetChildren を呼び出して各埋め込みオブジェクトの AutomationElement を取得した後、 RangeFromChild を呼び出して各要素のテキスト範囲を取得します。 この操作は、すべてのテキスト コンテンツが取得されるまで再帰的に行われます。

Text ranges spanned by embedded objects. 埋め込みオブジェクトとその範囲を含むテキスト ストリームの例

テキスト範囲の内容を走査する必要がある場合、 Move メソッドを正常に実行するために、一連の手順がその背後で関係しています。

  1. テキスト範囲は正規化されます。つまり、テキスト範囲は Start エンドポイントで低次元テキスト範囲に縮小されるため、 End エンドポイントは不要になります。 この手順は、テキスト範囲が複数の TextUnit 境界にまたがる状況であいまいさをなくすために必要です。たとえば、"{" と "}" がテキスト範囲エンドポイントである {The URL https://www.microsoft.com is embedded in text のような場合です。

  2. 結果として得られる範囲は、 DocumentRange 内で、要求された TextUnit 境界の先頭に向かって後方に移動されます。

  3. この範囲は、 DocumentRange 内で、 TextUnit 境界の要求された数だけ、前方または後方に移動されます。

  4. その後、この範囲は、要求された 1 つの End 境界の分、 TextUnit エンドポイントを移動することによって、低次元テキスト範囲の状態から展開されます。

Range adjustments by Move & ExpandToEnclosingUnit テキスト範囲を Move() と ExpandToEnclosingUnit() に対して調整する方法の例

一般的なシナリオ

以下のセクションでは、埋め込みオブジェクトが関連する最も一般的なシナリオの例を紹介します。

この例で使用される凡例は次のとおりです。

{ = Start

} = End

例 1: 埋め込みテキスト ハイパーリンクを含むテキスト範囲

{The URL https://www.microsoft.com is embedded in text}.

呼び出されるメソッド 結果
GetText string The URL https://www.microsoft.com is embedded in text が返されます。
GetEnclosingElement テキスト範囲を囲む最も内側の AutomationElement を返します。この場合は、テキスト プロバイダー自体を表す AutomationElement を返します。
GetChildren ハイパーリンク コントロールを表す AutomationElement を返します。
RangeFromChild ( AutomationElement は、前の GetChildren メソッドから返されるオブジェクト) https://www.microsoft.com を表す範囲を返します。

例 2: 埋め込みテキスト ハイパーリンクに部分的にかかるテキスト範囲

URL https://{[www]} はテキストに埋め込まれています。

呼び出されるメソッド 結果
GetText 文字列 "www" を返します。
GetEnclosingElement テキスト範囲を囲む最も内側の AutomationElement を返します。この場合は、ハイパーリンク コントロールです。
GetChildren テキスト範囲が URL 文字列全体をカバーしていないため、 null を返します。

例 3: テキスト コンテナーのコンテンツに部分的にかかるテキスト範囲 テキスト コンテナーには、テキスト範囲に含まれない埋め込みテキスト ハイパーリンクが含まれます。

{The URL} [https://www.microsoft.com](https://www.microsoft.com) is embedded in text.

呼び出されるメソッド 結果
GetText 文字列 "The URL" を返します。
GetEnclosingElement テキスト範囲を囲む最も内側の AutomationElement を返します。この場合は、テキスト プロバイダー自体を表す AutomationElement を返します。
Move (パラメーターは (TextUnit.Word, 1)) ハイパーリンクのテキストは個々の単語で構成されているため、テキスト範囲は "http" に移動します。 この場合、ハイパーリンクは 1 つのオブジェクトとして扱われません。

URL {[http]} はテキストに埋め込まれています。

Image

例 1: 埋め込みイメージを含むテキスト範囲

{画像 Embedded Image Example がテキストに埋め込まれます}。

呼び出されるメソッド 結果
GetText 文字列 "The is embedded in text" を返します。 イメージに関連付けられた代替テキストがテキスト ストリームに含まれることはありません。
GetEnclosingElement テキスト範囲を囲む最も内側の AutomationElement を返します。この場合は、テキスト プロバイダー自体を表す AutomationElement を返します。
GetChildren イメージ コントロールを表す AutomationElement を返します。
RangeFromChild ( AutomationElement は、前の GetChildren メソッドから返されるオブジェクト) "Embedded Image Example" を表す低次元テキスト範囲を返します。

例 2: テキスト コンテナーのコンテンツに部分的にかかるテキスト範囲 テキスト コンテナーには、テキスト範囲に含まれない埋め込みイメージが含まれます。

{画像} Embedded Image Example がテキストに埋め込まれます。

呼び出されるメソッド 結果
GetText 文字列 "The image" を返します。
GetEnclosingElement テキスト範囲を囲む最も内側の AutomationElement を返します。この場合は、テキスト プロバイダー自体を表す AutomationElement を返します。
Move (パラメーターは (TextUnit.Word, 1)) テキスト範囲は "is " に移動します。 テキスト ベースの埋め込みオブジェクトのみがテキスト ストリームの一部と見なされるため、この例のイメージは Move やその戻り値 (この場合は 1) に影響を与えません。

テーブル

例で使用するテーブル

イメージを含むセル テキストを含むセル
Embedded Image Example x
Embedded Image Example 2
Embedded Image Example 3

Z のイメージ
Z

例 1: セルのコンテンツからテキスト コンテナーを取得する

呼び出されるメソッド 結果
GetItem (パラメーターは (0, 0)) セルのコンテンツを表す AutomationElement を返します。この場合、要素はテキスト コントロールです。
RangeFromChild ( AutomationElement は、前の GetItem メソッドから返されるオブジェクト) 画像 Embedded Image Example をカバーする範囲を返します。
前のGetEnclosingElement メソッドから返されるオブジェクトの RangeFromChild セルを表す AutomationElement を返します。この場合、要素は TableItemPattern をサポートするテキスト コントロールです。
前のGetEnclosingElement メソッドから返されるオブジェクトの GetEnclosingElement テーブルを表す AutomationElement を返します。
前のGetEnclosingElement メソッドから返されるオブジェクトの GetEnclosingElement テキスト プロバイダー自体を表す AutomationElement を返します。

例 2: セルのテキスト コンテンツを取得する

呼び出されるメソッド 結果
GetItem (パラメーターは (1, 1)) セルのコンテンツを表す AutomationElement を返します。この場合、要素はテキスト コントロールです。
RangeFromChild ( AutomationElement は、前の GetItem メソッドから返されるオブジェクト) "Y" を返します。

関連項目