ITfRange::InsertEmbedded method

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

ec [in]

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

dwFlags [in]

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.

pDataObject [in]

Pointer to the data transfer object to be inserted.

Return value

This method can return one of these values.

ValueDescription
S_OK

The method was successful.

E_NOTIMPL

The implementing application does not expose embedded objects in its stream.

TF_E_COMPOSITION_REJECTED

The context owner rejected a default composition.

TF_E_FORMAT

The context owner cannot handle the specified object type.

TF_E_NOLOCK

The value of the ec parameter is an invalid cookie, or the caller does not have a read-only lock.

TF_E_RANGE_NOT_COVERED

The caller already has an active composition, but the range is positioned over text not covered by the composition.

TF_E_READONLY

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

Minimum supported client

Windows 2000 Professional [desktop apps | Windows Store apps]

Minimum supported server

Windows 2000 Server [desktop apps | Windows Store apps]

Redistributable

TSF 1.0 on Windows 2000 Professional

Header

Msctf.h

IDL

Msctf.idl

DLL

Msctf.dll

See also

ITfRange
Miscellaneous Framework Constants
Text Stores
ITfDocumentMgr::CreateContext
ITfEditSession::DoEditSession
ITfRange::GetEmbedded
IDataObject

 

 

Show: