ITextRange

ITextRange オブジェクトは、プログラムがストーリー内のテキストを選択し、そのテキストを調べたり変更したりできる強力な編集およびデータバインディングのツールです。

複数のテキスト範囲を同時にアクティブにして、同じストーリー上で協調的に動作させ、ストーリーの変化に合わせて変化させることができます。たとえば、あるテキスト範囲が別のテキスト範囲より前の指定テキストを削除すると、後者はその変更を追跡します。この意味で、テキスト範囲は編集の変更を追跡する Microsoft Word のブックマークに似ています。ただし、ブックマークはテキストを編集できませんが、テキスト範囲は編集できます。さらに、範囲を使うと、選択範囲やクリップボードを変更せずにテキストを操作できます。これらはどちらもエンドユーザーにとって重要です。ITextSelection インターフェイスは ITextRange を継承し、ITextSelection のセクションで説明する UI 指向のメソッドとプロパティをいくつか追加します。

テキスト範囲は文字位置に基づくメソッドで参照できます。具体的には、テキスト範囲は次の要素で特徴付けられます。

• 先頭の文字位置 cpFirst。範囲内の(ストーリーの先頭を基準とした)最初の文字の直前にある挿入ポイントを指します。
• 上限の位置 cpLim。範囲内の最後の文字の直後にある挿入ポイントを指します。

ストーリーの最初の文字は cpFirst = 0 です。cp 引数の値がストーリーの文字数より大きい場合は、代わりにストーリーの文字数が使われます。cp 引数が負の場合は、代わりに 0 が使われます。Microsoft Visual Basic for Applications に慣れている方は、cpFirst プロパティを Start、cpLim プロパティを End と呼びます(範囲の開始位置も一種の端ではありますが)。

次の図では、文字位置は文字を区切る線で表されています。対応する文字位置の値は線の下に示されています。cpFirst = 5 で始まり cpLim = 7 で終わる範囲には、2 文字の単語 is が含まれます。この図がストーリー内の全テキストを表しているとすると、ストーリーの長さは 30 です。

範囲の長さは cpLim - cpFirst、すなわち End - Start で表されます。長さが 0 の範囲は退化した(degenerate)範囲または空の(empty)範囲と呼ばれ、cp* の値が等しく、cpFirst = cpLim となります。退化した範囲の例が現在の挿入ポイントです。空でない選択範囲は、退化していない範囲の例です。

前の図で網掛けのセルで示された 5 から 7 の範囲に、テキストを削除するよう指示した(Delete を参照)とします。これによってその範囲自身は挿入ポイントになります。25 から 29 の範囲は、その内容、すなわち単語 text を自動的に追跡します。次の図はその結果を示しています。

この図では、text の範囲は cpFirst = 23、cpLim = 27 となるよう自動的に調整されています。範囲の所有者は、編集に際して範囲の文字位置の値を更新する必要はありません。

move 系メソッドの名前は、どちらの端を移動するかを示していますが、いずれかのメソッドが一方の範囲端を他方の端を越えて移動しようとすると、両方の端が目標位置に移動する点に注意してください。その結果、挿入ポイントが目標位置に置かれます。この考え方は、cpFirst と cpLim が常に次の基本条件に従わなければならない、というものです。

0 <= cpFirst <= cpLim <= ストーリー内の文字数

あるいは範囲 r について同等に 0 <= r.Start <= r.End <= r.StoryLength であり、これはこれらの量の名前から予想されるとおりです。

もう 1 つの重要な特徴は、すべてのストーリーが末尾に削除できない最終 CR (0xD) 文字を含むことです。そのため、空のストーリーでも 1 文字、すなわち最終 CR を持ちます。範囲はこの文字を選択できますが、それより先の挿入ポイントにはなれません。この動作を確認するには、Word 文書で最終 CR を選択し、右方向キーを押して折りたたんでみてください。ディレクトリツリーは最終 CR の手前で折りたたまれますが、CR は削除できません。Text Object Model (TOM) も同じように動作します。したがって、r.Start <= r.End であれば、r.End <= (r.StoryLength – 1) です。CR の削除については、Delete の説明を参照してください。

一部のメソッドは Unit 引数に依存します。この引数は次の表に示す定義済みの値を取ります。

Unit	値	意味
tomCharacter	1	文字。
tomWord	2	単語。
tomSentence	3	文。
tomParagraph	4	段落。
tomLine	5	行(表示上)。
tomStory	6	ストーリー。
tomScreen	7	画面(PAGE UP / PAGE DOWN のような単位)。
tomSection	8	セクション。
tomColumn	9	表の列。
tomRow	10	表の行。
tomWindow	11	ウィンドウの左上または右下。
tomCell	12	表のセル。
tomCharFormat	13	一定の文字書式が連続する範囲。
tomParaFormat	14	一定の段落書式が連続する範囲。
tomTable	15	表。
tomObject	16	埋め込みオブジェクト。

Unit の値のほとんどは説明を要しませんが、明確にするために次の説明を示します。

tomWord

tomWord 定数は、段落の終わり、または後続の空白を含む英数字や句読点の連なりです。tomWord を画面上で体感するには、Word 文書で CTRL+右方向キー (—>) または CTRL+左方向キー (<—) を押したときのキャレットの動きを観察してください。

tomSentence

tomSentence 定数は、ピリオド、疑問符、または感嘆符で終わり、その後に 1 つ以上の ASCII 空白文字(9 から 0xd および 0x20)、または Unicode 段落区切り文字 (0x2029) が続くテキスト文字列を表します。末尾の空白は文の一部です。ストーリー内の最後の文は、ピリオド、疑問符、感嘆符を持つ必要はありません。ストーリーの先頭は、たとえそこにある文字列が文法的に文として成立していなくても、tomSentence の先頭として扱われます。それ以外の文は、文の終わりの後に続く必要があり、ピリオド、疑問符、感嘆符で始めることはできません。

tomParagraph

tomParagraph 定数は、段落終わりのマーク(CRLF、CR、VT (SHIFT+ENTER 用)、LF、FF、または 0x2029)で終端されるテキスト文字列です。TOM エンジンは常に、ストーリーの末尾に削除できない段落終わりのマークを持ちます。したがって、すべての TOM ストーリーは自動的に少なくとも 1 つの tomWord、1 つの tomSentence、1 つの tomParagraph を持ちます。

tomLine

tomLine 定数は、範囲にディスプレイが関連付けられている場合に、ディスプレイ上のテキスト 1 行に対応します。範囲にディスプレイが関連付けられていない場合、tomLine は tomParagraph として扱われます。選択範囲は自動的にディスプレイと、複製(GetDuplicate を参照)である範囲を持ちます。それ以外の範囲は、TOM エンジンやコンテキストによってはディスプレイを持たないことがあります。

Move、MoveEnd、MoveStart のように、Unit 単位で一方または両方の端を移動するメソッドは、符号付きの Count 引数に依存します。ITextSelection の幾何学的な移動コマンドを除き、Count が 0 より大きい場合、移動対象の端は前方(ストーリーの末尾方向)へ移動し、Count が 0 より小さい場合は後方(先頭方向)へ移動します。これらの Move メソッドの Count の既定値は 1 です。これらのメソッドは Count 個のUnit の移動を試みますが、ストーリーの端を越えて移動することはありません。

MoveWhile、MoveEndWhile、MoveStartWhile のように、文字列や文字列パターンの一致によって一方または両方の端を移動するメソッドは、符号付きの Count 引数で指定された最大文字数まで移動できます。Count が 0 より大きい場合、移動対象の端は前方へ移動し、Count が 0 より小さい場合は後方へ移動します。特別な Count 値として tomForward と tomBackward の 2 つが定義されています。これらの値はそれぞれ、ストーリーの末尾と先頭に確実に到達することが保証されます。Count の既定値は tomForward です。

Move、MoveWhile、MoveUntil のように、退化していない範囲を退化した範囲に変える Move* 系メソッドでは、Count が負の場合は cpFirst が変更され、Count が正の場合は cpLim が変更されます。この移動の後、範囲のもう一方の端も新しい位置に移動します。より具体的な Count の情報は、各メソッドを参照してください。退化していない範囲の場合、MoveStart、MoveEnd、MoveStartWhile、MoveEndWhile、MoveStartUntil、MoveEndUntil の各メソッドは、開始位置 (Start) または終了位置 (End) のいずれかを移動します。

