次の方法で共有

Text コントロール パターンと TextRange コントロール パターン

  • [アーティクル]

プロパティとメソッドに関する情報を含む、ITextProvider 、ITextProvider2、および ITextRangeProviderを実装するためのガイドラインと規則について説明します。 Text コントロール パターンを使用すると、アプリケーションとコントロールは単純なテキスト オブジェクト モデルを公開でき、クライアントはテキスト ベースのコントロールからテキスト コンテンツ、テキスト属性、埋め込みオブジェクトを取得できます。

Text コントロール パターンをサポートするために、コントロールは ITextProviderを実装し、ITextProvider2インターフェイスをします。 Text コントロール パターンをサポートする必要があるコントロールの種類には、編集 と ドキュメント コントロールの種類、およびユーザーがテキストを入力したり、読み取り専用テキストを選択したりできるようにするその他のコントロールの種類があります。

Text コントロール パターンは、他の Microsoft UI オートメーション コントロール パターンと共に使用して、テーブル、ハイパーリンク、コマンド ボタンなど、テキスト内のいくつかの種類の埋め込みオブジェクトをサポートできます。

ITextProvider および ITextProvider2インターフェイスには、テキスト範囲を取得するためのメソッドが多数含まれています。 テキスト範囲 は、テキスト コンテナー内の連続したテキストスパン (または複数の分離されたテキストスパン) を表すオブジェクトです。 1 つの ITextProvider メソッドは、ドキュメント全体を表すテキスト範囲を取得し、他のメソッドは、選択したテキスト、表示されるテキスト、テキストに埋め込まれたオブジェクトなど、ドキュメントの一部を表すテキスト範囲を取得します。

テキスト範囲オブジェクトは、ITextRangeProvider インターフェイスを介して実装される、TextRange コントロール パターンによって表されます。 TextRange コントロール パターンは、範囲内のテキストに関する情報を公開したり、範囲のエンドポイントを移動したり、テキストを選択または選択解除したり、範囲をビューにスクロールしたりするために使用するメソッドとプロパティを提供します。

Text および textRange コントロール パターン の詳細については、「UI オートメーションによるテキスト コンテンツのサポート」を参照してください。

Windows 8.1 以降では、ITextRangeProvider2 インターフェイスを実装できます。 これにより、テキスト範囲に関連付けられているコンテキスト メニューを呼び出します。 これは、テキストオートコレクトや入力メソッド エディター (IME) 候補の選択などのシナリオをサポートします。

このトピックには、次のセクションが含まれています。

実装のガイドラインと規則

