ITextStoreACP2::SetText method (textstor.h)

Article
10/13/2021

Sets the text selection to the supplied character positions.

Syntax

HRESULT SetText(
  [in]  DWORD         dwFlags,
  [in]  LONG          acpStart,
  [in]  LONG          acpEnd,
  [in]  const WCHAR   *pchText,
  [in]  ULONG         cch,
  [out] TS_TEXTCHANGE *pChange
);

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] acpStart

Specifies the starting character position of the text to replace.

[in] acpEnd

Specifies the ending character position of the text to replace. This parameter is ignored if the value is 1.

[in] pchText

Specifies the 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.

[out] pChange

Pointer to a TS_TEXTCHANGE structure with the following data.

Value	Meaning
acpStart	The starting application character position before the text is inserted into the document.
acpOldEnd	The ending position before the text is inserted into the document. This value is the same as acpStart for an insertion point. If this value is different from acpStart, then text was selected prior to the text insertion.
acpNewEnd	The ending position after the text insertion occurred.

Return value

This method can return one of these values.

Value	Description
S_OK	The method was successful.
TS_E_INVALIDPOS	The acpStart or acpEnd parameter 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 InsertTextAtSelection. 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.

The acpStart and acpEnd character positions cannot be outside the document range.

Applications should not call the OnTextChange method in response to this method.

This method should call the SetSelection method to select the text to be changed. After successfully executing the SetSelection method, this method then calls the InsertTextAtSelection method to perform the actual text change.

Requirements

Requirement	Value
Minimum supported client	Windows 8 [desktop apps \| UWP apps]
Minimum supported server	Windows Server 2012 [desktop apps \| UWP apps]
Target Platform	Windows
Header	textstor.h
DLL	Msctf.dll