ITextStoreAnchor::SetText method (textstor.h)

Article
10/13/2021

The ITextStoreAnchor::SetText method sets the text selection between two supplied anchor locations.

Syntax

HRESULT SetText(
  [in] DWORD       dwFlags,
  [in] IAnchor     *paStart,
  [in] IAnchor     *paEnd,
  [in] const WCHAR *pchText,
  [in] ULONG       cch
);

Parameters

[in] dwFlags

If set to the value of TS_ST_CORRECTION, the text is a transform (correction) of existing content, and any special text markup information (metadata) is retained, such as .wav file data or a language identifier. The client defines the type of markup information to be retained.

[in] paStart

Pointer to the anchor at the start of the range of text to replace.

[in] paEnd

Pointer to the anchor at the end of the range of text to replace. Must always follow or be at the same position as paStart.

[in] pchText

Pointer to the replacement text. The text string does not have to be NULL terminated, because the text character count is specified in the cch parameter.

[in] cch

Specifies the number of characters in the replacement text.

Return value

This method can return one of these values.

Value	Description
S_OK	The method was successful.
E_FAIL	The method could not instantiate one of the anchors paStart or paEnd.
TS_E_INVALIDPOS	The location of paStart or paEnd is outside of the document text.
TS_E_NOLOCK	The caller does not have a read/write lock.
TS_E_READONLY	The document is read-only. Content cannot be modified.
TS_E_REGION	An attempt was made to modify text across a region boundary.

Remarks

Applications should start a composition by first using ITextStoreAnchor::InsertTextAtSelection. ITextStoreAnchor::SetText should be used only within an existing composition. If there is no active composition at the time SetText is called, the TSF manager creates a composition that lasts just long enough to wrap the call to SetText.

Callers must hold a write lock obtained through ITextStoreAnchor::RequestLock. Otherwise, ITextStoreAnchor::SetText will fail with TS_E_NOLOCK.

If paStart is at the same location as paEnd, then the operation is an insertion, and no existing text will be removed.

TS_CHAR_EMBEDDED cannot be passed into this method. For embedded objects, use ITextStoreAnchor::InsertEmbedded instead.

This method will fail if the range of text replaced covers any region boundary. Instead, callers should make multiple calls to the method, one for each region.

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	textstor.h
DLL	Msctf.dll
Redistributable	TSF 1.0 on Windows 2000 Professional