Text コントロール パターンを実装する場合は、次のガイドラインと規則に注意してください。

  • テキストへのアクセスを可能にするコントロール (テキストの入力や読み取り専用テキストの選択など) は、Text コントロール パターンをサポートする必要があります。
  • Text コントロール パターンは、標準のボタン コントロールの静的ラベルであっても、テキストを表示する任意の UI 要素で使用できます。 ただし、選択できない、またはカーソルがない静的テキスト コントロールでは必要ありません。
  • テキストに完全にアクセスできるようにするには、ITextProvider実装するコントロールでも、IValueProvider インターフェイスをサポートする必要があります。 IValueProvider は、プログラムでテキストを変更する方法を提供することで、ITextProvider 補完します。 また、Microsoft Active Accessibility などのレガシ テクノロジに基づくものも含め、支援技術クライアント アプリケーションとの互換性も向上します。 両方のコントロール パターンが実装されている場合、TextChanged イベント (UIA_Text_TextChangedEventId) と automationPropertyChanged イベント (UIA_AutomationPropertyChangedEventId) は、Value プロパティ (UIA_ValueValuePropertyId) と同じです。 両方のイベントがサポートされている必要があります。
  • Text コントロール パターンでは、コントロールごとに 1 つのテキスト ストリームと 1 つのビューポートのみがサポートされます。 アプリケーションがペイン内のドキュメントの複数のビューを提供する場合は、各ビュー (コントロール) が個別に ITextProviderサポートする必要があります。
  • ITextProvider::GetSelection メソッドは、現在選択されているテキストを表す 1 つのテキスト範囲を返す場合があります。 コントロールが複数の連続しないテキストスパンの選択をサポートしている場合、GetSelection メソッドは、選択したテキストのスパンごとに 1 つの ITextRangeProvider インターフェイスを含む配列を返す必要があります。
  • Text コントロール パターンは、挿入ポイントを縮退 (空) テキスト範囲として表します。 ITextProvider::GetSelection メソッドは、挿入ポイントが存在し、テキストが選択されていない場合に、縮退したテキスト範囲を返す必要があります。 詳細については、「System Caretとの相互運用性」を参照してください。
  • ITextProvider::GetVisibleRanges メソッドは、連続するテキスト範囲がビューポートに表示されている場合は 1 つのテキスト範囲を返すか、部分的に表示される複数のテキスト行を表す不整合なテキスト範囲の配列を返す場合があります。
  • ITextProvider::RangeFromChild メソッドは、子要素にテキストが含まれている場合、縮退範囲を返す必要があります。 埋め込みオブジェクトにはテキストを含めることができるため、RangeFromChild メソッドは、常に縮退したテキスト範囲を返すとは限りません。 詳細については、「UI オートメーションによる埋め込みオブジェクトのの公開方法」を参照してください。
  • ITextProvider::RangeFromPoint メソッドは、指定された画面座標を使用してドキュメント領域でヒット テストを実行します。 結果のテキスト範囲は、指定した画面座標の位置をクリックした結果として生じる挿入ポイントまたは選択範囲と一致している必要があります。 たとえば、指定した画面座標に画像が存在する場合、結果のテキスト範囲は、ITextProvider::RangeFromChild メソッドがイメージに対して取得するテキスト範囲と同じである必要があります。 同様に、クライアント アプリケーションがシステム キャレット (挿入ポイント) の中心にある場所のテキスト範囲を要求する場合、結果のテキスト範囲はシステム キャレットの場所と同じにする必要があります。
  • ITextProvider::D ocumentRange プロパティは、対応する ITextProvider 実装でサポートされているすべてのテキストを含むテキスト範囲を常に提供する必要があります。
  • UIA_Text_TextChangedEventId イベントは、変更がビューポートに表示されていない場合でも、テキストの変更が発生した後に発生する必要があります。 たとえば、ユーザーが選択したテキストにまったく同じテキストを貼り付けた場合でも、プロバイダーはイベントを発生させる必要があります。
  • UIA_Text_TextSelectionChangedEventId は、テキストの選択が変更されるたびに、またはカーソル (キャレット) がテキスト間を移動するたびに発生する必要があります。

