ITextStoreACP::SetText method (textstor.h)

  • Article

The ITextStoreACP::SetText method 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 ITextStoreACP::InsertTextAtSelection. ITextStoreACP::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 ITextStoreACPSink::OnTextChange method in response to this method.

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

Requirements

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

See also

Compositions

ITextStoreACP

ITextStoreACPSink::OnTextChange

Miscellaneous Text Store Constants

TS_TEXTCHANGE