ITextRangeProvider

ITextProvider または ITextProvider2 を実装するテキストコンテナ内の、連続したテキスト範囲へのアクセスを提供します。

範囲は、挿入ポイント、テキストの一部、またはコンテナ内のすべてのテキストを表すことができます。

元の ITextRangeProvider と同一で、元のすべてのプロパティを継承する新しい ITextRangeProvider を返します。

型: HRESULT

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

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

このテキスト範囲が別のテキスト範囲と同じ端点を持つかどうかを示す値を取得します。(ITextRangeProvider.Compare)

型: HRESULT

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

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

2 つのテキスト範囲が同一の端点を持つかどうかを示す値を返します。

型: HRESULT

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

呼び出し元の端点が対象の端点よりもテキスト内で前に位置する場合は、負の値を返します。

呼び出し元の端点が対象の端点と同じ位置にある場合は、ゼロを返します。

呼び出し元の端点が対象の端点よりもテキスト内で後に位置する場合は、正の値を返します。

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

型: HRESULT

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

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

名前に反して、ITextRangeProvider::ExpandToEnclosingUnit メソッドは必ずしもテキスト範囲を拡張するわけではありません。代わりに、範囲が指定されたテキスト単位を包含するように端点を移動して、テキスト範囲を「正規化」します。範囲が指定された単位より小さい場合は拡張され、指定された単位より長い場合は短縮されます。範囲がすでに指定された単位のちょうど整数個分である場合は、変更されません。ExpandToEnclosingUnit メソッドが常に一貫した方法でテキスト範囲を正規化することが重要です。そうでないと、テキスト単位によるテキスト範囲操作の他の側面が予測不能になります。次の図は、ExpandToEnclosingUnit が範囲の端点を移動してテキスト範囲を正規化する方法を示しています。

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

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

• Character
• Format
• Word
• Line
• Paragraph
• Page
• Document

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

unit が TextUnit::Format の場合の範囲の動作

TextUnit::Format を unit の値として使用すると、範囲内のテキストの共通のテキスト属性(書式)に基づいて範囲を拡張または移動するように、テキスト範囲の境界が配置されます。ただし、書式テキスト単位を使用しても、画像やハイパーリンクなどの埋め込みオブジェクトの境界を越えてテキスト範囲を移動または拡張しないでください。詳細については、UI Automation Text Units または Text and TextRange Control Patterns を参照してください。

指定されたテキスト属性値を持つテキスト範囲の部分集合を返します。

型: HRESULT

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

FindAttribute メソッドは、テキストが非表示か表示かにかかわらず、一致するテキストを取得します。クライアントは UIA_IsHiddenAttributeId を使用してテキストの表示状態を確認できます。

指定されたテキストを含むテキスト範囲の部分集合を返します。

型: HRESULT

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

非表示テキストと表示テキストの区別はありません。

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

型: HRESULT

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

GetAttributeValue メソッドは、テキストが非表示か表示かにかかわらず、属性値を取得します。

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

型: HRESULT

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

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

型: HRESULT

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

例

1. この例は、画像リンクを含むテキストストリームを示しています。リンクは画像の子ですが、どちらも同じテキスト範囲にまたがっており、テキストストリーム内で埋め込みオブジェクトとして公開されます。

   Hello <Image Link> World

   • 画像とリンクはどちらもストリームの ITextProvider の子孫でもあり、ITextProvider::RangeFromChild の呼び出しでどちらも childElement として指定できます。
   • 画像またはリンクのいずれかを使用して ITextRangeProvider::RangeFromChild を呼び出すと、同じテキスト範囲(Range1)が返されます。
   • GetChildren はリンクを返しません。
   • GetEnclosingElement は、どのテキスト範囲に対しても画像を返しません。
   • Range1 に対する GetEnclosingElement はリンクを返します。
   • Range1 に対する GetChildren は子を返しません。
   • ストリームの ITextProvider のテキスト範囲に対する GetEnclosingElement はプロバイダーを返します。
   • ストリームの ITextProvider のテキスト範囲に対する GetChildren は画像のみを返します。