TextRange コントロール パターンを実装する場合は、次のガイドラインと規則に注意してください。

  • TextRange コントロール パターンのすべてのメソッドは、テキストの表示状態に関係なく、テキスト操作を実行する必要があります。 テキスト範囲の表示は、IsHidden テキスト属性 (UIA_IsHiddenAttributeId) に対してクエリを実行することで常に決定できます。
  • 可能であれば、プロバイダーは、削除、挿入、移動などのテキストの変更が関連付けられているテキスト範囲オブジェクト (ITextRangeProviderインターフェイスインスタンス) に反映されるようにし、UIA_Text_TextChangedEventId イベントを発生させる必要があります。 クライアントは、イベントをヒントとして使用して、コントロールのテキストに加えられた編集上の変更を確認できます。
  • ITextRangeProvider::Compare、CompareEndpoints、および MoveEndpointByRangeメソッド使用されるすべてのテキスト範囲オブジェクトは、同じ Text コントロール パターン実装のピアである必要があります。
  • 必須ではありませんが、ITextRangeProvider::CompareEndpoints メソッドによって取得される pRetVal 値は、2 つのエンドポイント間の距離を文字 (TextUnit_Character) で示すことができます。 ただし、クライアント アプリケーションは、pRetVal の正または負の値を超える精度に依存しないようにする必要があります。
  • ITextRangeProvider::ExpandToEnclosingUnit、Move、および MoveEndpointByUnitメソッドには、指定したテキスト単位を慎重に考慮する必要があります。 詳細については、「テキスト単位による TextRange の操作」を参照してください。
  • ITextRangeProvider::Select、AddToSelection、および RemoveFromSelection メソッドに関連する実装要件については、「テキスト範囲内のテキストの選択」を参照してください。
  • ITextRangeProvider::FindText メソッドと FindAttribute メソッドは、一致する単一のテキスト文字列またはテキスト属性を前方または後方に検索します。 一致するものが見つからない場合 NULL を返す必要があります。
  • ITextRangeProvider::GetAttributeValue メソッドは、UiaGetReservedMixedAttributeValue または UiaGetReservedNotSupportedValue 関数から取得したアドレスを返す必要があります(関連付けられた属性が範囲で異なる場合、または属性がテキスト コントロールでサポートされていない場合)。 TextRange コントロール パターン仕様では、新しいテキスト属性識別子を追加したり、既存の属性の定義方法を変更したりすることはできません。
  • 可能であれば、ITextRangeProvider::GetBoundingRectangles メソッドは、テキスト範囲内のテキストの完全または部分的に表示される行ごとに 1 つの外接する四角形を含む配列を返す必要があります。 これが不可能な場合、プロバイダーは、完全に表示される線のみの外接する四角形を含む配列を返すことができます。ただし、これにより、クライアント アプリケーションが画面上でテキストがどのように表示されているかを正確に記述する機能が制限されます。
  • ITextRangeProvider::GetChildren メソッドは、テキスト範囲に埋め込まれているすべての子要素を返す必要がありますが、子要素の子を返す必要はありません。 たとえば、テキスト範囲に多数の子セルがあるテーブルが含まれている場合、GetChildren メソッドは、セル要素ではなくテーブル要素のみを返すことができます。 パフォーマンスやアーキテクチャ上の理由から、プロバイダーは、オートメーション ツリー内のドキュメントでホストされているすべての埋め込みオブジェクトを公開できない場合があります。 この場合、プロバイダーは少なくとも、GetChildren メソッドを介した子オブジェクトの列挙をサポートする必要があります。オプションとして、仮想化解除のサポートのための VirtualizedItem コントロール パターンをサポートします。
  • ITextRangeProvider::GetEnclosingElement メソッドは、通常、テキスト範囲を提供するテキスト プロバイダーを返します。 ただし、テキスト プロバイダーがテーブルやハイパーリンクなどの子オブジェクトをサポートしている場合、外側の要素はテキスト プロバイダーの子孫である可能性があります。 GetEnclosingElement によって返される要素は、指定されたテキスト範囲に最も近い要素である必要があります。 たとえば、テキスト範囲がテーブルのセル内にある場合、getEnclosingElement は、テーブル要素の代わりに含まれるセルを返す必要があります。
  • ITextRangeProvider::GetText メソッドは、範囲内のプレーン テキストを返す必要があります。 詳細については、「テキスト範囲からテキストを取得する」を参照してください。
  • ITextRangeProvider::ScrollIntoViewを呼び出すと、alignToTop パラメーターで指定されたテキスト コントロールのビューポート内のテキストを配置する必要があります。 水平方向の配置に関する要件はありませんが、テキスト範囲は水平方向と垂直方向の両方に表示する必要があります。 alignToTop パラメーターを評価する場合、プロバイダーはテキスト コントロールの向きとテキストのフロー方向を考慮する必要があります。 たとえば、alignToTop が右から左に流れるテキストを含む垂直方向のテキスト コントロールに対して TRUE 場合、プロバイダーはテキスト範囲をビューポートの右側に揃える必要があります。
  • TextUnit_Lineで文書内を移動する場合、テキスト範囲が埋め込みテーブルに入った場合は、セル内のテキストの各行を 1 行として扱う必要があります。

