ITfRange

ITfRange インターフェイスは、テキストサービスやアプリケーションが、指定されたコンテキスト内のテキストを参照し操作するために使用します。インターフェイス ID は IID_ITfRange です。

このインターフェイスは TSF マネージャーが実装します。範囲 (レンジ)、アンカー、埋め込みオブジェクト、その他 TSF が使用するテキストプロパティの詳細については、Ranges、Embedded Objects、および Using Text Services Framework 内の各トピックを参照してください。

例

ITfComposition コンポジションオブジェクトのインスタンスを生成すると、次のコード例のように ITfComposition::GetRange メソッドを呼び出して ITfRange インターフェイスポインターへのポインターを取得できます。

HRESULT         hr;
ITfComposition  *pComposition;
ITfRange        *pRange;
WCHAR           *achBuffer[64];  // テキストを受け取るバッファー。 
ULONG           cch;

hr = pComposition->GetRange(&pRange);
if(SUCCEEDED(hr))
{
    // テキストを走査するループ: 

    do
    {
        cch = ARRAYSIZE(achBuffer);
        hr = pRange->GetText(ec, TF_TF_MOVESTART | TF_TF_IGNOREEND, achBuffer, cch, &cch);
        if(SUCCEEDED(hr))
        {
            // テキストに対して何らかの処理を行う。 

            pRange->Release();
        }
    }
    while (cch == ARRAYSIZE(achBuffer));

    pComposition->Release();
}

現在の ITfRange オブジェクトへのポインターは、TF_SELECTION 構造体の <range> 要素から取得できます。

ITfRange::GetText メソッドは、このテキスト範囲 (レンジ) が対象とする内容を取得します。

このメソッドは次のいずれかの値を返します。

ITfRange::SetText メソッドは、テキスト範囲 (レンジ) が対象とする内容を置き換えます。

このメソッドは次のいずれかの値を返します。

範囲が複数のリージョンにまたがる場合は、リージョンごとに個別に ITfRange::SetText を呼び出してください。そうしないとメソッドが失敗することがあります。

既定では、テキストサービスは範囲を対象とする一時的なコンポジションを開始および終了し、編集されたテキストに対するコンポジションをコンテキストの所有者が一貫して認識できるようにします。コンポジションの所有者が既定のコンポジションを拒否した場合、メソッドは TF_E_COMPOSITION_REJECTED を返します。既定のコンポジションは、呼び出し元がまだコンポジションを開始していない場合にのみ作成されます。呼び出し元がアクティブなコンポジションを保持している場合、呼び出しは失敗します。

TF_CHAR_EMBEDDED オブジェクトのプレースホルダー文字は、このメソッドに渡せない場合があります。代わりに ITfRange::InsertEmbedded を使用してください。

テキストを挿入する場合、ITFInsertAtSelection:InsertTextAtSelection メソッドは選択範囲の割り当てを必要とせず、範囲が選択と一致していなければならないという制約も回避できます。

ITfRange::GetFormattedText メソッドは、テキスト範囲 (レンジ) に含まれる書式付きの内容を取得します。内容は IDataObject インターフェイスをサポートするオブジェクトにパッケージ化されます。

このメソッドは次のいずれかの値を返します。

IDataObject の形式と格納方法は、その範囲が属するアプリケーションによって決定されます。

ITfRange::GetEmbedded メソッドは、テキストストリーム内の TS_CHAR_EMBEDDED 文字に対応する内容を取得します。テキスト範囲 (レンジ) の開始アンカーは、対象となる文字の直前に配置されます。

このメソッドは次のいずれかの値を返します。

取得したオブジェクトが特定のインターフェイスをサポートしていない場合もありますが、IOleObject、IDataObject、IViewObject、IPersistStorage、IOleCache、IDispatch など、埋め込みドキュメントやコントロールに関連するインターフェイスはサポートしている可能性が高いです。呼び出し元は QueryInterface を使用して必要なインターフェイスを調べる必要があります。メソッドが成功しても riid が NULL の場合、アプリケーションは埋め込みオブジェクトの存在を示していますが、オブジェクト自体は公開していません。それでもテキストプロセッサーは、単語区切りの可能性についての通知から利益を得られます。

ITfRange::InsertEmbedded メソッドは、テキスト範囲 (レンジ) の開始アンカーの位置にオブジェクトを挿入します。

このメソッドは次のいずれかの値を返します。

