ITfContext::GetSelection method (msctf.h)

Article
02/22/2024

Obtains the selection within the document.

Syntax

HRESULT GetSelection(
  [in]  TfEditCookie ec,
  [in]  ULONG        ulIndex,
  [in]  ULONG        ulCount,
  [out] TF_SELECTION *pSelection,
  [out] ULONG        *pcFetched
);

Parameters

[in] ec

Contains an edit cookie that identifies the edit session. This is the value passed to ITfEditSession::DoEditSession.

[in] ulIndex

Specifies the zero-based index of the first selection to obtain. Use TF_DEFAULT_SELECTION to obtain the default selection. If TF_DEFAULT_SELECTION is used, only one selection is obtained.

[in] ulCount

Specifies the maximum number of selections to obtain.

[out] pSelection

An array of TF_SELECTION structures that receives the data for each selection. The array must be able to hold at least ulCount elements.

[out] pcFetched

Pointer to a ULONG value that receives the number of selections obtained.

Return value

This method can return one of these values.

Value	Description
S_OK	The method was successful.
TF_E_NOSELECTION	The document has no selection.
TF_E_NOLOCK	The cookie in ec is invalid.
TF_E_DISCONNECTED	The context is not on a document stack.
E_INVALIDARG	One or more parameters are invalid.
E_OUTOFMEMORY	A memory allocation failure occurred.

Remarks

A selection is a highlighted range of text, or an insertion point if the range is empty, that identifies the user focus area within a document.

If this method is successful, the caller must release the range member of all TF_SELECTION structures obtained.

Normally, a context only supports a single selection. It is possible, however, for a context to support multiple, simultaneous selections. This method can be used to obtain multiple selections.

Examples


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

Requirements

Requirement	Value
Minimum supported client	Windows 2000 Professional [desktop apps \| UWP apps]
Minimum supported server	Windows 2000 Server [desktop apps \| UWP apps]
Target Platform	Windows
Header	msctf.h
DLL	Msctf.dll
Redistributable	TSF 1.0 on Windows 2000 Professional