ITextProvider 必要なメンバー

ITextProvider インターフェイスを実装するには、次のプロパティとメソッドが必要です。

必須メンバー メンバーの種類 筆記
DocumentRange 財産 何一つ
SupportedTextSelection 財産 何一つ
GetSelectionの 方式 何一つ
GetVisibleRangesの 方式 何一つ
RangeFromChild 方式 何一つ
RangeFromPoint 方式 何一つ
UIA_Text_TextChangedEventId 出来事 何一つ
UIA_Text_TextSelectionChangedEventId 出来事 何一つ

 

ITextProvider2 インターフェイスを実装するには、次の追加のプロパティとメソッドが必要です。

必須メンバー メンバーの種類 筆記
GetCaretRangeをする 方式 何一つ
RangeFromAnnotation 方式 何一つ

 

ITextRangeProvider 必須メンバー

ITextRangeProvider インターフェイスを実装するには、次のプロパティとメソッドが必要です。

必須メンバー メンバーの種類 筆記
AddToSelectionをする 方式 何一つ
クローン 方式 何一つ
比較 方式 何一つ
CompareEndpoints 方式 何一つ
ExpandToEnclosingUnitの 方式 何一つ
FindAttributeの 方式 何一つ
FindTextの 方式 何一つ
GetAttributeValueをする 方式 何一つ
GetBoundingRectanglesの 方式 何一つ
GetChildrenをする 方式 何一つ
GetEnclosingElementの 方式 何一つ
GetTextの 方式 何一つ
移動 方式 何一つ
MoveEndpointByUnitの 方式 何一つ
MoveEndpointByRangeの 方式 何一つ
の選択 方式 何一つ
ScrollIntoView 方式 何一つ

 

ITextRangeProvider2 インターフェイスを実装するには、次の追加のプロパティとメソッドが必要です。

必須メンバー メンバーの種類 筆記
ShowContextMenu 方式 「ShowContextMenu の実装」セクションを参照してください。

 

TextRange コントロール パターンには、関連付けられたイベントがありません。

テキスト範囲のサポート

このセクションでは、TextRange コントロール パターンをサポートするために、ITextRangeProvider および ITextRangeProvider2 インターフェイスのさまざまなメソッドをプロバイダーが実装する方法について説明します。

テキスト単位によるテキスト範囲の操作

ITextRangeProvider インターフェイスには、テキスト ベースのコントロール内のテキスト範囲を操作および移動するためのメソッドがいくつか用意されています。 ITextRangeProvider::Move、MoveEndpointByUnit、ExpandToEnclosingUnit メソッドは、文字、単語、段落などの指定されたテキスト単位でテキスト範囲またはそのエンドポイントの 1 つを移動します。 詳細については、「UI オートメーション テキスト ユニットの」を参照してください。

その名前にもかかわらず、ITextRangeProvider::ExpandToEnclosingUnit メソッドは必ずしもテキスト範囲を展開するとは限りません。 代わりに、指定したテキスト単位を含む範囲になるようにエンドポイントを移動することで、テキスト範囲を "正規化" します。 指定した単位より小さい場合は範囲が拡張され、指定した単位より長い場合は短縮されます。 ExpandToEnclosingUnit メソッドは常に一貫した方法でテキスト範囲を正規化することが重要です。それ以外の場合、テキスト単位によるテキスト範囲操作の他の側面は予測できません。 次の図は、ExpandToEnclosingUnit 範囲のエンドポイントを移動してテキスト範囲を正規化する方法を示しています。

expandtoenclosingunit図