TF_CHAR_EMBEDDED オブジェクトのプレースホルダー文字は ITfRange::SetText に渡せないため、テキストストリームにオブジェクトを挿入するにはこのメソッドを使用します。このメソッドは OLE のクリップボード API をモデルにしており、アプリケーションは OleGetClipboard から返される IDataObject と同じように pDataObject を使用します。

範囲が複数のリージョンにまたがる場合は、リージョンごとに個別にこのメソッドを呼び出してください。そうしないとメソッドが失敗することがあります。

既定では、テキストサービスは範囲を対象とする一時的なコンポジションを開始および終了し、編集されたテキストに対するコンポジションをコンテキストの所有者が一貫して認識できるようにします。コンポジションの所有者が既定のコンポジションを拒否した場合、メソッドは TF_E_COMPOSITION_REJECTED を返します。既定のコンポジションは、呼び出し元がまだコンポジションを開始していない場合にのみ作成されます。呼び出し元がアクティブなコンポジションを保持している場合、呼び出しは失敗します。

コンテキストの所有者が特定のオブジェクトの挿入をサポートしているかどうかを事前に確認するには、ITfQueryEmbedded::QueryInsertEmbedded を使用してください。

ITfRange::ShiftStart メソッド

このメソッドは次のいずれかの値を返します。

範囲 (レンジ) の開始位置と終了位置はアンカーと呼ばれます。

このメソッドでは、アンカーをリージョンの境界を越えて移動することはできません。移動がリージョンの境界に達した場合、実際に移動した文字数は要求された数より少なくなります。隣接するリージョンへアンカーを移動するには ITfRange::ShiftStartRegion を使用します。

移動操作によって範囲の開始アンカーが終了アンカーを越えた場合、終了アンカーは開始アンカーと同じ位置に移動されます。

ITfRange::ShiftStart は時間のかかる操作になることがあります。パフォーマンスを向上させるため、可能な場合は ITfRange::ShiftStartToRange を使用してください。

ITfRange::ShiftEnd メソッド

このメソッドは次のいずれかの値を返します。

範囲 (レンジ) の開始位置と終了位置はアンカーと呼ばれます。

このメソッドでは、アンカーをリージョンの境界を越えて移動することはできません。移動がリージョンの境界に達した場合、実際に移動した文字数は要求された数より少なくなります。隣接するリージョンへアンカーを移動するには ITfRange::ShiftEndRegion を使用します。

移動操作によって範囲の終了アンカーが開始アンカーを越えた場合、開始アンカーは終了アンカーと同じ位置に移動されます。

ITfRange::ShiftEnd は時間のかかる操作になることがあります。パフォーマンスを向上させるため、可能な場合は ITfRange::ShiftEndToRange を使用してください。

ITfRange::ShiftStartToRange メソッド

このメソッドは次のいずれかの値を返します。

範囲 (レンジ) の開始位置と終了位置はアンカーと呼ばれます。

移動操作によって範囲の開始アンカーが終了アンカーを越えた場合、終了アンカーは開始アンカーと同じ位置に移動されます。

このメソッドは ITfRange::ShiftStart よりも効率的であり、可能な場合はこちらを使用してください。

ITfRange::ShiftEndToRange メソッド

このメソッドは次のいずれかの値を返します。

範囲 (レンジ) の開始位置と終了位置はアンカーと呼ばれます。

移動操作によって範囲の終了アンカーが開始アンカーを越えた場合、開始アンカーは終了アンカーと同じ位置に移動されます。

このメソッドは ITfRange::ShiftEnd よりも効率的であり、こちらを使用してください。

ITfRange::ShiftStartRegion メソッド

このメソッドは次のいずれかの値を返します。

範囲 (レンジ) の開始位置と終了位置はアンカーと呼ばれます。

このメソッドを呼び出す前に、アンカーが目的のリージョンに隣接して配置されている必要があります。隣接していない場合、pfNoRegion は 0 以外の値を受け取り、アンカーは移動しません。アンカーが目的のリージョンに隣接している場合、pfNoRegion は 0 を受け取り、アンカーはそのリージョンへ移動されます。

ITfRange::ShiftEndRegion メソッド

このメソッドは次のいずれかの値を返します。

範囲 (レンジ) の開始位置と終了位置はアンカーと呼ばれます。

このメソッドを呼び出す前に、アンカーが目的のリージョンに隣接して配置されている必要があります。隣接していない場合、pfNoRegion は 0 以外の値を受け取り、アンカーは移動しません。アンカーが目的のリージョンに隣接している場合、pfNoRegion は 0 を受け取り、アンカーはそのリージョン内へ移動されます。

