WW0532: Object Linking and Embedding (OLE)

                  FEATURES OF OLE NOT FOUND IN DDE
                  ================================

   Feature                      | Description

                                |
   Extensibility for future     | The OLE libraries can be updated in
   enhancements                 | future releases to support new data
                                | formats, link tracking, and other
                                | new features of OLE as they are
                                | developed.
                                |
   Persistent OLE embedding and | The OLE libraries do most of the
   OLE linking of objects       | work of activating objects when an
                                | embedded document is reopened, by
                                | reestablishing the conversation
                                | between a client and server. In
                                | contrast, establishing a DDE link is
                                | either your responsibility (if there
                                | is no link) or the application's
                                | responsibility (if the link is
                                | persistent).
                                |
   Rendering of common data     | The OLE libraries assume the burden
   formats                      | of rendering common data formats in
                                | a display context. DDE applications
                                | must do this work themselves.
                                |
   Server rendering of          | The OLE libraries facilitate the
   specialized data formats     | rendering of specialized data
                                | formats in the client's display
                                | context. The server application or
                                | object handler actually performs the
                                | rendering. The client application
                                | has to do very little work to render
                                | the embedded or linked data in its
                                | display context.
                                |
   Activation of embedded and   | The OLE libraries support activating
   linked objects               | a server application (the
                                | application associated with the
                                | object) to edit a linked or embedded
                                | object to render data. Activating
                                | servers for data rendering and
                                | editing is beyond the scope of DDE.
                                |
   Creation of objects and links| The OLE libraries do most of the
   from the Clipboard           | work when an application is using
                                | the Windows Clipboard to copy and
                                | paste links or exchange objects. In
                                | contrast, DDE applications must
                                | directly call the Windows Clipboard
                                | functions to perform such
                                | operations.
                                |
   Creation of objects and links| The OLE libraries provide direct
   from files                   | support for using files to exchange
                                | data. No DDE protocol is defined for
                                | this purpose.


               OLE LINKING AND OLE EMBEDDING TERMINOLOGY
               =========================================

OLE DOCUMENT

An OLE document is a document that contains data in several different formats (see Figure 1). An OLE document uses the facilities of different OLE applications to present the different kinds of data it contains.

Note that an OLE document can incorporate links to information, rather than the information itself. If a document uses links, it requires minimal storage and is updated automatically whenever the linked data changes.

<Graphic Deleted> Figure 1. An OLE document

When you are working with an OLE document, you do not need to know which data formats are compatible with one another or how to find and start the applications that created the data. Whenever you choose part of an OLE document, the server application starts automatically. For example, an OLE document could be a brochure that includes text, charts, cells of financial data, and illustrations. By selecting different data within the brochure, you can automatically switch between the word processor, spreadsheet, and graphics programs that produced its components.

CLIENT

A client is a document that contains objects managed by other applications, or the application that manages such documents. The OLE client applications that are included with Microsoft Windows 3.1 are Write and Cardfile. Figure 1 shows Write acting as a client. Other examples of OLE clients are Microsoft Word for Windows and Microsoft Excel for Windows.

SERVER APPLICATION

A server application is an application that provides editing and rendering services for a linked and embedded object. When you double- click an object in a client document, the server application is invoked. A new instance of the server application is started even if one is already running. (The advantage of starting a new instance of the server application is that it is initially dedicated to the current object and does not contain any unrelated document windows.)

<Graphic Deleted> Figure 2. Microsoft Draw--an OLE server application

Paintbrush is an OLE server application that is included with Microsoft Windows 3.1. Other examples of OLE server applications are Microsoft Excel, Microsoft PowerPoint, and Microsoft Draw.

OBJECT

An object is any data that can be displayed in an OLE document and manipulated by a user. An object can be anything from a single cell in a spreadsheet to an entire document or illustration. When an object is incorporated into a document, it maintains an association with the application that produced it. OLE applications are "opaque"; that is, the client application never looks inside the object and therefore doesn't need to understand its contents. The client simply calls functions in the OLE libraries when it needs to display an object or invoke the server application for editing purposes.

<Graphic Deleted> Figure 3. The Insert Object dialog box from Microsoft Word for Windows

EMBEDDED OBJECT

An embedded object is an object that is completely contained within the client document. For example, when a range of spreadsheet cells from Microsoft Excel is embedded in a Microsoft Write file, all the data associated with the cells, including any formulas, is saved as part of the Write file. The name of the server for the spreadsheet (Microsoft Excel) is saved along with the data. While working with the Write file, you can double-click this embedded object (the range of cells), and Microsoft Excel will start automatically so that you can edit those cells.