テキスト範囲がテキスト単位の先頭から始まり、次のテキストユニット境界の先頭または前で終わる場合、終了エンドポイントは次のテキストユニット境界に移動されます (前の図の 1 と 2 を参照)。

テキスト範囲がテキスト単位の先頭から始まり、次の単位境界で終わる場合、終了エンドポイントは開始エンドポイントの後の次の単位境界に留まるか、後方に移動します (前の図の 3 と 4 を参照)。 開始エンドポイントと終了エンドポイントの間に複数のテキスト単位境界がある場合、終了エンドポイントは開始エンドポイントの後の次の単位境界に後方に移動され、テキスト範囲の長さが 1 つのテキスト単位になります。

テキスト範囲がテキスト単位の中央から始まる場合、開始エンドポイントはテキスト単位の先頭に戻り、必要に応じて、開始エンドポイントの後の次の単位境界に前後に移動します (前の図の 5 から 8 を参照)。

ITextRangeProvider::Move メソッドが呼び出されると、プロバイダーは、ExpandToEnclosingUnit メソッドと同じ正規化ロジックを使用して、指定したテキスト単位でテキスト範囲を正規化します。 次に、プロバイダーは、指定された数のテキスト単位で範囲を後方または前方に移動します。 範囲を移動する場合、プロバイダーはテキスト内の埋め込みオブジェクトの境界を無視する必要があります。 (ただし、単位境界自体は、埋め込みオブジェクトの存在によって影響を受ける可能性があります)。 次の図は、Move メソッドが、埋め込みオブジェクトとテキスト単位の境界を越えてテキスト範囲を単位単位で移動する方法を示しています。

move メソッドがオブジェクトとテキストユニットの境界を越えて範囲エンドポイントを移動する方法を示す図

ITextRangeProvider::MoveEndpointByUnit メソッドは、次の図に示すように、指定したテキスト単位でエンドポイントの 1 つを前後に移動します。

範囲 のエンドポイントを moveendpointbyunit が移動する方法を示す図

ITextRangeProvider::MoveEndpointByRange メソッドを使用すると、クライアント アプリケーションはテキスト範囲の 1 つのエンドポイントを、2 番目のテキスト範囲の指定されたエンドポイントと同じ場所に設定できます。

テキスト範囲内のテキストの選択

ITextRangeProvider インターフェイスには、テキスト ベースのコントロール内のテキストの選択を制御するためのいくつかのメソッドが含まれています。

ITextRangeProvider::Select メソッドは、テキスト範囲に対応するテキストを選択し、テキスト コントロールから前の選択範囲 (ある場合) を削除する必要があります。 生成されたテキスト範囲で Select が呼び出された場合、プロバイダーはテキストを選択せずにテキスト範囲の場所にカーソルを移動する必要があります。

コントロールが複数の非結合のテキスト範囲の選択をサポートしている場合、ITextRangeProvider::AddToSelection および RemoveFromSelectionメソッド、選択したテキスト範囲のコレクションにテキスト範囲を追加し、それらを削除します。 コントロールが一度に 1 つの選択したテキスト範囲のみをサポートしているが、選択操作によって複数の非結合テキスト範囲が選択される場合、プロバイダーは E_INVALIDOPERATION エラーを返すか、現在の選択範囲を拡張または切り捨てる必要があります。 ITextProvider::SupportedTextSelection プロパティは、コントロールがテキストの 1 つまたは複数のスパンの選択をサポートしているか、まったくサポートしていないかを示す必要があります。

テキスト ベースのコントロールでテキストの挿入がサポートされている場合は、ITextRangeProvider::AddToSelection呼び出すか、コントロール内の縮退したテキスト範囲で RemoveFromSelectionをすると、カーソルが移動されますが、テキストは選択されません。

テキスト範囲からテキストを取得する

