Objects

Microsoft OLE links, Microsoft OLE embedded objects, and Macintosh Edition Manager subscriber objects are represented in RTF as objects. Objects are destinations that contain a data part and a result part. The data part is generally hidden to the application that produced the document. A separate application uses the data and supplies the appearance of the data. This appearance is the result part of the object.

The representation of objects in RTF is designed to allow RTF readers that don't understand objects or don't use a particular type of object to use the current result in place of the object. This allows the appearance of the object to be maintained through the conversion even though the object functionality is lost. Each object comes with optional information about the object, a required destination that contains the object data, and an optional result that contains the current appearance of the object. This result contains standard RTF. It is an important responsibility of the RTF writer to provide the result so that existing RTF readers that either do not support objects or that do not support the particular type of object will be able to display the object.

When the object is an OLE embedded or linked object, the data part of the object is the structure produced by the OLESaveToStream function. Some OLE clients rely on the OLE system to render the object and a copy of the result is not available to the RTF writer for that application. For these cases, the object result can be extracted from the structure produced by the OLESaveToStream function. For information about the OLESaveToStream function, see the Microsoft Object Linking and Embedding Software Development Kit.

The syntax for this destination is:

<obj> ( '{' \object (<objtype> & <objmod>? & <objclass>? & <objname>? & <objtime>? & <objsize>? & <rsltmod>?) <objdata> <result> '}' ) | <pubobject>
<objtype> \objemb | \objlink | \objautlink | \objsub | \objpub | \objicemb | objhtml | objocx
<objmod> \linkself? & \objlock? | \objupdate?
<objclass> '{\*' \objclass #PCDATA '}'
<objname> '{\*' \objname #PCDATA '}'
<objtime> '{\*' \objtime <time> '}'
<rsltmod> \rsltmerge? & <rslttype>?
<rslttype> \rsltrtf | \rslttxt | \rsltpict | \rsltbmp
<objsize> \objsetsize? & \objalign? & \objtransy? & <objhw>? & \objcropt? & \objcropb? & \objcropl? & \objcropr? & \objscalex? & \objscaley?
<objhw> \objh & \objw
<objdata> '{\*' \objdata (<objalias>? & <objsect>?) <data> '}'
<objalias> '{\*' \objalias <data> '}'
<objsect> '{\*' \objsect <data> '}'
<result> '{' \result <para>+ '}'

Control word Meaning
Object Type
\objemb An object type of OLE embedded object. If no type is given for the object, the object is assumed to be of type \objemb.
\objlink An object type of OLE link.
\objautlink An object type of OLE autolink.
\objsub An object type of Macintosh Edition Manager subscriber.
\objpub An object type of Macintosh Edition Manager publisher.
\objicemb An object type of MS Word for the Macintosh Installable Command (IC) Embedder.
\objhtml An object type of HTML control.
\objocx An object type of OLE control.
Object Information
\linkself The object is a link to another part of the same document.
\objlock Locks the object from any updates.
\objupdate Forces an update to the object before displaying it. Note that this will override any values in the <objsize> control words, but reasonable values should always be provided for these to maintain backwards compatibility.
\objclass The text argument is the object class to use for this object; ignore the class specified in the object data. This is a destination control word.
\objname The text argument is the name of this object. This is a destination control word.
\objtime Describes the time that the object was last updated.
Object Size, Position, Cropping, and Scaling
\objhN N is the original object height in twips, assuming the object has a graphical representation.
\objwN N is the original object width in twips, assuming the object has a graphical representation.
\objsetsize Forces the object server to set the object's dimensions to that specified by the client.
\objalignN N is the distance in twips from the left edge of the objects that should be aligned on a tab stop. This is needed to place Equation Editor equations correctly in line.
\objtransyN N is the distance in twips the objects should be moved vertically with respect to the baseline. This is needed to place Math Type equations correctly in line.
\objcroptN N is the top cropping distance in twips.
\objcropbN N is the bottom cropping distance in twips.
\objcroplN N is the left cropping distance in twips.
\objcroprN N is the right cropping distance in twips.
\objscalexN N is the horizontal scaling percentage.
\objscaleyN N is the vertical scaling percentage.
Object Data
\objdata This subdestination contains the data for the object in the appropriate format; OLE objects are in OLESaveToStream format. This is a destination control word.
\objalias This subdestination contains the alias record for the publisher object for the Macintosh Edition Manager. This is a destination control word.
\objsect This subdestination contains the section record for the publisher object for the Macintosh Edition Manager. This is a destination control word.
Object Result
\rsltrtf Forces the result to be rich text format, if possible.
\rsltpict Forces the result to be a Windows metafile or MacPict image format, if possible.
\rsltbmp Forces the result to be a bitmap, if possible.
\rslttxt Forces the result to be plain text, if possible.
\rsltmerge Uses the formatting of the current result whenever a new result is obtained.
\result The result destination is optional in the \object destination. It contains the last update of the result of the object. The data of the result destination should be standard RTF so that RTF readers that don't understand objects or the type of object represented can use the current result in the object's place to maintain appearance. This is a destination control word.

When Word is used as an editor for Mail, the following control word can be emitted. It is not seen in other situations.

Control Word Meaning
\objattph Object attachment placeholder. Used in the RTF stream when Word is started as a mail editor and the message contains attachments. The control word tells where in the text stream the attachment should be placed. It does not define the actual attachment.

Macintosh Edition Manager Publisher Objects

Word for the Macintosh writes publisher objects for the Macintosh Edition Manager in terms of bookmarks (see "Bookmarks" on page 41 of this Application Note). The range of publisher objects are marked as bookmarks, so these controls are all used within the \bkmkstart destination. The RTF syntax for a publisher object is:

<pubobject> '{\*' \bkmkstart \bkmkpub \pubauto? (<objalias>? & <objsect>) #PCDATA '}'

Control word Meaning
\bkmkpub The bookmark marks a Macintosh Edition Manager publisher object.
\pubauto The publisher object updates all Macintosh Edition Manager subscribers of this object automatically whenever it is edited.