ITfContext

ITfContext インターフェイスは TSF マネージャーによって実装され、アプリケーションやテキストサービスが編集コンテキストにアクセスするために使用します。

編集コンテキストオブジェクトは ITfDocumentMgr::CreateContext を呼び出して作成します。テキストサービスは通常、現在アクティブな編集コンテキストを使用します。現在アクティブな編集コンテキストとは、アクティブなドキュメントマネージャーのスタック最上位にある編集コンテキストです。

例

HRESULT         hr;
ITfDocumentMgr  *pFocusDoc;

hr = pThreadMgr->GetFocus(&pFocusDoc);
if(SUCCEEDED(hr))
{
    ITfContext *pContext;

    hr = pFocusDoc->GetTop(&pContext);
    if(SUCCEEDED(hr))
    {
        //Use the context. 
        
        pContext->Release();
    }

    pFocusDoc->Release();
}

ITfContext::RequestEditSession メソッド

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

保留中の非同期編集セッションは、受け取った順に処理されます。同期の編集セッションは、保留中の非同期編集セッションよりも先に処理されます。

テキストサービスは、既存の編集セッションのコンテキスト内で編集セッションを要求できます。ただし、読み取り専用セッション内で書き込みアクセスのセッションを要求することはできません。別のテキストサービスが確立した編集セッションのコンテキスト内でこのメソッドを呼び出すと、TF_E_LOCKED で失敗します。

同期の読み書き要求は、次の通知の処理中に行われた場合は失敗します。

• ITfTextEditSink::OnEndEdit
• ITfTextLayoutSink::OnLayoutChange
• ITfStatusSink::OnStatusChange

ITfContext::InWriteSession メソッド

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

クライアントは通知コールバックの内部でこのメソッドを使用し、自身が変更を行う必要があるかどうかを判断します。

ITfContext::GetSelection メソッド

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

選択範囲とは、ドキュメント内でユーザーのフォーカス領域を示す、強調表示されたテキストの範囲 (レンジ) です。範囲が空の場合は挿入位置を表します。

このメソッドが成功した場合、呼び出し元は取得したすべての TF_SELECTION 構造体の range メンバーを解放する必要があります。

通常、コンテキストがサポートする選択範囲は 1 つだけです。ただし、コンテキストが複数の選択範囲を同時にサポートすることも可能です。このメソッドを使用して複数の選択範囲を取得できます。

例

HRESULT         hr;
TF_SELECTION    tfSel;
ULONG           uFetched;

//Obtain the default selection. 
hr = pContext->GetSelection(ec, TF_DEFAULT_SELECTION, 1, &tfSel, &uFetched);
if(SUCCEEDED(hr) && (uFetched > 0))
{
    //Work with the selection. 
    
    //Release the selection range object. 
    tfSel.range->Release();
}

ITfContext::SetSelection メソッド

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

選択範囲とは、ドキュメント内でユーザーのフォーカス領域を示す、強調表示されたテキストの範囲です。範囲が空の場合は挿入位置を表します。ドキュメントによっては複数の選択範囲を持てるものもあります。pSelection 内に長さ 0 の選択範囲は 1 つしか含められません。これはドキュメントのキャレット位置を表すためです。

アプリケーションが選択範囲に含まれるテキストを調整する必要がある場合は、呼び出し元がロックを解放するまで待つ必要があります。ただし、アプリケーションは S_OK を返しつつ TF_SELECTION 構造体の style メンバーを調整できます。

呼び出し元が fInterimChar フラグを設定できるのは、選択範囲を 1 つだけ設定する場合のみです。この場合、選択範囲はちょうど 1 文字にまたがっている必要があり、TF_SELECTION 構造体の ase メンバーは TFAE_NONE に設定されます。

ITfContext::GetStart メソッド

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

ITfContext::GetEnd メソッド

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

ITfContext::GetActiveView メソッド

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

ITfContext::GetStatus メソッド

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

ITfContext::GetProperty メソッド

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

アプリケーションやテキストサービスは、GUID で識別される独自のプロパティを定義できます。プロパティは VARIANT データとして格納されるため、独自プロパティを使用するには、呼び出し元がその形式と意味を理解している必要があります。