LINKED OBJECT

A linked object is a reference, or link, to data shared by a server application and a client. If the range of spreadsheet cells from our example is a linked object instead of an embedded object, the data is stored in a Microsoft Excel file and only the link to the data is saved with the Write file. The server then "presents" the data, in the proper format, to the client document (see "Presentation Data" below). You can still double-click the object to bring up the server application (in this case, Microsoft Excel) and edit the information.

PRESENTATION DATA

Presentation data is formatted data sent from the server application to the client so that the client can display and print the object. (Presentation data is referenced by an ObjectLink.)

OBJECT CLASS

The object class describes the type of information an object contains, and is assigned by the server application. Examples of Microsoft object classes include picture (Microsoft Paintbrush), worksheet (Microsoft Excel for Windows), and document (Microsoft Word for Windows).

DOCUMENT NAME/ITEM NAME

The document name and item name identify the object within whatever server application or document it resides.

OBJECTLINK

An ObjectLink is a DDE and Clipboard format that carries a descriptor of a source object. The ObjectLink contains the class, document, and item that identify a linked object. An ObjectLink is represented internally by three null-terminated strings followed by a null string (that is, a null character). (This format describes a linked object.)

OWNERLINK

An OwnerLink is a DDE and Clipboard format that carries a descriptor of the owner of an OLE object. An OwnerLink has the same format as an ObjectLink, and is used to communicate information about the owner of an object, which may be distinct from the source. (This format describes an embedded object.)

NATIVE

Native is the format of the data that defines the object; this format and its interpretation are known only to the server application. Native format data is transferred between the client and the server application in the case of embedded objects, where a client document provides permanent storage and the server application provides editing features.

VERB

The types of actions you can perform on an object are called verbs. For example, two common verbs for an object are play and edit. The nature of an object determines the verbs that you can initiate; for example, you typically play a voice annotation and edit a text file. The typical use for an object is called the "primary verb." Double- clicking an object usually executes the action specified by the primary verb. Other possible verbs for an object are called "secondary verbs." (Note that many objects support only one verb.)

PACKAGE

A package is a type of OLE object that encapsulates another object, a file, or a command line inside a graphic representation (such as an icon or bitmap). When you double-click the graphic object, the OLE libraries execute the primary verb of the object contained in the package. The graphic part of a package is always an embedded object, not a link; thus, the graphic is saved as part of the client document. The package contents can be an embedded object, a linked object, a static object, or a command line.

Packages are useful for presenting compact "token" views of large files or OLE objects. An application can also use packages as hyperlinks. You can use Microsoft's Object Packager (PACKAGER.EXE), a packager application that ships with Windows 3.1, to associate a file or data selection with a particular icon or graphic. (The secondary verb for a package is "edit package"; when you choose this verb, Object Packager starts.)

                         OLE LIBRARIES
                         =============

DATA TRANSFER IN OLE

Applications use three dynamic-link libraries (DLLs)--OLECLI.DLL, OLESVR.DLL, and SHELL.DLL--to implement OLE. OLECLI.DLL and OLESVR.DLL support OLE, while SHELL.DLL supports the system registration database. These libraries can be included with any products developed under Windows versions 3.1 and 3.11 to ensure the products will run under Windows version 3.0.

COMMUNICATION BETWEEN OLE LIBRARIES

Client applications use functions from the OLE application programming interface (API) to inform the client library, OLECLI.DLL, that a user wants to perform an operation on an object. The client library uses DDE messages to communicate with the server library, OLESVR.DLL. The server library is responsible for starting and stopping the server application, directing the interaction with the server application's callback functions, and maintaining communication with the client library.

When a server application modifies an embedded object, the server application notifies the server library of changes. The server library then notifies the client library, and the client library calls back to the client application, informing it that the changes have occurred. Typically, the client application then forces the embedded object to be redrawn in the document file. If the server application changes a linked object, the client library is notified that the object has changed and should be redrawn.

OBJECT HANDLERS

Some server applications implement a fourth kind of OLE library called an "object handler." Object handlers are DLLs that act as intermediaries between client and server applications. Typically, an object handler is supplied by the developer of a server application as a way of improving performance. For example, an object handler can be used to redraw a changed object if the presentation data for that ob- ject could not be rendered by the client library.

                       OBJECT INSERTION METHODS
                       ========================