ITfRange::IsEmpty メソッドは、開始アンカーと終了アンカーが同じ位置にあることによってテキスト範囲 (レンジ) が空であるかどうかを確認します。

このメソッドは次のいずれかの値を返します。

ITfRange::Collapse メソッドは、開始アンカーと終了アンカーを同じ位置に移動することで、テキスト範囲 (レンジ) を空にします。

このメソッドは次のいずれかの値を返します。

ITfRange::IsEqualStart メソッドは、このテキスト範囲 (レンジ) の開始アンカーが、指定された別の範囲のアンカーと一致するかどうかを確認します。

このメソッドは次のいずれかの値を返します。

このメソッドは ITfRange::CompareStart と同一の機能を持ちますが、より効率的です。

ITfRange::IsEqualStart メソッドは、このテキスト範囲 (レンジ) の終了アンカーが、指定された別の範囲のアンカーと一致するかどうかを確認します。

このメソッドは次のいずれかの値を返します。

このメソッドは、この範囲の終了アンカーを指定された別の範囲のアンカーと比較する点を除き、ITfRange::IsEqualStart と同一です。

このメソッドは ITfRange::CompareEnd と機能的に同等ですが、より効率的です。

ITfRange::CompareStart メソッドは、このテキスト範囲 (レンジ) の開始アンカーの位置を、別の範囲のアンカーと比較します。

このメソッドは次のいずれかの値を返します。

このメソッドは、2 つのアンカーが同一のリージョン内にある場合を除き、0 を返すことはありません。2 つのアンカーが同じ位置にあるかどうかだけを知りたい場合は、ITfRange::IsEqualStart の方が効率的です。

ITfRange::CompareEnd メソッドは、このテキスト範囲 (レンジ) の終了アンカーの位置を、別の範囲のアンカーと比較します。

このメソッドは次のいずれかの値を返します。

このメソッドは、2 つのアンカーが同一のリージョン内にある場合を除き、0 を返すことはありません。2 つのアンカーが同じ位置にあるかどうかだけを知りたい場合は、ITfRange::IsEqualEnd の方が効率的です。

このメソッドは、この範囲の終了アンカーを指定された別の範囲のアンカーと比較する点を除き、ITfRange::CompareStart と同一です。

ITfRange::AdjustForInsert メソッドは、テキストの挿入に合わせてテキスト範囲 (レンジ) を拡張または縮小します。

このメソッドは次のいずれかの値を返します。

編集を開始する前に、新しいコンポジションを開始するための範囲を準備する目的でこのメソッドを使用してください。使用するのは、テキストが現在の選択位置に挿入されない場合に限ります。テキストを現在の選択位置に挿入する場合は、ITFInsertAtSelection:InsertTextAtSelection または ITfInsertAtSelection::InsertEmbeddedAtSelection を使用するのが適切です。

コンテキストの所有者は、動作を保持し一貫したユーザー体験を維持するためにこのメソッドを利用できます。たとえば、コンテキスト内の特定の文字やオブジェクトを変更から保護したり、上書き入力をサポートしたりできます。

既存のコンポジションを変更する場合、このメソッドは不要です。呼び出し元が以前に入力したテキストを変更するには、ITfRange::SetText を直接呼び出しても問題ありません。

戻り時に *pfInsertOk が FALSE に設定されている場合、この範囲を用いた以降の ITfRange::SetText または ITfRange::InsertEmbedded の呼び出しは失敗する可能性が高くなります。それ以外の場合、*pfInsertOk は TRUE に設定され、範囲の開始アンカーまたは終了アンカーはコンテキストの所有者の判断で再配置されることがあります。

ITfRange::GetGravity メソッド

このメソッドは次のいずれかの値を返します。

ITfRange::SetGravity メソッド

このメソッドは次のいずれかの値を返します。

ITfRange::Clone メソッドは、このテキスト範囲 (レンジ) を複製します。

このメソッドは次のいずれかの値を返します。

生成された新しい範囲オブジェクトは、元の範囲に影響を与えずに変更できます。ただし、新しい範囲を含むドキュメントを変更すると、元の範囲のアンカーが再配置される場合があります。

元の範囲のグラビティは、新しい範囲にも引き継がれます。

ITfRange::GetContext メソッド

このメソッドは次のいずれかの値を返します。