ITfContext::GetAppProperty メソッド

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

アプリケーションは GUID で識別される独自のプロパティを定義できます。プロパティは VARIANT データとして格納されるため、独自プロパティを使用するには、呼び出し元がその形式と意味を理解している必要があります。

アプリケーションプロパティは、ITfContext::GetProperty で取得するテキストプロパティとは異なり、コンテキストオーナーが管理し、テキストサービスからは変更できません。アプリケーションプロパティを変更できるのはコンテキストオーナーのみです。

ITfContext::TrackProperties メソッド

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

このメソッドは、複数のプロパティについて一貫したプロパティ値を持つ範囲を素早く特定するために使用します。同じ処理は ITfContext::GetProperty メソッドだけでも実現できますが、TSF マネージャーはこの処理をより高速に行えます。

このメソッドで取得されるプロパティは VT_UNKNOWN 型です。このプロパティに対して IID_IEnumTfPropertyValue を指定して QueryInterface メソッドを呼び出すと、IEnumTfPropertyValue 列挙子を取得できます。この列挙子には、prgProp および prgAppProp で指定したプロパティ値が含まれます。

例

const GUID *rgGuids[2] = {  &GUID_PROP_COMPOSING,
                            &GUID_PROP_ATTRIBUTE };
HRESULT hr;
ITfReadOnlyProperty *pTrackProperty;
TF_SELECTION sel;
IEnumTfRanges *pEnumRanges;
ITfRange *pRangeValue;

// Get the tracking property. 
hr = pContext->TrackProperties(NULL, 0, rgGuids, 2, &pTrackProperty);

// Get the selection range. 
hr = pContext->GetSelection(ec, TF_DEFAULT_SELECTION, 1, &sel, &cFetched);

// Use the property from TrackProperties to get an enumeration of the ranges  
// within the selection range that have the same property values. 
hr = pTrackProperty->EnumRanges(ec, &pEnumRanges, sel.range);

// Enumerate the ranges of text. 
while(pEnumRanges->Next(1, &pRangeValue, NULL) == S_OK)
{
    VARIANT varTrackerValue;
    TF_PROPERTYVAL tfPropertyVal;
    IEnumTfPropertyValue *pEnumPropVal;

    // Get the values for this range of text. 
    hr = pTrackProperty->GetValue(ec, pRangeValue, &varTrackerValue);

    // Because pTrackProperties originates from TrackProperties, 
    // varTrackerValue can be identified as a VT_UNKNOWN/IEnumTfPropertyValue. 
    varTrackerValue.punkVal->QueryInterface(    IID_IEnumTfPropertyValue,
                                                (void **)&pEnumPropVal);

    while(pEnumPropVal->Next(1, &tfPropertyVal, NULL) == S_OK)
    {
        BOOL fComposingValue;
        TfGuidAtom gaDispAttrValue;
        
        // Is this the composition property? 
        if (IsEqualGUID(tfPropertyVal.guidId, GUID_PROP_COMPOSING))
        {
            fComposingValue = (BOOL)tfPropertyVal.varValue.lVal;
        }
        // Or is this the attribute property? 
        else if (IsEqualGUID(tfPropertyVal.guidId, GUID_PROP_ATTRIBUTE))
        {
            gaDispAttrValue = (TfGuidAtom)tfPropertyVal.varValue.lVal;
        }
        
        // Clear the property. 
        VariantClear(&tfPropertyVal.varValue);
    }

    // Clear the tracker property. 
    VariantClear(&varTrackerValue);

    // Release the property enumerator. 
    pEnumPropVal->Release();

    // Release the range. 
    pRangeValue->Release();
}

// Release the selection range. 
sel.range->Release();

ITfContext::EnumProperties メソッド

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

ITfContext::GetDocumentMgr メソッド

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

コンテキストがドキュメントマネージャーに含まれていない場合、このメソッドは S_FALSE を返し、ppDm には NULL が設定されます。これは、ITfDocumentMgr::Pop の呼び出しによってコンテキストがコンテキストスタックから取り除かれた場合に発生します。

ITfContext::CreateRangeBackup メソッド

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

このメソッドは範囲のコピーを作成し、ITfRangeBackup::Restore でデータを復元する際に使用できるようにします。