INSERTING AN EMBEDDED OBJECT

The basic procedure for inserting an embedded object is simple. For example, to insert a Paintbrush drawing in a Write document:

1. In the server application (Paintbrush), select the drawing, then choose the Copy command from the Edit menu.

2. Switch to the client application (Write), position the insertion point at the correct location, and choose the Paste command from the Edit menu.

Most applications, however, will not be able to provide full editing capabilities for any alternative format, and they will simply embed the object and allow the source application to provide editing tools.

Therefore, in most applications that support OLE, when the Clipboard contains an object from another application, the Paste command embeds the object in the current document. Note that in applications that do not support OLE, the Paste command simply inserts a static copy of the data, without providing easy access to the tools required for later editing of the data.

INSERTING A LINKED OBJECT

Inserting links to objects is just as easy as OLE embedding objects. To continue the example using Paintbrush and Write, suppose that instead of OLE embedding the drawing, you wanted to insert a link to the drawing. The following steps would be required:

1. In the server application (Paintbrush), select the drawing and choose Copy from the Edit menu.

2. Switch to the client application (Write), position the insertion point at the correct location, and choose Paste Link from the Edit menu.

Once a link exists in one document, it can be inserted in other documents using the Copy and Paste commands. When a linked object, including the ObjectLink format, is copied, all information describing the object is copied to the Clipboard as one self-contained unit. When the object is pasted into a client, it possesses the same attributes as the original object from which it was copied.

PASTE SPECIAL

The Paste Special command on the Edit menu allows you to control the manner and format in which an object is inserted into a client document. For example, you may want the data to be inserted as an embedded object (rather than translated into a client-editable format), so that the tools of the server application can easily be invoked to edit the object. Alternatively, certain special tools or editing operations might be available only when the data is in a format that cannot be manipulated by the client application.

The dialog box activated by the Paste Special command enables you to control the insertion of the object in the following ways:

• The Data Type list allows you to choose the format for the inserted object. The first choice is generally the "object class name," which is the format the data takes in the server application. Examples of object class names are Microsoft Excel Worksheet, Microsoft PowerPoint Slide, and Microsoft Paintbrush Bitmap. The other choices are the formats available on the Clipboard: Formatted Text (meaning RTF, or rich-text format), Unformatted Text, Picture, and Bitmap.
• Paste and Paste Link buttons are provided so that you can override the default choice made by the client application. Both choices translate the data into the selected format and insert the data into the document. The Paste button does not establish a link to the original source of the data. If you have selected the object class name rather than a data format, the data is inserted as an embedded object instead of being translated into a client-editable format. The Paste Link button establishes an automatic link to the original source of the data.

INSERT OBJECT

To facilitate the OLE embedding of blank objects, applications may implement an Insert Object command. In applications that include an Insert menu (for example, Microsoft Word for Windows), the command appears on that menu and is labeled "Object." In applications that do not include an Insert menu, the command appears on the Edit menu and is called "Insert Object." The dialog box that appears when you choose the Insert Object command contains the Object Type list, a list of object names drawn from the registration database maintained by the system in the REG.DAT file.

To embed an object, select its name from the list, and choose the OK button (or press ENTER). This activates the server application for the selected object. The server application then displays a blank window in which you can create and edit the object. After creating and editing the object, choose Update from the File menu of the server application. This command inserts the object where the insertion point was positioned in the client when the Insert Object command was chosen. You can then close the server application by choosing Exit from the File menu, and return to the client document.

NOTE: Not all Windows applications contain the Insert Object command.

                          OBJECT ACTIONS
                          ==============

VIEWING OBJECTS

Complex OLE documents may contain several linked or embedded objects (OLE objects), interspersed with objects that are native to the docu- ment. Because OLE objects support different operations than those supported by the native objects, it is convenient if you can visually distinguish OLE objects from native ones. For this purpose, applica- tions should provide visual indications of OLE object boundaries. The boundaries of a particular object should appear whenever the object is selected. In addition, applications should provide a way for all object boundaries to be turned on or off at once, to facilitate easy viewing of all OLE objects in a document. For example, applications may reveal object boundaries, as well as other normally hidden infor- mation, through a Hidden Structure command on the View menu or through a Show All check box in a Preferences dialog box.

The exact method of indicating object boundaries depends on the nature of the client application and the type of OLE object. Three possible methods are:

1. Complete borders surrounding the object. For VGA monitors, the border should be dark gray; for non-VGA monitors, the border should be a 50-percent gray pattern.