ITextRangeProvider::GetText メソッドは、テキスト範囲のプレーン テキストを返す必要があります。 プレーン テキストには、復帰や Unicode の左から右へのマーク (LRM) など、ソース テキストに含まれるすべての制御文字を含める必要があります。 プレーン テキストには、ソース テキストに存在する可能性がある HTML などのマークアップ タグを含めないようにしてください。 また、ソース テキスト内のエスケープ コードは、同等のプレーン テキストに変換する必要があります。 たとえば、"" は単純なスペース文字に変換する必要があります。

埋め込みオブジェクトがテキストの範囲にまたがる場合、プレーン テキストにはオブジェクトの内部テキストを含める必要がありますが、代替テキスト (埋め込みオブジェクトの名前プロパティ) は含めないようにする必要があります。これは、説明的な内部テキストと矛盾する可能性があるためです。 詳細については、「UI オートメーションによる埋め込みオブジェクトのの公開方法」を参照してください。

ShowContextMenu の実装

ITextRangeProvider2::ShowContextMenu は、常に範囲の始点にコンテキスト メニューを表示する必要があります。 これは、ユーザーがコンテキスト メニュー キーまたは Shift + F10 キーを押し、カーソルが範囲の先頭にある場合と同じになります。

コンテキスト メニューを表示すると、通常、カーソルが特定の場所に移動する場合は、UI オートメーションのサポートのために showContextMenuプログラムで呼び出すようにする必要があります。

システム キャレットとの相互運用性

挿入ポイントを正しくサポートすることは、UI オートメーションに基づいていないものも含め、多くのクライアント アプリケーションにとって重要です。 Text コントロール パターンでは、挿入ポイントは、システム キャレットの位置にある縮退した (空の) テキスト範囲で表されます。 カーソルが移動すると、コントロールは TextSelectionChanged イベント (UIA_Text_TextSelectionChangedEventId) を発生させる必要があります。 一部のクライアント アプリケーションは、挿入ポイントの場所を監視し、テキストの選択を追跡するために、このイベントに依存します。

コントロールに選択したテキストが含まれている場合、Text コントロール パターンの現在のデザインでは、カーソルの位置を特定のテキスト範囲に直接関連付ける方法は提供されません。 プロバイダーは、テキストの選択を追跡し、挿入ポイントの場所を適切に設定する必要があります。 テキストの選択は通常、Shift キーまたは Ctrl キーを押しながらカーソルを移動することによって行われるため、プロバイダーは、選択が変更されるたびにこれらのキーの状態をチェックすることで、テキストの選択を追跡できます。

アクセシビリティ フレームワークはシステム キャレットの組み込みサポートを提供しますが、カスタム キャレットには対応していないため、テキスト ベースのコントロールでは可能な限りシステム キャレットを使用する必要があります。 カスタム キャレットを使用するコントロールは、カスタム キャレットと同じディメンションを持つシステム キャレットを作成し、カスタム キャレットと同じ位置 (つまり、カーソル位置) にシステム キャレットを配置することで、キャレットに確実にアクセスできるようにします。 別の方法として、カスタム キャレットを使用するコントロールは、カスタム キャレットのアクセシビリティ情報を直接提供するために、OBJID_CARET 用の Microsoft Active Accessibility プロバイダーを実装できます。

システムキャレットの詳細については、キャレットを参照してください。

コントロールがシステム キャレットの場所を適切に公開しているかどうかをテストするには、検査 を使用し、アクセシビリティ対応の Event Watcher ツールを します。

システム キャレット ビットマップの中心の画面座標は、常に挿入ポイントの位置と一致する必要があります。 そうすることで、クライアントは ITextProvider::RangeFromPointを呼び出しでキャレット画面座標を使用して、カーソルの位置を正確に表すテキスト範囲を取得できます。

コントロールの種類とサポートされているコントロール パターン

テキスト コントロールの種類

TextEdit コントロール パターン

TextChild コントロール パターン

UI オートメーション コントロール パターンの概要

UI オートメーションによるテキスト コンテンツ のサポート

UI オートメーション ツリーの概要