ITfRange::SetText method (msctf.h)

The ITfRange::SetText method replaces the content covered by the range of text. For an empty range object, the method results in an insertion at the ___location of the range. If the new content is an empty string (cch = 0), the method deletes the existing content within the range.

Syntax

HRESULT SetText(
  [in] TfEditCookie ec,
  [in] DWORD        dwFlags,
  [in] const WCHAR  *pchText,
  [in] LONG         cch
);

Parameters

[in] ec

Identifies the edit context obtained from ITfDocumentMgr::CreateContext or ITfEditSession::DoEditSession.

[in] dwFlags

Specifies optional behavior for correction of content. If set to the value of TF_ST_CORRECTION, then the operation is a correction of the existing content, not a creation of new content, and original text properties are preserved.

[in] pchText

Pointer to a buffer that contains the text to replace the range contents.

[in] cch

Contains the number of characters in pchText.

Return value

This method can return one of these values.

Remarks

When a range covers multiple regions, call ITfRange::SetText on each region separately. Otherwise, the method can fail.

By default, text services start and end a temporary composition that covers the range, to ensure that context owners consistently recognize compositions over edited text. If the composition owner rejects a default composition, then the method returns TF_E_COMPOSITION_REJECTED. Default compositions are only created if the caller has not already started one. If the caller has an active composition, the call fails.

The TF_CHAR_EMBEDDED object placeholder character might not be passed into this method. ITfRange::InsertEmbedded should be used instead.

For inserting text, the ITFInsertAtSelection:InsertTextAtSelection method does not require a selection range to be allocated, and avoids the requirement that the range match the selection.

Requirements

See also

ITFInsertAtSelection:InsertTextAtSelection

ITfDocumentMgr::CreateContext

ITfEditSession::DoEditSession

ITfRange

ITfRange::GetText

ITfRange::InsertEmbedded

Miscellaneous Framework Constants

Text Stores