2. Special graphic characters (for example, "{" and "}") at the beginning and end of the object.

3. Distinctive formatting (for example, a dotted underline) that is not used elsewhere in the client.

EDITING OBJECTS

Double-Clicking the Object

Once linked or embedded objects are inserted in a document, the standard user interface provides three methods for editing them. The first method involves double-clicking the object or object boundary to invoke a new instance of the server application, with the OLE object as the active document.

Note that in the following situations, a new instance of the server application is not started:

• The object is already open in an existing instance of the server application. In this case, the existing instance should be brought to the front.
• The server application is a multiple document interface (MDI) application and is the same as the client application. The appropriate behavior depends on whether the link is external or internal.

INTERNAL LINKS: In contrast to the preceding example, suppose that the link in the original Word document refers to another part of that same document. If you double-click the link, the current document window should scroll to show the source of the link.

When the server application's window opens, the object is loaded into the window. For embedded objects, the window is initially sized to show only the portion of the object displayed in the client. You can resize the window to display additional portions of the embedded object. When linked objects are used, the entire linked file is loaded, and the linked portion is selected. You can then modify the object with the tools provided by the server application.

Updating Objects from Non-MDI Server Applications

When a non-MDI application (for example, Paintbrush) functions as a server application for an embedded object, the Save command on the File menu changes to Update. This change occurs only for embedded objects, not for linked objects. The Update command updates the object in the client but does not close the server application. The server application remains open so you can make further changes after noting the effects (for example, repagination) of the update on the client. Updates to embedded objects can be undone through the Undo command on the client's Edit menu.

If you attempt to exit the server application without updating the object, a warning message is displayed, asking if you want to update the client document ("Update <client filename>?").

When an embedded object is being edited, the Save As command on the File menu can be used to save a copy of the object in a separate file. If the client file has not yet been updated, the "Update <client filename>?" warning message is displayed before the Save As dialog box appears. Choosing New from the File menu also displays the "Update <client filename>?" warning message.

When the server closes, the focus returns to the client. If you attempt to close the client while server documents for that client are still open, the server documents are closed first, after the usual checks for unsaved data.

Updating Objects from MDI Server Applications

The procedure for editing and updating objects from MDI server applications is similar to the procedure for non-MDI server applications, with the following exceptions.

If the focus changes from the embedded object window to a "normal" document window (that is, one containing an existing file or a new document), the Update command on the File menu changes back to Save. If the embedded object window regains the focus, Save becomes Update again.

When New is chosen from the File menu, the window containing the embedded object remains open. Therefore, the "Update <client filename>?" warning message is not displayed if the client file has not yet been updated.

Updating Objects Using the Links Command

The second method for editing OLE objects involves two commands on the Edit menu. The Links command produces a dialog box that allows you to change the type of updating (automatic or manual) for links, update linked objects, cancel links, repair broken links, and invoke the verbs associated with linked objects. The Links dialog box should use object-specific verbs if possible; otherwise, the generic verbs "activate" and "edit" should be used.

When the Links dialog box opens, the Links list shows each link in the document; links in the current selection are highlighted. Embedded objects in the current selection are not shown in the list. As you select different links in the Links list, the verbs on the two object- specific buttons will change accordingly.

Below the Links list, the dialog box contains two Update option buttons: Automatic and Manual. These buttons reflect whether the currently selected links are automatically updated whenever the linked file changes or whether they must be manually updated.

The Update Now button in the Links dialog box updates all links selected in the Links list. The presentations of the linked objects in the client are updated to reflect the current data in the linked (server) files.

The Cancel Link button in the Links dialog box permanently breaks the link between the client and the server application. The linked object in the client is changed to a picture that can no longer be edited or updated through the standard OLE techniques. The picture can still be edited using the cut/copy/paste techniques, but it will not retain all the data present in the original linked object. No link boundaries will be displayed for the picture.

The Change Link button in the Links dialog box is dimmed if the selection in the Links list includes multiple links to multiple files. Otherwise, if all the selected links are linked to the same file, the button is active and leads to a dialog box exactly like the File Open dialog box, except that the title is Change Link (in most applications). The Change Link dialog box allows you to change the file to which a link refers. This feature has two uses. First, it allows broken links to be reestablished. Second, the dialog box allows a single client that operates on linked data files to be successively connected to different linked files. This flexibility in providing data to the client is particularly useful for applications such as spreadsheets and databases.