tomWord、tomSentence、tomParagraph のように連続した範囲に対応する単位を選択するには、MoveEnd メソッドを使います。tomObject のように連続していない範囲に対応する単位を選択するには、EndOf メソッドを使います。次のオブジェクトは、存在するとしても、かなりの中間テキストの後に現れる可能性があるためです。tomCell 単位を選択するには、範囲が表の内部にある必要があります。

Count 引数と Unit 引数の例と補足説明を以下に示します。なお、TOM エンジンは上記の表のすべての単位をサポートしているとは限りません。たとえば、リッチエディットコントロールはセクションの概念を提供せず、tomSection を指定すると E_NOTIMPL を返します。ただし、TOM エンジンがある単位をサポートしている場合は、その単位は表に示されたインデックス値を持ちます。

通常、アプリケーションが ITextRange インターフェイスを実装することはありません。リッチエディットコントロールなどの Microsoft のテキストソリューションが、TOM 実装の一部として ITextRange を実装します。

アプリケーションは、Range メソッドを呼び出して ITextRange ポインターを取得できます。

この範囲のプレーンテキストを取得します。Text プロパティは ITextRange インターフェイスの既定のプロパティです。

型: HRESULT

成功した場合は S_OK を返します。失敗した場合は、次のいずれかのエラーコードを返します。COM のエラーコードについて詳しくは、COM のエラー処理を参照してください。

戻り値	説明
E_INVALIDARG	pbstr が null です。
E_OUTOFMEMORY	テキストを保持するのに十分なメモリがありません。

ITextRange::GetText メソッドは、範囲内のプレーンテキストを返します。Text プロパティは ITextRange の既定のプロパティです。つまり、次の Microsoft Visual Basic for Applications (VBA) の例のように、範囲に対して自動的に呼び出されます。

print range

以下の例のいくつかは、この事実を利用しています。ITextRange::SetText メソッドは、範囲のテキストを bstr で置き換えます。1 文字だけを処理する場合、Char プロパティは Text プロパティより効率的で、1 文字を格納するために 1 文字分の範囲を作成する必要もありません。範囲が退化している場合、Text プロパティを使うとテキストを簡単に挿入できます。次の VBA の例に示すように、範囲内のテキストを削除することもできます。

range.delete

range = ""

Text プロパティを使うと、一方の範囲をもう一方の範囲と等しく設定するだけで、ある場所から別の場所へプレーンテキストをコピーできます。(これは Duplicate プロパティとはまったく異なります。詳しくは ITextRange::GetDuplicate を参照してください)。次の Microsoft Visual Basic の例文は、range1 のテキストを range2 のテキストに設定します。

range1 = range2 ' Replace range1's text by range2's

これらの範囲は、異なるストーリー、あるいは異なるアプリケーションにあってもかまいません。ただし、これはテキストをまず BSTR にコピーし、その文字列からコピー先の場所へコピーすることを意味します。大量のテキストの場合、ITextRange::Copy と ITextRange::Paste メソッドの方が高速な場合があります。これらはコピー元からコピー先へ直接、かつコピー元とコピー先の両方がサポートする任意の形式でコピーを実行できるためです。

Text プロパティが返すテキストは Unicode で表現されます。段落終わりのマークは、元のファイルに応じて 0x2029 (Unicode 段落区切り文字)、キャリッジリターン / ラインフィード (CR/LF) (0xd, 0xa)、またはキャリッジリターン単独で表される場合があります。Microsoft Word は、ファイル、クリップボード、または IDataObject から別の選択を読み込まない限り、キャリッジリターン単独を使います。埋め込みオブジェクトのプレースホルダーは、Unicode 値 0xFFFC を持つ特殊文字 WCH_EMBEDDING で表されます。

この範囲にテキストを設定します。

型: HRESULT

このメソッドは HRESULT 値を返します。成功した場合は S_OK を返します。失敗した場合は、次のいずれかのエラーコードを返します。COM のエラーコードについて詳しくは、COM のエラー処理を参照してください。

戻り値	説明
E_ACCESSDENIED	テキストが書き込み保護されています。
E_INVALIDARG	bstr が null です。
E_OUTOFMEMORY	メモリ不足です。

ITextRange::SetText は、範囲内のテキストを新しいテキストで置き換えます。これに対し、TypeText は選択範囲をテキスト bstr で置き換え、あたかもそのテキストを入力したかのように、挿入したテキストの直後に挿入ポイントとして選択範囲を残します。UI での選択の動作については、TypeText を参照してください。

ITextRange::SetText を呼び出した後に ITextRange::GetText を呼び出すと、(呼び出しの間に他の範囲がそのテキストを変更していない限り)ITextRange::SetText メソッドで設定したのと同じテキストが返されます。

範囲の開始位置にある文字を取得します。

型: HRESULT

このメソッドは HRESULT 値を返します。成功した場合は S_OK を返します。pChar が null の場合、メソッドは失敗し、E_INVALIDARG を返します。

次の Microsoft Visual Basic の例は、ch を範囲の先頭にある文字に設定します。

ch = r.Char

同様に、ITextRange::SetChar は、範囲の先頭にある文字を指定した文字で上書きします。これらのメソッドで取得・設定される文字は LONG 変数であり、バッキングストアでの格納方法(バイト、ワード、可変長など)を隠蔽し、BSTR を使う必要がありません。

Char プロパティは、文字コレクションでできることのほとんどを行えますが、2 つの大きな利点があります。

• 親範囲に限定されず、親ストーリー内の任意の文字を参照できます。
• 範囲オブジェクトではなく LONG を扱うため、大幅に高速です。

このため、Text Object Model (TOM) は文字コレクションをサポートしていません。

範囲の開始位置にある文字を設定します。

型: HRESULT

このメソッドは HRESULT 値を返します。成功した場合は S_OK を返します。失敗した場合は、次のいずれかのエラーコードを返します。COM のエラーコードについて詳しくは、COM のエラー処理を参照してください。

戻り値	説明
E_ACCESSDENIED	テキストが書き込み保護されています。
E_OUTOFMEMORY	メモリ不足です。

ITextRange::SetChar を使うと、使用する正確な文字コードを指定できます。ただし、見た目の似たグリフを持つ文字列リテラルは誤解を招くことがあります。

このメソッドで設定される文字は BSTR ではなく LONG です。これにより、バッキングストアでの格納方法(バイト、ワード、可変長など)が隠蔽されます。

自動的な折り返しを行わないシステムでは、文書に改行のためだけのハードキャリッジリターンが挿入されていることがよくあります。次のコードは、範囲 r に関連付けられたストーリーについて、そのようなハードキャリッジリターンを空白に戻す、単純ですが完全ではない方法を示しています。

    Sub EnableWrap(r As ITextRange)   // 見せかけのハード CR をソフトに変換
        r.SetRange 0, 0               // r をストーリーの先頭に設定
        While r.Move(tomParagraph)    // 次の段落の先頭へ移動
            If r.MoveWhile(C1_WHITE, 1) = 0 Then    // 次の文字が空白でない場合
                r.Move tomCharacter, -1
                r.SetChar = Asc(" ")    // CR を空白に置換
            End If
        Wend        // ストーリーに CR がなくなるまでループ
    End Sub

あるいは、IF ループ内で次のコードを使うこともできます。

r.MoveStart tomCharacter, -1        // 直前の文字(CR)を選択
r = " "        // 空白に置換

この方法により、テキストを別の幅に折り返すことができます。ただし、このアルゴリズムは完全ではありません。空白以外(空白、タブ、ラインフィード、キャリッジリターンなど)が後に続くハードキャリッジリターンは空白に置き換えるべきである、と想定しています。また、キャリッジリターン文字がキャリッジリターンや Unicode の段落終わり (EOP) 0x2029 文字のような単一文字であることも想定しています。さらに、キャリッジリターンとラインフィードの組み合わせは一致せず、さらに多くのコードを記述して実行する必要があります(または FindText(^p) を使います)。もう 1 つの注意点として、コードとドキュメントが混在する場合など、このアルゴリズムが正しく動作しないケースが他にもあります。

ただし、ITextRange::SetChar は、削除に続いて挿入を行う置換操作よりも効率的です。そのため、ITextRange::SetChar を使わずにコードを書き直すと、おそらくはるかに遅くなります。

Char プロパティは、文字コレクションでできることのほとんどを行えますが、2 つの大きな利点があります。親範囲に限定されず、親ストーリー内の任意の文字を参照できること、そして範囲オブジェクトではなく LONG を扱うため大幅に高速であることです。これらの利点のため、Text Object Model (TOM) は文字コレクションをサポートしていません。