2. この例は、テキストに囲まれた 2 セルのテーブルを含むテキストストリームを示しています。

   Start text

   Table Cell 1

   Table Cell 2

   End Text

   • ケース 1: ストリームの ITextProvider とテキスト範囲全体
     • テキスト範囲全体に対する ITextRangeProvider::GetEnclosingElement は、ストリームの ITextProvider を返します。
     • GetChildren は、ストリームの ITextProvider のすべての子要素を返します。この場合はテーブル要素のみです。
   • ケース 2: テーブル要素に対して ITextProvider::RangeFromChild を呼び出して取得したテキスト範囲:
     • ITextRangeProvider::GetEnclosingElement はテーブル要素を返します。
     • ITextRangeProvider::GetChildren は両方のテーブルセルを返します。
   • ケース 3: Table Cell 1 Table Cell 2 の視覚的内容にまたがるテキスト範囲:
     • ITextRangeProvider::GetEnclosingElement はテーブル要素を返します。
     • ITextRangeProvider::GetChildren は両方のテーブルセルを返します。
   • ケース 4: Table Cell 1 の単語 Cell にまたがるテキスト範囲:
     • ITextRangeProvider::GetEnclosingElement は最初のセル要素を返します。
     • ITextRangeProvider::GetChildren は要素を返しません。
   • ケース 5: 両方の開始位置(テーブルと最初のセル)を表す縮退した(空の)テキスト範囲:
     • ITextRangeProvider::GetEnclosingElement は最初のセル要素(縮退した範囲を含む範囲を持つ最も内側の要素)を返します。
     • ITextRangeProvider::GetChildren は要素を返しません。

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

型: HRESULT

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

ITextRangeProvider::GetText は、非表示テキストと表示テキストの両方を取得します。

maxLength が呼び出し元のテキスト範囲の長さよりも大きい場合、返される文字列はテキスト範囲のプレーンテキストになります。

ITextRangeProvider::GetText は、テキストフロー内の端点の順序の影響を受けません。常に、論理的なテキストフローの順序で、テキスト範囲の開始端点と終了端点の間のテキストを返します。

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

型: HRESULT

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

ITextRangeProvider::Move は、テキストの別の部分にまたがるようにテキスト範囲を移動するだけであり、テキストを一切変更してはなりません。

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

1. 開始端点でテキスト範囲を縮退した(空の)範囲に折りたたみます。
2. 必要に応じて、結果として得られるテキスト範囲を、要求された単位境界の先頭までドキュメント内で後方に移動します。
3. 要求された数のテキスト単位境界分、テキスト範囲をドキュメント内で前方または後方に移動します。
4. 終了端点を要求されたテキスト単位境界 1 つ分だけ前方に移動して、縮退した状態からテキスト範囲を拡張します。

上記のいずれかの手順が失敗した場合、テキスト範囲は変更されないままにする必要があります。 テキスト範囲を要求された数のテキスト単位分だけ移動できないが、より少ない数のテキスト単位分だけ移動できる場合は、その少ない数のテキスト単位分だけテキスト範囲を移動し、pRetVal に正常に移動したテキスト単位の数を設定する必要があります。

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

テキスト範囲を移動する際、プロバイダーはテキスト内の埋め込みオブジェクトの境界を無視する必要があります。

ITextRangeProvider::Move は、非表示テキストと表示テキストの両方を対象とする必要があります。

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

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

• Character
• Format
• Word
• Line
• Paragraph
• Page
• Document

unit が TextUnit::Format の場合の範囲の動作