In addition to these standard options, an application's Links dialog box may also include a list box for changing the format in which the object is displayed.

Updating and Acting Upon Objects Using

the "Object Class Name" Object Command

The third method for editing OLE objects involves the "Object Class Name" Object command on the Edit menu, which allows you to choose one of an object's verbs. If the selection in the document is a single embedded object, the class name placeholder is typically replaced by the class and name of the object (for example, "Microsoft Excel Worksheet"). If an object supports only one verb, the name of the verb should precede the class name in the menu item (for example, "Edit WPDocument Object"). When an object supports more than one verb, choosing this menu item brings up a menu listing each of the verbs associated with the selected object.

                          REGISTRATION
                          ============

The entries in the registration database are used whenever an application or library needs information about an OLE server application. For example, client applications that support the Insert Object command refer to the database in order to list the OLE server applications that could provide a new object. The client applications also use the registration database to retrieve the name of the server application for the Paste Special dialog box.

The registration database stores key/value pairs, where keys and values are null-terminated strings. Keys are hierarchically structured, with the names of the components and keys separated by backslash (\) characters. To be available for OLE transactions, a server application should register the key/value pairs shown in the following example when the server application is installed. The class name and server application path should be registered for every class the server application supports. If a class has an object-handler library, it should be registered using the "handler" keyword. An application should also register all the verbs its class or classes support. An application's verbs must be sequential; for example, if an object supports three verbs, the primary verb is 0 and the other verbs must be 1 and 2.

The following example shows the form of the key/value pairs as they would be added to a database using the Registration Information Editor, REGEDIT.EXE. An application could also use the registration API to add this information to the database.

   HKEY_CLASSES_ROOT\<class name> = readable version of class name
   HKEY_CLASSES_ROOT\<.ext> = <class name>
   HKEY_CLASSES_ROOT\<class name>\protocol\StdFileEditing\server =
      <executable filename>
   HKEY_CLASSES_ROOT\<class name>\protocol\\StdFileEditing\handler =
      <dll name>
   HKEY_CLASSES_ROOT\<class name>\protocol\StdFileEditing\verb\0 =
      <primary verb>
   HKEY_CLASSES_ROOT\<class name>\protocol\StdFileEditing\verb\1 =
      <secondary verb>

   HKEY_CLASSES_ROOT\<class name>\protocol\StdExecute\Server =
      <executable filename>

For compatibility with earlier applications, the system registration service also reads and writes registration information in the [embedding] section of the WIN.INI initialization file. A sample [embedding] section follows:

   [embedding]
   ExcelWorksheet=Worksheet created by Microsoft Excel,Excel Worksheet,
      EXCEL.EXE, picture
   WordDocument=Word Document,Word Document,C:\WINWORD\WINWORD.EXE,
      picture
   SoundRec=Sound Recorder Waveform Audio,Sound,SoundRec.exe,picture
   Package=Package,Package,packager.exe,picture
   PBrush=Paintbrush Picture,Paintbrush Picture,pbrush.exe,picture

   <Object Class Name>=<Comment>,<Textual Class Name>,<Path>/<Arguments>,
      [picture]

Note that a server application can register the entire path for its executable file, or register only the file's name and arguments. Registering only the filename without the path will cause the server application to fail if the application is installed in a directory that is not mentioned in the PATH environment variable in the AUTOEXEC.BAT file. Generally, registering the path and filename is recommended instead of registering only the filename. In the above example, you may want to verify that the directory containing EXCEL.EXE is mentioned in your PATH environment variable.

TO OBTAIN THIS APPLICATION NOTE

You can find WW0532.EXE (size: 26124 bytes) 
                       , a self-extracting file, on the following

• Microsoft's World Wide Web Site on the Internet

        On the www.microsoft.com home page, click the Support icon.
        Click Knowledge Base, and select the product.
        Enter kbfile WW0532.EXE (size: 26124 bytes) 
                               , and click GO!
        Open the article, and click the button to download the file.
  
  

• Internet (anonymous FTP)

        ftp ftp.microsoft.com
        Change to the Softlib/Mslfiles folder.
        Get WW0532.EXE (size: 26124 bytes) 
  

• Microsoft Download Service (MSDL)

        Dial (425) 936-6735 to connect to MSDL
        Download WW0532.EXE (size: 26124 bytes) 
  

   ARTICLE-ID: Q119591
   TITLE     : How to Obtain Microsoft Support Files from Online
               Services