この範囲オブジェクトの複製を取得します。

型: HRESULT

このメソッドは HRESULT 値を返します。成功した場合は S_OK を返します。失敗した場合は、次のいずれかのエラーコードを返します。COM のエラーコードについて詳しくは、COM のエラー処理を参照してください。

戻り値	説明
E_INVALIDARG	ppRange が null です。
E_FAIL	その他の理由による失敗です。

範囲をたどるための挿入ポイントを作成するには、まず範囲を複製し、次にその複製を開始文字位置で折りたたみます。なお、範囲は開始と終了の文字位置、および属するストーリーによって特徴付けられます。

範囲が実際には ITextSelection であっても、返される複製は ITextRange です。例については、ITextRange::FindText メソッドを参照してください。

指定した範囲の書式付きテキストを持つ ITextRange オブジェクトを取得します。

型: HRESULT

成功した場合は S_OK を返します。失敗した場合は、次のいずれかのエラーコードを返します。COM のエラーコードについて詳しくは、COM のエラー処理を参照してください。

戻り値	説明
E_INVALIDARG	ppRange が null です。
E_OUTOFMEMORY	メモリ不足です。

このメソッドは、実質的に ITextRange::GetDuplicate メソッドの別名であり、Microsoft Visual Basic for Applications (VBA) で扱いやすくするために含まれています。このメソッドは範囲内の書式付きテキストを返します。ITextRange が同じ Text Object Model (TOM) エンジンに属していない場合は、IUnknown::QueryInterface を呼び出して IDataObject インターフェイスを取得します。

IDataObject が通常サポートする形式には、CF_TEXT と CF_RTF があります。さらに、プライベート形式を使って、テキストソリューション独自の内部リッチテキスト形式を参照することもできます。次の Microsoft Visual Basic の例は、FormattedText プロパティを使って、range2 のテキストを range1 の書式付きテキストで置き換えます。

range2.FormattedText = range1.FormattedText

この範囲のテキストの書式付きテキストを、指定した範囲の書式付きテキストに設定します。

型: HRESULT

成功した場合は S_OK を返します。失敗した場合は、次のいずれかのエラーコードを返します。COM のエラーコードについて詳しくは、COM のエラー処理を参照してください。

戻り値	説明
E_ACCESSDENIED	テキストが保護されています。
E_INVALIDARG	pRange が null です。
E_OUTOFMEMORY	メモリ不足です。

ITextRange が同じ Text Object Model (TOM) エンジンに属していない場合は、IUnknown::QueryInterface を呼び出して IDataObject インターフェイスを取得します。

IDataObject が通常サポートする形式には、CF_TEXT と CF_RTF があります。さらに、プライベート形式を使って、テキストソリューション独自の内部リッチテキスト形式を参照することもできます。次の Microsoft Visual Basic の例は、FormattedText プロパティを使って、range2 のテキストを range1 の書式付きテキストで置き換えます。

range2.FormattedText = range1.FormattedText

範囲の開始文字位置を取得します。

型: HRESULT

このメソッドは HRESULT 値を返します。成功した場合は S_OK を返します。pcpFirst が null の場合、メソッドは失敗し、E_INVALIDARG を返します。

この範囲の開始の文字位置を設定します。

型: HRESULT

このメソッドは HRESULT 値を返します。成功した場合は S_OK を返します。失敗した場合は S_FALSE を返します。

cpFirst が範囲の終了位置より大きい場合、このメソッドは終了位置を cpFirst に等しく設定し、範囲を挿入ポイントにする点に注意してください。この範囲が選択範囲の場合、開始位置がアクティブ端になり、ディスプレイが固定されていなければスクロールして表示されます。

ITextRange::SetEnd は範囲の終了位置を設定し、ITextRange::SetRange は範囲の両端を同時に設定します。次の例は、退化していない範囲を退化した範囲(挿入ポイント)に変換する方法を示しています。

range.End = range.Start

同様に、range.Start = range.End は範囲を終了位置の挿入ポイントに変換します。

次の例は、終了位置がストーリーの末尾でない場合に、終了位置に 1 を加えます。

range.End = range.End + 1

これにより、終了位置が範囲のアクティブ端になり、退化した範囲を退化していない範囲に変えることができます。

範囲の終了文字位置を取得します。

型: HRESULT

このメソッドは HRESULT 値を返します。成功した場合は S_OK を返します。pcpLim が null の場合、メソッドは失敗し、E_INVALIDARG を返します。

範囲へのポインターはテキストが編集されても有効なままですが、文字位置についてはそうではありません。文字位置は揮発性です。つまり、その文字位置より前にテキストが挿入または削除されるとすぐに無効になります。文字位置の値を返すメソッドの使用には注意してください。特に、その値を一定期間保存する場合は注意が必要です。

このメソッドは、範囲の開始文字位置を取得する ITextRange::GetStart メソッドに似ています。

範囲の終了位置を設定します。

型: HRESULT

このメソッドは HRESULT 値を返します。成功した場合は S_OK を返します。失敗した場合は S_FALSE を返します。

新しい終了位置が開始位置より小さい場合、このメソッドは開始位置も cp に設定します。つまり、範囲は挿入ポイントになります。

この範囲が実際には選択範囲の場合、終了位置がアクティブ端になり、ディスプレイが固定されていなければスクロールして表示されます。

ITextRange::SetStart は範囲の開始位置を設定し、ITextRange::SetRange は範囲の両端を同時に設定します。退化していない範囲 r を開始位置の退化した範囲(挿入ポイント)に変換するには、次を使います。

r.End = r.Start

同様に、r.Start = r.End は r を終了位置の挿入ポイントに変換します。

終了位置がストーリーの末尾でない場合に終了位置に 1 を加えるには、次を使います。

r.End = r.End + 1

これにより、終了位置がアクティブ端になり、退化した範囲を退化していない範囲に変えることができます。

指定した範囲の文字属性を持つ ITextFont オブジェクトを取得します。

型: HRESULT

このメソッドは HRESULT 値を返します。成功した場合は S_OK を返します。ppFont が null の場合、メソッドは失敗し、E_INVALIDARG を返します。

プレーンテキストコントロールでは、これらのオブジェクトは範囲ごとに変化しませんが、リッチテキストのソリューションでは変化します。詳しくは ITextFont のセクションを参照してください。

この範囲の文字属性を、指定した ITextFont オブジェクトの文字属性に設定します。

型: HRESULT

このメソッドは HRESULT 値を返します。成功した場合は S_OK を返します。失敗した場合は、次のいずれかのエラーコードを返します。COM のエラーコードについて詳しくは、COM のエラー処理を参照してください。

戻り値	説明
値	意味
E_ACCESSDENIED	テキストが保護されています。
E_INVALIDARG	pFont が null です。
E_OUTOFMEMORY	メモリ不足です。

たまに書式を変更する場合は、ITextRange::SetFont メソッドを使います。ただし、多数の文字書式変更を行う場合は、フォントの複製を使う方が効率的です。これは、range.font.bold = tomTrue のような文を実行するたびに、フォントオブジェクトが確保・解放されるためです。一方、フォントの複製は一度確保して何度も使えます。さらに、フォントの複製を保存し、Reset メソッドで既定状態または未定義状態にリセットし、リッチテキスト処理の必要に応じて値を設定できます。フォントの複製の使い方を示すサンプルコードについては、Using a Font Duplicate を参照してください。

指定した範囲の段落属性を持つ ITextPara オブジェクトを取得します。

型: HRESULT

このメソッドは HRESULT 値を返します。成功した場合は S_OK を返します。ppPara が null の場合、メソッドは失敗し、E_INVALIDARG を返します。

プレーンテキストコントロールでは、これらのオブジェクトは範囲ごとに変化しませんが、リッチテキストのソリューションでは変化します。詳しくは ITextPara のセクションを参照してください。

この範囲の段落属性を、指定した ITextPara オブジェクトの段落属性に設定します。

型: HRESULT

このメソッドは HRESULT 値を返します。成功した場合は S_OK を返します。失敗した場合は、次のいずれかのエラーコードを返します。COM のエラーコードについて詳しくは、COM のエラー処理を参照してください。

戻り値	説明
E_ACCESSDENIED	テキストが書き込み保護されています。
E_INVALIDARG	pPara が null です。
E_OUTOFMEMORY	メモリ不足です。

