Embedded Objects

Text Services Framework enables a text service to embed objects in an application text stream. Embedded objects are inserted into the text stream using the value TS_CHAR_EMBEDDED. This value resolves to the Unicode object replacement character U+fffc, using hexadecimal notation. For example, the following illustration shows the rendering of an embedded object that represents the Japanese ideograph hi, in combination with the sequence of Unicode characters that represent the English translation of "Sun."

Character encoding of an embedded object

The top row of the figure contains the translated text, consisting of the word "Sun" followed by the Japanese character for sun, hi. The center row of the figure shows the Unicode character. In the case of U+fffc, this is the object replacement character. The bottom row of the figure shows the hexadecimal value of each character.

Supporting Embedded Objects in an Application

The TSF manager inserts an embedded object into the text stream by calling ITextStoreACP::InsertEmbedded for an ACP-based application, or ITextStoreAnchor::InsertEmbedded for an anchor-based application. When an embedded object is inserted, the application should place the TS_CHAR_EMBEDDED value at the character position (or anchor location) where the object is embedded and store the IDataObject associated with the embedded object. When ITextStoreACP::GetText or ITextStoreAnchor::GetText is called and an embedded object is contained within the text obtained, the TS_CHAR_EMBEDDED value indicates the presence and location of the embedded object. To obtain the embedded object, call ITextStoreACP::GetEmbedded with the character position of the embedded object, or ITextStoreAnchor::GetEmbedded with the anchor location of the embedded object.

The application does not normally recognize the embedded object contents. The application can attempt to obtain display information from the object itself. If the embedded object can supply data in a format that the application recognizes, such as CF_UNICODETEXT or CF_BITMAP, the application can display graphic information supplied by the object.

Inserting Embedded Objects

A text service inserts an embedded object into a context by calling ITfRange::InsertEmbedded or ITfInsertAtSelection::InsertEmbeddedAtSelection. The text service must supply the embedded IDataObject.