ITfContext::TrackProperties method (msctf.h)

Obtains a special property that can enumerate multiple properties over multiple ranges.

Syntax

HRESULT TrackProperties(
  [in]  const GUID          **prgProp,
  [in]  ULONG               cProp,
  [in]  const GUID          **prgAppProp,
  [in]  ULONG               cAppProp,
  [out] ITfReadOnlyProperty **ppProperty
);

Parameters

[in] prgProp

Contains an array of property identifiers that specify the properties to track.

[in] cProp

Contains the number of property identifiers in the prgProp array.

[in] prgAppProp

Contains an array of application property identifiers that specify the application properties to track.

[in] cAppProp

Contains the number of application property identifiers in the prgAppProp array.

[out] ppProperty

Pointer to an ITfReadOnlyProperty interface pointer that receives the tracking property.

Return value

This method can return one of these values.

Remarks

This method is used to quickly identify ranges with consistent property values for multiple properties. While this method could be duplicated using only the ITfContext::GetProperty method, the TSF manager can accomplish this task more quickly.

The property obtained by this method is a VT_UNKNOWN type. This property can be used to obtain an IEnumTfPropertyValue enumerator by calling the QueryInterface method with IID_IEnumTfPropertyValue. This enumerator contains property values specified by prgProp and prgAppProp.

Examples

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();

Requirements

See also

IEnumTfPropertyValue

ITfContext

ITfContext::GetProperty

ITfReadOnlyProperty