範囲のストーリー内の文字数を取得します。

型: HRESULT

このメソッドは HRESULT 値を返します。成功した場合は S_OK を返します。pCount が null の場合、メソッドは失敗し、E_INVALIDARG を返します。

範囲のストーリーの種類を取得します。

型: HRESULT

このメソッドは HRESULT 値を返します。成功した場合は S_OK を返します。pValue が null の場合、メソッドは失敗し、E_INVALIDARG を返します。

指定したテキスト範囲を、範囲の先頭または末尾の退化したポイントに折りたたみます。

型: HRESULT

このメソッドは HRESULT 値を返します。成功した場合は S_OK を返します。それ以外の場合は S_FALSE を返します。

この範囲に含まれる部分的な単位が完全に含まれるように、この範囲を拡張します。

型: HRESULT

このメソッドは HRESULT 値を返します。成功した場合は S_OK を返します。失敗した場合は、次のいずれかのエラーコードを返します。COM のエラーコードについて詳しくは、COM のエラー処理を参照してください。

戻り値	説明
E_NOTIMPL	Unit がサポートされていません。
S_FALSE	その他の理由による失敗です。

たとえば、挿入ポイントが単語の先頭、末尾、または内部にある場合、ITextRange::Expand はその単語を含むように範囲を拡張します。範囲がすでに 1 つの単語と別の単語の一部を含んでいる場合、ITextRange::Expand は両方の単語を含むように範囲を拡張します。ITextRange::Expand は、範囲のストーリーの可視部分を含むように範囲を拡張します。

指定した範囲の Start 文字位置における Unit パラメーターのストーリーインデックスを取得します。

型: HRESULT

このメソッドは HRESULT 値を返します。成功した場合は S_OK を返します。失敗した場合は、次のいずれかのエラーコードを返します。COM のエラーコードについて詳しくは、COM のエラー処理を参照してください。

戻り値	説明
E_INVALIDARG	pIndex が null です。
E_NOTIMPL	Unit が存在しません。

ITextRange::GetIndex メソッドは、範囲の Start における単語、行、文、段落などのストーリーインデックスを取得します。Unit は、インデックスを付ける対象の種類(単語 (tomWord)、行 (tomLine)、文 (tomSentence)、段落 (tomParagraph) など)を指定します。たとえば、ITextRange::GetIndex は pIndex を範囲内の最初の行の行番号に設定します。ストーリーの末尾にある範囲の場合、ITextRange::GetIndex はストーリー内の Unit の数を返します。このようにして、ストーリー内の単語、行、オブジェクトなどの数を取得できます。

ITextRange::GetIndex メソッドが返すインデックス値は、その後テキストが編集されると無効になります。そのため、インデックス値を返すメソッドの使用には注意してください。特に、その値を一定期間保存する場合は注意が必要です。これは、テキストが編集されても有効なままである範囲へのポインターとは対照的です。

この範囲を、ストーリー内の指定した単位に変更します。

型: HRESULT

このメソッドは HRESULT 値を返します。成功した場合は S_OK を返します。失敗した場合は、次のいずれかのエラーコードを返します。COM のエラーコードについて詳しくは、COM のエラー処理を参照してください。

戻り値	説明
E_INVALIDARG	Index が無効です。
E_NOTIMPL	Unit がサポートされていません。
S_FALSE	その他の理由による失敗です。

このメソッドを使うと、アプリケーションはプログラムのような行指向のテキストを便利に扱えます。たとえば、SetIndex(tomLine, 10, 0) は範囲を 10 行目の先頭にある挿入ポイントに変換します。

範囲の端点を指定した値に調整します。

型: HRESULT

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

このメソッドは、範囲の開始位置を min(cpActive, cpAnchor) に、終了位置を max(cpActive, cpAnchor) に設定します。範囲が退化していない選択範囲の場合、cpActive がアクティブ端で、cpAnchor がアンカー端です。範囲が退化した選択範囲の場合、選択範囲は前の行の末尾ではなく、行の先頭に表示されます。

このメソッドは、この範囲が持つ可能性のある他のサブ範囲をすべて削除します。現在のサブ範囲を保持するには、ITextRange2::SetActiveSubrange を使います。

テキスト範囲が選択範囲の場合、ITextSelection::SetFlags メソッドを使って選択範囲の属性を設定できます。

この範囲が、指定した範囲の内部にあるか、または同じテキスト上にあるかを判定します。

型: HRESULT

このメソッドは HRESULT 値を返します。成功した場合は S_OK を返します。失敗した場合は S_FALSE を返します。

range2 が range1 に含まれるには、両方の範囲が同じストーリーにあり、range2 の限界が次のいずれかの条件を満たす必要があります。

• range1 の開始と終了の文字位置が range2 と同じである。つまり、両方の範囲が退化しており、同一の挿入ポイントを持つ。
• range2 が退化していない範囲で、開始と終了の文字位置が range1 の位置と同じか、その内部にある。

次の例は、ある範囲でもう 1 つの範囲をたどる方法を示しています。

    range2 = range1.Duplicate
    range2.End = range2.Start       ' range2 を開始位置に折りたたむ
    While range2.InRange(range1)    ' range2 が range1 の内部にある間、繰り返す
         ...   ' このコードで range2 の文字位置を変更する
    Wend

ITextRange::FindText、ITextRange::MoveWhile、ITextRange::MoveUntil の各メソッドファミリを使う場合、適切な文字数の限界を指定することで、ある範囲でもう 1 つの範囲をたどることができます(例については、ITextRange::Find の「解説」を参照してください)。

ITextRange::IsEqual は ITextRange::InRange の特別なケースで、pRange が同じ開始・終了の文字位置を持ち、同じストーリーに属している場合に pB を tomTrue にして返します。

この範囲のストーリーが、指定した範囲のストーリーと同じかどうかを判定します。

型: HRESULT

このメソッドは HRESULT 値を返します。2 つのストーリーが同じ場合、このメソッドは S_OK を返します。それ以外の場合は S_FALSE を返します。

この範囲が、指定した範囲と同じ文字位置およびストーリーを持つかどうかを判定します。

型: HRESULT

このメソッドは HRESULT 値を返します。範囲が同じ文字位置とストーリーを持つ場合、このメソッドは S_OK を返します。それ以外の場合は S_FALSE を返します。

ITextRange::IsEqual メソッドは、範囲が pRange と同じテキストを指している場合にのみ tomTrue を返します。2 つの異なるテキストが同じプレーンテキストと同じ文字書式を含むかどうかを比較するコードについては、Finding Rich Text を参照してください。

アクティブな選択範囲の開始位置、終了位置、およびストーリーの値を、この範囲の値に設定します。

型: HRESULT

このメソッドは HRESULT 値を返します。成功した場合は S_OK を返します。失敗した場合は S_FALSE を返します。

新しい選択範囲のアクティブ端は終了位置にあります。

あいまいな文字位置のキャレットは、行の先頭に表示されます。

範囲の端を、範囲内で最初に重なる Unit の先頭に移動します。

型: HRESULT

このメソッドは HRESULT 値を返します。成功した場合は S_OK を返します。失敗した場合は、次のいずれかのエラーコードを返します。COM のエラーコードについて詳しくは、COM のエラー処理を参照してください。

戻り値	説明
E_NOTIMPL	Unit がサポートされていません。
S_FALSE	その他の理由による失敗です。

範囲が Unit 間の境界上にある挿入ポイントの場合、ITextRange::StartOf は開始位置を変更しません。

ITextRange::StartOf と ITextRange::EndOf メソッドは、HomeKey と EndKey メソッドとは異なります。後者はアクティブ端から拡張しますが、ITextRange::StartOf は開始位置から拡張し、ITextRange::EndOf は終了位置から拡張します。

この範囲の端を、範囲内で最後に重なる Unit の末尾に移動します。

型: HRESULT

このメソッドは HRESULT 値を返します。成功した場合は S_OK を返します。失敗した場合は、次のいずれかのエラーコードを返します。COM のエラーコードについて詳しくは、COM のエラー処理を参照してください。

戻り値	説明
E_NOTIMPL	Unit がサポートされていません。
S_FALSE	その他の理由による失敗です。

