ITfRange::InsertEmbedded method (msctf.h)

The ITfRange::InsertEmbedded method inserts an object at the location of the start anchor of the range of text.

Syntax

HRESULT InsertEmbedded(
  [in] TfEditCookie ec,
  [in] DWORD        dwFlags,
  [in] IDataObject  *pDataObject
);

Parameters

[in] ec

Edit cookie obtained from ITfDocumentMgr::CreateContext or ITfEditSession::DoEditSession.

[in] dwFlags

Bit fields that specify how insertion should occur. If TF_IE_CORRECTION is set, the operation is a correction, so that other text services can preserve data associated with the original text.

[in] pDataObject

Pointer to the data transfer object to be inserted.

Return value

This method can return one of these values.

Remarks

Use this method to insert objects into the text stream, because the TF_CHAR_EMBEDDED object placeholder character cannot be passed into ITfRange::SetText. This method is modeled after the OLE clipboard API, with applications using pDataObject as they would an IDataObject returned from OleGetClipboard.

When a range covers multiple regions, the method should be called on each region separately. Otherwise, the method might 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.

To determine in advance whether a context owner supports insertion of a particular object, use ITfQueryEmbedded::QueryInsertEmbedded.

Requirements

See also

IDataObject

ITfDocumentMgr::CreateContext

ITfEditSession::DoEditSession

ITfRange

ITfRange::GetEmbedded

Miscellaneous Framework Constants

Text Stores