TextUnit::Format を unit の値として使用すると、範囲内のテキストの共通のテキスト属性(書式)に基づいて範囲を拡張または移動するように、テキスト範囲の境界が配置されます。ただし、書式テキスト単位を使用しても、画像やハイパーリンクなどの埋め込みオブジェクトの境界を越えてテキスト範囲を移動または拡張しないでください。詳細については、UI Automation Text Units または Text and TextRange Control Patterns を参照してください。

テキスト範囲の一方の端点を、ドキュメント範囲内で指定された数の TextUnit 単位分だけ移動します。

型: HRESULT

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

端点は、指定されたとおりに前方または後方に、次に利用可能な単位境界まで移動します。元の 端点が指定されたテキスト単位の境界にあった場合、端点は次に利用可能なテキスト単位境界まで移動します。これは次の図に示すとおりです。

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

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

最小の単位から最大の単位への順序は、ここに示すとおりです。

• Character
• Format
• Word
• Line
• Paragraph
• Page
• Document

unit が TextUnit::Format の場合の範囲の動作

TextUnit::Format を unit の値として使用すると、範囲内のテキストの共通のテキスト属性(書式)に基づいて範囲を拡張または移動するように、テキスト範囲の境界が配置されます。ただし、書式テキスト単位を使用しても、画像やハイパーリンクなどの埋め込みオブジェクトの境界を越えてテキスト範囲を移動または拡張しないでください。詳細については、UI Automation Text Units または Text and TextRange Control Patterns を参照してください。

現在のテキスト範囲の一方の端点を、2 番目のテキスト範囲の指定された端点に移動します。(ITextRangeProvider.MoveEndpointByRange)

型: HRESULT

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

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

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

型: HRESULT

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

縮退したテキスト範囲を指定すると、テキスト挿入ポイントが移動します。

複数の分離した選択テキスト範囲をサポートするコントロールにおいて、テキスト範囲を選択済みテキスト範囲のコレクションに追加します。(ITextRangeProvider.AddToSelection)

型: HRESULT

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

テキスト挿入ポイントが新しい選択の領域に移動します。

このメソッドが縮退したテキスト範囲に対して呼び出された場合、テキスト挿入ポイントはテキスト範囲の位置に移動しますが、テキストは選択されません。

複数の分離した選択テキスト範囲をサポートするコントロールにおいて、テキスト範囲を選択済みテキスト範囲のコレクションから削除します。

型: HRESULT

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

テキスト挿入ポイントが削除された選択の領域に移動します。

このメソッドが縮退したテキスト範囲に対して呼び出された場合、テキスト挿入ポイントはテキスト範囲の位置に移動しますが、テキストは選択されません。

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

型: HRESULT

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

ITextRangeProvider::ScrollIntoView は、非表示テキストと表示テキストの両方を対象とします。

テキスト範囲が非表示の場合、非表示テキストがビューポート内にアンカーを持つ場合にのみ、テキストコントロールはスクロールします。

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

型: HRESULT

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

ITextRangeProvider::GetChildren で取得される各要素は、RangeFromChild を通じて取得できる有効なテキスト範囲を持ちます。これには、ITextProvider と子要素の間にある UI Automation ツリー内のすべての要素が含まれます。

例

1. この例は、画像リンクを含むテキストストリームを示しています。リンクは画像の子ですが、どちらも同じテキスト範囲にまたがっており、テキストストリーム内で埋め込みオブジェクトとして公開されます。

   Hello <Image Link> World

   • 画像とリンクはどちらもストリームの ITextProvider の子孫でもあり、ITextProvider::RangeFromChild の呼び出しでどちらも childElement として指定できます。
   • 画像またはリンクのいずれかを使用して ITextRangeProvider::RangeFromChild を呼び出すと、同じテキスト範囲(Range1)が返されます。
   • GetChildren はリンクを返しません。
   • GetEnclosingElement は、どのテキスト範囲に対しても画像を返しません。
   • Range1 に対する GetEnclosingElement はリンクを返します。
   • Range1 に対する GetChildren は子を返しません。
   • ストリームの ITextProvider のテキスト範囲に対する GetEnclosingElement はプロバイダーを返します。
   • ストリームの ITextProvider のテキスト範囲に対する GetChildren は画像のみを返します。