比較として、ITextRange::StartOf メソッドは範囲の端を、範囲内で最初に重なる Unit の先頭に移動します。なお、ITextRange::StartOf と ITextRange::EndOf メソッドは、HomeKey と EndKey メソッドとは異なります。後者はアクティブ端から拡張しますが、ITextRange::StartOf は Start から拡張し、ITextRange::EndOf は End から拡張します。範囲が Unit 間の境界上にある挿入ポイントの場合、ITextRange::EndOf は End を変更しません。特に、ITextRange::EndOf (tomCharacter, *, *) を呼び出しても、ストーリーの先頭にある挿入ポイントを除いて End は変更されません。

挿入ポイントを、指定した数の単位だけ前方または後方に移動します。範囲が退化していない場合、Count に応じていずれかの端の挿入ポイントに範囲を折りたたんでから移動します。

型: HRESULT

このメソッドは HRESULT 値を返します。挿入ポイントの移動に成功した場合は S_OK を返します。失敗した場合は、次のいずれかのエラーコードを返します。COM のエラーコードについて詳しくは、COM のエラー処理を参照してください。

戻り値	説明
E_NOTIMPL	Unit がサポートされていません。
S_FALSE	その他の理由による失敗です。

範囲が退化している(挿入ポイントである)場合、このメソッドは挿入ポイントを Count 個の Unit だけ移動しようとします。

範囲が退化しておらず、Count が 0 より大きい場合、このメソッドは範囲を終了文字位置で折りたたみ、結果として得られる挿入ポイントを(まだ Unit 境界にない場合は)前方の Unit 境界へ移動し、その後 Count - 1 個の Unit だけ前方へ移動しようとします。範囲が退化しておらず、Count が 0 より小さい場合、このメソッドは範囲を開始文字位置で折りたたみ、結果として得られる挿入ポイントを(まだ境界にない場合は)後方の Unit 境界へ移動し、その後 |Count| - 1 個の Unit だけ後方へ移動しようとします。したがって、どちらの場合も、退化していない範囲を挿入ポイントに折りたたむことは、折りたたみ後に Unit の先頭と末尾のどちらへ移動する場合でも、1 つの Unit として数えられます。

ITextRange::Move メソッドは、pDelta = 実際に移動した Unit の数を返します。このメソッドは、この範囲のストーリーを越えて挿入ポイントを移動することは決してありません。Count 個の Unit によって挿入ポイントがストーリーの先頭より前に移動する場合、挿入ポイントはストーリーの先頭に移動し、pDelta はそれに応じて設定されます。同様に、Count 個の Unit によってストーリーの末尾より先に移動する場合、挿入ポイントはストーリーの末尾に移動します。

ITextRange::Move メソッドは、UI 指向の MoveLeft と MoveRight メソッドと同様に動作しますが、移動方向が幾何学的ではなく論理的である点が異なります。つまり、ITextRange::Move では方向はストーリーの末尾方向または先頭方向のいずれかです。言語によっては、ストーリーの末尾方向への移動が左方向にも右方向にもなり得ます。Count を体感するには、Microsoft Word 文書でさまざまな選択に対して Ctrl+右方向キーを押してみてください。左から右へのテキストでは、このキー操作は Move(tomWord, 1) や MoveRight(tomWord, 1) と同じように動作します。Count は Ctrl+右方向キーを押した回数に対応します。

たとえば、次の 2 つの図に示す選択に対して Ctrl+右方向キーを押すと、いずれの場合も文字位置 8 の挿入ポイントになります。このコマンドは選択をその終了文字位置(それぞれ 7 と 8)で折りたたみ、次の tomWord 境界へ移動するためです。

最初の選択は文字位置 7 の空白を含まないため、Ctrl+右方向キーは空白を越えて文字位置 8 の tomWord 境界へ移動します。2 番目の選択では終了文字位置がすでに tomWord 境界にあるため、Ctrl+右方向キーはその境界で選択を折りたたむだけです。同様に、このテキストでは Move(tomWord, -1) や MoveLeft(tomWord, 1) のように動作する Ctrl+左方向キーは、最初の選択を文字位置 5 で折りたたみますが、そこはすでに tomWord 境界であるため、それ以上の移動は起こりません。一方、Ctrl+左方向キーは 2 番目の選択を文字位置 4 で折りたたみ、その後 0 へ移動します。そこが移動方向における次の tomWord 境界だからです。

戻り引数 pDelta は、退化していない範囲を折りたたんで Unit 境界へ移動する分の 1 Unit を含めて、挿入ポイントが移動した Unit の数に設定されます。したがって、範囲がストーリーの末尾にある挿入ポイントの場合のように、移動も折りたたみも起こらないときは、pDelta は 0 に設定されます。この方法は、ストーリー全体を処理するプログラムループを制御するのに便利です。

前述の両方のケースで、Move(tomWord, 1) を呼び出すと、範囲が折りたたまれたため pDelta は 1 に設定されます。同様に、Move(tomWord, -1) を呼び出すと、両方のケースで pDelta は -1 に設定されます。Unit の一部を Unit 境界へ移動する場合もしない場合も、折りたたみは移動した 1 Unit として数えられます。

移動方向は、プレーンテキストのバッキングストアにおける論理的な文字の順序を指します。この方法は、国際化ソフトウェアにおける左対右、上対下といった幾何学的な順序の問題を回避します。もちろん、キーボードにはそれらを呼び出す方向キーがあるため、そのような幾何学的なメソッドは編集エンジンでは依然として必要です。範囲が実際には ITextSelection オブジェクトの場合、MoveLeft や MoveRight のようなメソッドを使えます。

Unit が文字 (tomCharacter) を指定する場合、Text Object Model (TOM) は Unicode 文字セットを使います。Unicode とマルチバイト文字セットの間の変換には、MultiByteToWideChar 関数と WideCharToMultiByte 関数が、それぞれインポート時とエクスポート時に Unicode とマルチバイト文字セットを簡単に変換する手段を提供します。詳しくは、Open を参照してください。これに関連して、段落を区切るためにキャリッジリターン / ラインフィード (CR/LF) を使うことは、ダブルバイト文字セット (DBCS) と同じくらい問題があります。ITextSelection の UI メソッドは、CR/LF を 1 文字であるかのように戻りますが、ITextRange::Move メソッドは CR/LF を 2 文字として数えます。段落区切りには単一文字を使う方が明らかに優れており、TOM ではこれはキャラクターリターンで表されます(ただし Unicode 段落区切り文字 0x2029 も受け付けられます)。一般に、TOM エンジンは CR/LF、キャリッジリターン (CR)、ラインフィード (LF)、垂直タブ、フォームフィード、0x2029 をサポートすべきです。Microsoft Rich Edit 2.0 は、下位互換性のために CR/CR/LF もサポートします。

範囲の Start または End の位置をそれぞれ Count 個の Unit だけ移動する ITextRange::MoveStart と ITextRange::MoveEnd メソッドも参照してください。

範囲の開始位置を、指定した方向に指定した数の単位だけ移動します。

型: HRESULT

このメソッドは HRESULT 値を返します。成功した場合は S_OK を返します。失敗した場合は、次のいずれかのエラーコードを返します。COM のエラーコードについて詳しくは、COM のエラー処理を参照してください。

戻り値	説明
E_NOTIMPL	Unit がサポートされていません。
S_FALSE	その他の理由による失敗です。

新しい開始位置が古い終了位置より後になる場合、新しい終了位置は新しい開始位置に等しく設定されます。

ITextRange::MoveStart が示す移動は、幾何学的ではなく論理的です。つまり、移動はストーリーの末尾方向または先頭方向へ向かいます。言語によっては、ストーリーの末尾方向への移動が左方向か右方向のいずれかになることがあります。

詳しくは、ITextRange と ITextRange::Move を参照してください。

範囲の終了位置を移動します。

型: HRESULT

このメソッドは HRESULT 値を返します。成功した場合は S_OK を返します。失敗した場合は、次のいずれかのエラーコードを返します。COM のエラーコードについて詳しくは、COM のエラー処理を参照してください。

戻り値	説明
E_NOTIMPL	Unit がサポートされていません。
S_FALSE	その他の理由による失敗です。

新しい終了位置が古い開始位置より前になる場合、新しい開始位置は新しい終了位置に等しく設定されます。つまり、退化した範囲または挿入ポイントになります。

ITextRange::MoveEnd が示す移動は、幾何学的ではなく論理的です。つまり、移動はストーリーの末尾方向または先頭方向へ向かいます。言語によっては、ストーリーの末尾方向への移動が左方向か右方向のいずれかになることがあります。

詳しくは、ITextRange と ITextRange::Move を参照してください。

範囲の指定した端から開始し、文字が Cset で指定されたセットに属し、かつ文字数が Count 以下である間、検索します。

型: HRESULT

このメソッドは HRESULT 値を返します。成功した場合は S_OK を返します。失敗した場合は、次のいずれかのエラーコードを返します。COM のエラーコードについて詳しくは、COM のエラー処理を参照してください。

戻り値	説明
E_INVALIDARG	Cset が無効です。
S_FALSE	その他の理由による失敗です。

ITextRange::MoveUntil が示す移動は、幾何学的ではなく論理的です。つまり、移動はストーリーの末尾方向または先頭方向へ向かいます。言語によっては、ストーリーの末尾方向への移動が左方向か右方向のいずれかになることがあります。

詳しくは、ITextRange の説明と ITextRange::Move の「解説」セクションを参照してください。

ITextRange::MoveWhile メソッドは ITextRange::MoveUntil に似ていますが、MoveWhile は Cset で指定されたセットのメンバーが見つかる間検索を続け、pDelta の値への追加の増分はありません。

ITextRange::MoveStartWhile と ITextRange::MoveEndWhile メソッドは、Cset パラメーターで指定された文字セットに含まれる連続する文字をすべて越えた直後まで、それぞれ start と end を移動します。

VARIANT 型は主に、Microsoft Visual Basic for Applications (VBA) のような IDispatch のシナリオでの使用を意図していますが、C や C++ からも簡単に使えます。次の C++ コードは、範囲 r 内で数字の連なりを照合するために VARIANT 引数を初期化して使う方法を示しています。

VariantInit(&varg);
varg.vt = VT_I4;
varg.lVal = C1_DIGIT;
hr = r.MoveWhile(&varg, tomForward, pDelta); // 挿入ポイントを数字の連なりを越えて移動

あるいは、次のサンプルのように明示的な文字列を使うこともできます。

VariantInit(&varg);
bstr = SysAllocString("0123456789");
varg.vt = VT_BSTR;
varg.bstr = bstr;
hr =r.MoveWhile(&varg, tomForward, pDelta);    // 挿入ポイントを数字の連なりを越えて移動

次の VBA のサンプルコードは、範囲 r 内で次の Standard Generalized Markup Language (SGML) エントリの本体を照合します。SGML エントリは <keyword ...> で始まり、</keyword> で終わります。

r.Find <                  // 次のタグの先頭へ移動
r.MoveWhile C1_SPACE      // 空白文字をスキップ
r.MoveEndWhile C1_ALPHA   // キーワードを照合
s$ = </ + r               // 検索用の VBA 文字列を作成
r.Find >                  // 開始タグの残りをスキップ
r.FindEnd s$              // 閉じキーワードの末尾まで照合
r.FindEnd <, tomStart     // 終了タグの先頭まで戻る
                          // r に SGML エントリの本体が入る

範囲の開始位置を、Count 文字分、または Cset で指定された文字セットに含まれる連続する文字をすべて越えた直後までのいずれか短い方だけ移動します。

型: HRESULT

このメソッドは HRESULT 値を返します。成功した場合は S_OK を返します。失敗した場合は、次のいずれかのエラーコードを返します。COM のエラーコードについて詳しくは、COM のエラー処理を参照してください。

戻り値	説明
E_INVALIDARG	Cset が無効です。
S_FALSE	その他の理由による失敗です。

新しい開始位置が古い終了位置より後になる場合、新しい終了位置は新しい開始位置に等しく設定されます。

ITextRange::MoveStartWhile が示す移動は、幾何学的ではなく論理的です。つまり、移動はストーリーの末尾方向または先頭方向へ向かいます。言語によっては、ストーリーの末尾方向への移動が左方向か右方向のいずれかになることがあります。

詳しくは、ITextRange と ITextRange::Move を参照してください。

範囲の終了を、Count 文字分、または Cset で指定された文字セットに含まれる連続する文字をすべて越えた直後までのいずれか短い方だけ移動します。

型: HRESULT

このメソッドは HRESULT 値を返します。成功した場合は S_OK を返します。失敗した場合は、次のいずれかのエラーコードを返します。COM のエラーコードについて詳しくは、COM のエラー処理を参照してください。

戻り値	説明
E_INVALIDARG	Cset が無効です。
S_FALSE	その他の理由による失敗です。

新しい終了位置が古い開始位置より前になる場合、新しい開始位置は新しい終了位置に等しく設定されます。

ITextRange::MoveEndWhile が示す移動は、幾何学的ではなく論理的です。つまり、移動はストーリーの末尾方向または先頭方向へ向かいます。言語によっては、ストーリーの末尾方向への移動が左方向か右方向のいずれかになることがあります。

詳しくは、ITextRange と ITextRange::Move を参照してください。

Cset で指定された文字セット内の最初の文字を、最大 Count 文字まで検索します。文字が見つかった場合、範囲はその位置に折りたたまれます。検索の開始位置と方向も Count で指定します。

型: HRESULT

このメソッドは HRESULT 値を返します。成功した場合は S_OK を返します。失敗した場合は、次のいずれかのエラーコードを返します。COM のエラーコードについて詳しくは、COM のエラー処理を参照してください。

戻り値	説明
E_INVALIDARG	Cset が無効です。
S_FALSE	その他の理由による失敗です。

一致する文字がない場合、範囲は変更されません。

ITextRange::MoveUntil が示す移動は、幾何学的ではなく論理的です。つまり、移動はストーリーの末尾方向または先頭方向へ向かいます。言語によっては、ストーリーの末尾方向への移動が左方向か右方向のいずれかになることがあります。

詳しくは、ITextRange と ITextRange::Move の「解説」セクションを参照してください。

ITextRange::MoveStartUntil と ITextRange::MoveEndUntil メソッドは、Cset パラメーターで指定されたセットにも含まれる最初の文字が見つかるまで、それぞれ start と end を移動します。

ITextRange::MoveUntil メソッドは ITextRange::MoveWhile に似ていますが、2 つの違いがあります。1 つ目は、MoveUntil は Cset で指定された文字セットに属する最初の文字が見つかるまで挿入ポイントを移動することです。2 つ目は、MoveUntil では、一致した文字が pDelta に返される値の中で追加の 1 文字として数えられることです。これにより、挿入ポイントは範囲のいずれかの端にとどまったままでも、範囲の一方の端の文字が Cset に属することがわかります。

たとえば、範囲 r が挿入ポイントであるとします。r にある文字(つまり r.GetChar() で得られる文字)が Cset に含まれるかどうかを調べるには、次を呼び出します。

r.MoveUntil(Cset, 1)

その文字が Cset に含まれる場合、戻り値は 1 で、挿入ポイントは移動しません。同様に、r の直前の文字が Cset に含まれるかどうかを調べるには、次を呼び出します。

r.MoveUntil(Cset, -1)

その文字が Cset に含まれる場合、戻り値は –1 です。

次の Microsoft Visual Basic for Applications (VBA) サブルーチンは、範囲 r で識別されるストーリー内のすべての数値を出力します。

Sub PrintNumbers (r As ITextRange)
   r.SetRange 0, 0    // r = ストーリーの先頭にある挿入ポイント
   While r.MoveUntil(C1_DIGIT)  // r を次の数値の最初の数字へ移動
      r.MoveEndWhile C1_DIGIT  // 数値(数字の連なり)を選択
      Print r    // 出力
   Wend
End Sub

範囲の開始位置を、Cset で指定された文字セット内で最初に見つかった文字の位置まで移動します。ただし、その文字が開始位置から Count 文字以内に見つかった場合に限ります。

型: HRESULT

このメソッドは HRESULT 値を返します。成功した場合は S_OK を返します。失敗した場合は、次のいずれかのエラーコードを返します。COM のエラーコードについて詳しくは、COM のエラー処理を参照してください。

戻り値	説明
E_INVALIDARG	Cset が無効です。
S_FALSE	その他の理由による失敗です。

Cset の文字が開始位置から Count 個の位置以内に見つからない場合、範囲は変更されません。

新しい開始位置が古い終了位置より後になる場合、新しい終了位置は新しい開始位置に等しく設定されます。

ITextRange::MoveStartUntil が示す移動は、幾何学的ではなく論理的です。つまり、移動はストーリーの末尾方向または先頭方向へ向かいます。言語によっては、ストーリーの末尾方向への移動が左方向か右方向のいずれかになることがあります。

