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.
| Value | Description |
|---|---|
|
The method was successful. |
|
The implementing application does not expose embedded objects in its stream. |
|
The context owner rejected a default composition. |
|
The context owner cannot handle the specified object type. |
|
The value of the ec parameter is an invalid cookie, or the caller does not have a read-only lock. |
|
The caller already has an active composition, but the range is positioned over text not covered by the composition. |
|
The document or the location of the range cannot be modified. |
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
| 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 | msctf.h |
| DLL | Msctf.dll |
| Redistributable | TSF 1.0 on Windows 2000 Professional |