2. この例は、テキストに囲まれた 2 セルのテーブルを含むテキストストリームを示しています。

   Start text

   Table Cell 1

   Table Cell 2

   End Text

   • ケース 1: ストリームの ITextProvider とテキスト範囲全体
     • テキスト範囲全体に対する ITextRangeProvider::GetEnclosingElement は、ストリームの ITextProvider を返します。
     • GetChildren は、ストリームの ITextProvider のすべての子要素を返します。この場合はテーブル要素のみです。
   • ケース 2: テーブル要素に対して ITextProvider::RangeFromChild を呼び出して取得したテキスト範囲:
     • ITextRangeProvider::GetEnclosingElement はテーブル要素を返します。
     • ITextRangeProvider::GetChildren

は両方のテーブルセルを返します。 - ケース 3: Table Cell 1 Table Cell 2 の視覚的内容にまたがるテキスト範囲: - ITextRangeProvider::GetEnclosingElement はテーブル要素を返します。 - ITextRangeProvider::GetChildren は両方のテーブルセルを返します。 - ケース 4: Table Cell 1 の単語 Cell にまたがるテキスト範囲: - ITextRangeProvider::GetEnclosingElement は最初のセル要素を返します。 - ITextRangeProvider::GetChildren は要素を返しません。 - ケース 5: 両方の開始位置(テーブルと最初のセル)を表す縮退した(空の)テキスト範囲: - ITextRangeProvider::GetEnclosingElement は最初のセル要素(縮退した範囲を含む範囲を持つ最も内側の要素)を返します。 - ITextRangeProvider::GetChildren は要素を返しません。

#define global IID_ITextRangeProvider "{5347AD7B-C355-46F8-AFF5-909033582F63}"
#usecom global ITextRangeProvider IID_ITextRangeProvider "{}"
#comfunc global ITextRangeProvider_Clone                  3 sptr
#comfunc global ITextRangeProvider_Compare                4 sptr,var
#comfunc global ITextRangeProvider_CompareEndpoints       5 int,sptr,int,var
#comfunc global ITextRangeProvider_ExpandToEnclosingUnit  6 int
#comfunc global ITextRangeProvider_FindAttribute          7 int,int,int,sptr
#comfunc global ITextRangeProvider_FindText               8 wstr,int,int,sptr
#comfunc global ITextRangeProvider_GetAttributeValue      9 int,var
#comfunc global ITextRangeProvider_GetBoundingRectangles  10 var
#comfunc global ITextRangeProvider_GetEnclosingElement    11 sptr
#comfunc global ITextRangeProvider_GetText                12 int,var
#comfunc global ITextRangeProvider_Move                   13 int,int,var
#comfunc global ITextRangeProvider_MoveEndpointByUnit     14 int,int,int,var
#comfunc global ITextRangeProvider_MoveEndpointByRange    15 int,sptr,int
#comfunc global ITextRangeProvider_Select                 16
#comfunc global ITextRangeProvider_AddToSelection         17
#comfunc global ITextRangeProvider_RemoveFromSelection    18
#comfunc global ITextRangeProvider_ScrollIntoView         19 int
#comfunc global ITextRangeProvider_GetChildren            20 var
; ※数字は vtbl インデックス(0始まり)。0/1/2 は IUnknown(QueryInterface/AddRef/Release)。
; ※このインターフェースは直接 CoCreateInstance するクラスIDが無いため "{}"(他メソッド/アクティベーションで取得)。
; ※出力/バッファ引数は var(変数直渡し)。varptr 方式にも切替可。
; ※ハンドル/void*等の不透明ポインタは IronHSP では intptr 指定が可能。