詳しくは、ITextRange と ITextRange::Move を参照してください。

範囲の終了を、Cset で指定された文字セット内で最初に見つかった文字の文字位置まで移動します。ただし、その文字が範囲の終了から Count 文字以内に見つかった場合に限ります。

型: HRESULT

このメソッドは HRESULT 値を返します。成功した場合は S_OK を返します。失敗した場合は、次のいずれかのエラーコードを返します。COM のエラーコードについて詳しくは、COM のエラー処理を参照してください。

戻り値	説明
値	意味
E_INVALIDARG	Cset が無効です。
S_FALSE	その他の理由による失敗です。

Cset で指定されたセットの文字が範囲の終了から Count 個の位置以内に見つからない場合、範囲は変更されません。新しい終了位置が古い開始位置より前になる場合、新しい開始位置は新しい終了位置に等しく設定されます。

ITextRange::MoveEndUntil が示す移動は、幾何学的ではなく論理的です。つまり、移動はストーリーの末尾方向または先頭方向へ向かいます。言語によっては、ストーリーの末尾方向への移動が左方向か右方向のいずれかになることがあります。

詳しくは、ITextRange と ITextRange::Move を参照してください。

bstr で指定されたテキストを、最大 Count 文字まで検索します。開始位置と方向も Count で指定し、照合条件は Flags で指定します。

型: HRESULT

このメソッドは HRESULT 値を返します。成功した場合は S_OK を返します。失敗した場合は S_FALSE を返します。COM のエラーコードについて詳しくは、COM のエラー処理を参照してください。

ITextRange::FindText メソッドは、キャレット (^) の後に特殊な文字を続けることで、特殊文字を照合することもできます。特殊文字の一覧については、Microsoft Word の [検索と置換] ダイアログボックスにある特殊文字の一覧を参照してください。たとえば、^p は次の段落マークに一致します。なお、^c は置換対象の文字列内でクリップボードの内容を表すために使えます。したがって、検索文字列で ^c を使うと、リッチテキストを検索できます。詳しくは、Word のヘルプファイルを参照してください。

ITextRange::FindText メソッドとの比較として、ITextRange::FindTextStart メソッドは範囲の Start cp から前方または後方へ検索し、ITextRange::FindTextEnd メソッドは範囲の End cp から前方または後方へ検索します。詳しくは、これらのメソッドの説明を参照してください。

次に、ITextRange::FindText メソッドを示すいくつかのコードスニペットを示します。

例 #1。次の Microsoft Visual Basic for Applications (VBA) プログラムは、範囲 r で識別されるストーリー内のすべての /* ... */ コメントを出力します。

Sub PrintComments (r As ITextRange)
    r.SetRange 0, 0                                      'r = ストーリーの先頭の挿入ポイント
    Do While r.FindText("/*") And r.FindTextEnd("*/")    'コメントを選択
        r.MoveStart tomCharacter, 2                      'ただし開始・終了のコメント記号は
                                                         '含めない
        r.MoveEnd tomCharacter, -2                       
        Print r                                          '表示する
    Loop
End Sub

これらのコメントを出力する代わりに、別の編集インスタンスに挿入してファイルに保存したり、表やスプレッドシートの別々のセルに挿入したりすることもできます。

"laser" という単語が 1 回以上出現するすべての行を出力するには、ループを次のコードに置き換えます。

    While r.FindText("laser")            // "laser" の次の出現箇所を選択
        r.Expand tomLine                // 囲んでいる行を選択
        Print r                    // 行を出力
    Wend

例 #2。次のプログラムは、住所一覧を含むストーリーを基に電話番号一覧を出力します。住所一覧のエントリは 2 つ以上の段落マークで区切られ、各エントリは次の形式を持ちます。

Person/Business Name
Address (one or more lines)
(area code) telephone number 

連続する 2 つの段落マークを見つけるために、FindText の文字列引数で文字 ^p を使っている点に注意してください。

Sub PrintTelephoneList (r As ITextRange)
    r.SetRange 0, 0                 // r = ストーリーの先頭にある挿入ポイント
    r.MoveWhile C1_WHITE            // 先頭の空白をスキップ
    Do
        r.EndOf tomParagraph, 1     // 次の段落(行)を選択: 名前が入っている
        Print r                    // 出力
        Do
            r.MoveWhile C1_SPACE        // 空白文字をスキップ
            If r.Char = Asc("(") Then Exit Do    // 電話番号の先頭を探す
        Loop While r.Move(tomParagraph)    // 次の段落へ移動
        r.EndOf tomParagraph, 1        // 電話番号のある行を選択
        Print r                    // 出力
    Loop While r.FindText("^p^p")        // 連続する 2 つの段落マークを探す
End Sub

例 #3。次のサブルーチンは、範囲内の文字列 str1 のすべての出現箇所を str2 で置き換えます。

Sub Replace ( tr As ITextRange, str1 As String, str2 As String )
    Dim r As ITextRange
    r = tr.Duplicate                // tr のパラメーターを r にコピー
    r.End = r.Start                    // Start の挿入ポイントに変換
    While r.FindText(str1, tr.End - r.End)        // str の次の出現箇所を照合
        r = str2                // rep で置換
    Wend                        // 一致がなくなるまで繰り返す
End Sub

例 #4。次のコード行は、HRESULT の出現箇所の後に続く右かっこ "(" の最初の出現箇所の前に空白を挿入します。

    If r.FindText("HRESULT") And r.FindText("(") Then r = " ("

そのようなすべての出現箇所に対してこれを行うには、上記のコード行の If を While/Wend ループに変更します。これは、[検索と置換] ダイアログボックスでは実行できない FIND/REPLACE マクロの例です。

範囲の Start cp (cpFirst) から開始して、文字列 bstr を最大 Count 文字まで検索します。

型: HRESULT

このメソッドは HRESULT 値を返します。成功した場合は S_OK を返します。失敗した場合は S_FALSE を返します。

範囲の End cp から開始して、文字列 bstr を最大 Count 文字まで検索します。

型: HRESULT

このメソッドは HRESULT 値を返します。成功した場合は S_OK を返します。失敗した場合は S_FALSE を返します。

CTRL キーの押下の有無に応じて、DELETE キーと BACKSPACE キーを模倣します。

型: HRESULT

このメソッドは HRESULT 値を返します。成功した場合は S_OK を返します。それ以外の場合は、次のいずれかの値を返します。COM のエラーコードについて詳しくは、COM のエラー処理を参照してください。

戻り値	説明
E_ACCESSDENIED	テキストが書き込み保護されています。
S_FALSE	その他の理由による失敗です。

Count = 0 の場合、このメソッドは範囲内のテキストを削除します。つまり、範囲が挿入ポイントだけの場合は何も削除しません。

Count が 0 以外で、範囲が挿入ポイント(つまり退化している)の場合、|Count|(Count の絶対値)個の Unit が、Count の符号で示される論理方向に削除されます。正の値はストーリーの末尾方向、負の値はストーリーの先頭方向です。

Count が 0 以外で、範囲が退化していない(テキストを含む)場合、(Unit と Count の値に関係なく)範囲内のテキストが削除され、挿入ポイントが作成されます。その後、|Count| - 1 個の Unit が、Count の符号で示される論理方向に削除されます。

範囲内のテキストは、範囲に空文字列を代入する(r が範囲のとき r = を実行する)ことでも削除できます。ただし、ITextRange::Delete は BSTR を確保する必要がありません。

段落終わりのマーク (CR) を削除すると、Microsoft Word の UI の特別な動作になります。特に興味深いケースが 4 つあります。

• CR だけを削除し、その段落にテキストが含まれている場合、CR は削除され、次の段落は現在の段落と同じ段落書式になります。
• CR と、次の段落の一部(ただし全部ではない)の文字を削除した場合、現在の段落から残った文字は次の段落の段落書式になります。
• 段落の末尾まで選択したが段落全体は選択していない場合、CR は削除されません。
• 段落全体(先頭から CR まで)を削除した場合、CR も削除されます(ファイル内の最終 CR である場合を除く)。

pVar パラメーターに応じて、プレーンテキストまたはリッチテキストをデータオブジェクトまたはクリップボードに切り取ります。

型: HRESULT

このメソッドは HRESULT 値を返します。成功した場合は S_OK を返します。それ以外の場合は、次のいずれかの値を返します。COM のエラーコードについて詳しくは、COM のエラー処理を参照してください。

戻り値	説明
E_ACCESSDENIED	テキストが書き込み保護されています。
E_OUTOFMEMORY	メモリ不足です。

テキストをデータオブジェクトにコピーします。

型: HRESULT

このメソッドは HRESULT 値を返します。成功した場合は S_OK を返します。それ以外の場合は E_OUTOFMEMORY を返します。

ITextRange::Cut、ITextRange::Copy、ITextRange::Paste メソッドを使うと、IDataObject を使って範囲オブジェクトに対して通常の 切り取り、コピー、貼り付け 操作を実行でき、クリップボードの内容を変更しません。通常サポートされるクリップボード形式には、CF_TEXT と CF_RTF があります。さらに、プライベートなクリップボード形式を使って、テキストソリューション独自の内部リッチテキスト形式を参照することもできます。

プレーンテキストをコピーして置き換えるには、ITextRange::GetText と ITextRange::SetText メソッドを使えます。クリップボードを使わずに書式付きテキストを範囲 r1 から範囲 r2 へコピーするには、Copy と Paste、および ITextRange::GetFormattedText と ITextRange::SetFormattedText メソッドを使えます。次の Microsoft Visual Basic の例に示します。

r2.GetFormattedText = r1.GetFormattedText

指定したデータオブジェクトからテキストを貼り付けます。

型: HRESULT

成功した場合は S_OK を返します。失敗した場合は、次のいずれかのエラーコードを返します。COM のエラーコードについて詳しくは、COM のエラー処理を参照してください。

戻り値	説明
E_ACCESSDENIED	書き込み先が書き込み保護されています。
E_OUTOFMEMORY	書き込み先が貼り付けるテキストを保持できません。

詳しくは、ITextRange::Copy を参照してください。

指定した形式を使って、データオブジェクトを現在の範囲に貼り付けできるかどうかを判定します。

型: HRESULT

このメソッドは次の COM エラーコードを返します。COM のエラーコードについて詳しくは、COM のエラー処理を参照してください。

戻り値	説明
S_OK	クリップボードの内容または IDataObject を貼り付けできます。
S_FALSE	クリップボードの内容または IDataObject を貼り付けできません。

指定した範囲を編集できるかどうかを判定します。

型: HRESULT

範囲を編集できる場合、このメソッドは成功し、S_OK を返します。範囲を編集できない場合、このメソッドは失敗し、S_FALSE を返します。COM のエラーコードについて詳しくは、COM のエラー処理を参照してください。

範囲の一部でも保護されている場合、またはドキュメントが読み取り専用の場合、範囲は編集できません。

Type パラメーターに従って、この範囲内の文字の大文字・小文字を変更します。

型: HRESULT

このメソッドは HRESULT 値を返します。成功した場合は S_OK を返します。それ以外の場合は S_FALSE を返します。

テキスト範囲内の開始または終了の文字位置について、行内位置とともにスクリーン座標を取得します。

型: HRESULT

このメソッドは HRESULT 値を返します。成功した場合は S_OK を返します。失敗した場合は、次のいずれかのエラーコードを返します。COM のエラーコードについて詳しくは、COM のエラー処理を参照してください。

戻り値	説明
E_INVALIDARG	px または py のいずれかが null です。
S_FALSE	その他の理由による失敗です。

ITextRange::GetPoint メソッドは、ITextRange に UI ポインターコマンドをエミュレートする機能を与えます。アクセシビリティの目的にも便利です。

Type に従って位置合わせされた点 (x, y) で、または(Extend に応じて)その点まで、指定した点に基づいて範囲を変更します。

型: HRESULT

このメソッドは S_OK を返します。

アプリケーションは、指定した点を WindowFromPoint 関数で使って、ウィンドウのハンドルを取得できます。通常、このハンドルを使ってクライアント矩形の座標を求められます(ただし、Windowless Controls は注目すべき例外です)。

指定した範囲をスクロールして表示します。

型: HRESULT

このメソッドは HRESULT 値を返します。成功した場合は S_OK を返します。失敗した場合は S_FALSE を返します。

指定した範囲の先頭、つまり cpFirst にある埋め込みオブジェクトへのポインターを取得します。範囲は挿入ポイントであるか、または埋め込みオブジェクトのみを選択している必要があります。

型: HRESULT

成功した場合は S_OK を返します。失敗した場合は、次のいずれかのエラーコードを返します。COM のエラーコードについて詳しくは、COM のエラー処理を参照してください。

戻り値	説明
E_INVALIDARG	ppObject が null です。
S_FALSE	その他の理由による失敗です。

この範囲の先頭に埋め込みオブジェクトがない場合、または範囲が単一のオブジェクトより多くを選択している場合、ppObject は NULL に設定されます。

#define global IID_ITextRange "{8CC497C2-A1DF-11CE-8098-00AA0047BE5D}"
#usecom global ITextRange IID_ITextRange "{}"
#comfunc global ITextRange_GetText            7 var
#comfunc global ITextRange_SetText            8 wstr
#comfunc global ITextRange_GetChar            9 var
#comfunc global ITextRange_SetChar            10 int
#comfunc global ITextRange_GetDuplicate       11 sptr
#comfunc global ITextRange_GetFormattedText   12 sptr
#comfunc global ITextRange_SetFormattedText   13 sptr
#comfunc global ITextRange_GetStart           14 var
#comfunc global ITextRange_SetStart           15 int
#comfunc global ITextRange_GetEnd             16 var
#comfunc global ITextRange_SetEnd             17 int
#comfunc global ITextRange_GetFont            18 sptr
#comfunc global ITextRange_SetFont            19 sptr
#comfunc global ITextRange_GetPara            20 sptr
#comfunc global ITextRange_SetPara            21 sptr
#comfunc global ITextRange_GetStoryLength     22 var
#comfunc global ITextRange_GetStoryType       23 var
#comfunc global ITextRange_Collapse           24 int
#comfunc global ITextRange_Expand             25 int,var
#comfunc global ITextRange_GetIndex           26 int,var
#comfunc global ITextRange_SetIndex           27 int,int,int
#comfunc global ITextRange_SetRange           28 int,int
#comfunc global ITextRange_InRange            29 sptr,var
#comfunc global ITextRange_InStory            30 sptr,var
#comfunc global ITextRange_IsEqual            31 sptr,var
#comfunc global ITextRange_Select             32
#comfunc global ITextRange_StartOf            33 int,int,var
#comfunc global ITextRange_EndOf              34 int,int,var
#comfunc global ITextRange_Move               35 int,int,var
#comfunc global ITextRange_MoveStart          36 int,int,var
#comfunc global ITextRange_MoveEnd            37 int,int,var
#comfunc global ITextRange_MoveWhile          38 var,int,var
#comfunc global ITextRange_MoveStartWhile     39 var,int,var
#comfunc global ITextRange_MoveEndWhile       40 var,int,var
#comfunc global ITextRange_MoveUntil          41 var,int,var
#comfunc global ITextRange_MoveStartUntil     42 var,int,var
#comfunc global ITextRange_MoveEndUntil       43 var,int,var
#comfunc global ITextRange_FindText           44 wstr,int,int,var
#comfunc global ITextRange_FindTextStart      45 wstr,int,int,var
#comfunc global ITextRange_FindTextEnd        46 wstr,int,int,var
#comfunc global ITextRange_Delete             47 int,int,var
#comfunc global ITextRange_Cut                48 var
#comfunc global ITextRange_Copy               49 var
#comfunc global ITextRange_Paste              50 var,int
#comfunc global ITextRange_CanPaste           51 var,int,var
#comfunc global ITextRange_CanEdit            52 var
#comfunc global ITextRange_ChangeCase         53 int
#comfunc global ITextRange_GetPoint           54 int,var,var
#comfunc global ITextRange_SetPoint           55 int,int,int,int
#comfunc global ITextRange_ScrollIntoView     56 int
#comfunc global ITextRange_GetEmbeddedObject  57 sptr
; ※数字は vtbl インデックス(0始まり)。0/1/2 は IUnknown(QueryInterface/AddRef/Release)。
; ※このインターフェースは直接 CoCreateInstance するクラスIDが無いため "{}"(他メソッド/アクティベーションで取得)。
; ※出力/バッファ引数は var(変数直渡し)。varptr 方式にも切替可。
; ※ハンドル/void*等の不透明ポインタは IronHSP では intptr 指定が可能。
; ※IDispatch 実装。HSP では comobj 経由でメソッド名による呼び出しも可能(vtbl 不要)。