6.2.7 Client User Interface

When a user opens a document that contains a linked or embedded object, the client application uses the OLE functions to communicate with OLECLI.DLL. This library assists the client application with such tasks as loading and drawing objects, updating objects (when necessary), and interacting with server applications.

6.2.7.1 New and Changed Commands

An OLE client application typically implements the following new or changed commands as part of its Edit menu. (Although this user interface is not mandatory, it is recommended for consistency with existing OLE applications.)

Command Description

Copy Copies an object from a document to the clipboard.
Cut Removes an object from a document and places it on the clipboard.
Paste Copies an object from the clipboard to a document.
Paste Link Inserts a link between a document and the file that contains an object.
Class Name Object Makes it possible for the user to activate the verbs for a linked or embedded object. The actual text used instead of the Class Name placeholder depends upon the selected object.
Links Makes it possible for the user to change link updating options, update linked objects, cancel links, repair broken links, and activate the verbs associated with linked objects.
Insert Object Starts the server application chosen by the user from a dialog box and embeds in a document the object produced by the server. This command is optional.
Paste Special Transfers an object from the clipboard to a document or inserts a link to the object, using the data format chosen by the user from a dialog box. This command is optional.

In addition to the listed menu changes, client applications must also implement changes to their Copy and Cut commands. When a linked or embedded object is selected in the client application, the application can use the OleCopyToClipboard function to implement the Cut and Copy commands.

When the user chooses the Paste command, a client application should insert the contents of the clipboard at the current position in a document. If the clipboard contains an object, choosing this command typically embeds the object in the document.

When the user chooses the Paste Link command, the client library typically inserts a linked object at the current position in a document. The object is displayed in the document, but the Native data that defines that object is stored elsewhere.

If a user copies a linked object to the clipboard, other documents can use this object to produce a link to the original data.

The Class Name Object command allows the user to choose one of an object's verbs. If the selection in the document is an embedded object, the Class Name placeholder is typically replaced by the class and name of the object; for example, if a user selects an object that is a range of spreadsheet cells for Microsoft Excel, the text of the command might be “Microsoft Excel Worksheet Object.” If an object supports only one verb, the name of the verb should precede the class name in the menu item; for example, if the only verb for a text object is Edit, the text of the command might be “Edit WPDocument Object.” When an object supports more than one verb, choosing the Class Name Object command brings up a cascading menu listing each of the verbs.

For more information about verbs, see Section 6.1.2.2, “Verbs.”

Choosing the Links command brings up a Links dialog box, which lists the selected links and their source documents and gives the user the opportunity to change how the links are updated, cancel the link, change the link, or activate the verbs for the link. A user can use this dialog box to repair links to objects that have been moved or renamed.

When the user chooses the Paste Special command, a client application should bring up a dialog box listing the data formats the client supports that are presently on the clipboard. The Paste Special dialog box makes if possible for the user to override the default behaviors of the Paste and Paste Link commands. For example, if the first format on the clipboard can be edited by the client appli-cation, the default behavior is for the client to copy the data into the document without making it into an object. The user could override this default behavior and create an object from such data by using the Paste Special command.

When the user chooses the Insert Object command, a client application should allow the user to insert an object of a specified class at the current position in a document. For example, to insert a range of spreadsheet cells in a text document, a user could choose the Insert Object command and select “Microsoft Excel Worksheet” from the dialog box. Selecting this item would start Microsoft Excel. The user would use Microsoft Excel to create the object to be embedded in the text document. When finished, the user would quit Microsoft Excel; the range of spreadsheet cells would automatically be embedded in the text document.

The Insert Object command is optional because a user could achieve the same
results without it, although the procedure is less convenient. To use the same
example as that shown in the preceding paragraph, the user could leave the client application, start Microsoft Excel, and use the Microsoft Excel Cut or Copy command to transfer data to the clipboard. After returning to the client application, the user could choose the Paste command to move the data from the clipboard into the text document.

If the user chooses the Undo command after activating an object, all the changes made since the object was last updated (or since the object was activated, if it has not been updated) are discarded and the object returns to its state prior to the update. The Undo command closes the connection to the server.

For more information about these commands, including illustrations of the dialog boxes, see Microsoft Windows User Interface Guidelines.

6.2.7.2 Using Packages

A package is an embedded graphical object that contains another object, which can be linked or embedded. For example, a user can package a file in an icon and embed the icon in an OLE document. Most of the packaging capabilities are provided by the dynamic-link library SHELL.DLL.

A user can put a package into an OLE document in a number of different ways:

Copy a file from File Manager to the clipboard, and then choose the Paste or Paste Link command from the Edit menu in the client application.

Drag a file from File Manager and drop it in the open window for a document in a client application.

Select Package from the list of objects in the Insert Object dialog box. This starts Object Packager, with which the user can associate a file or data selection with an icon or graphic. Choosing Update and then Exit from Object Packager's File menu puts the package in the client document.

Run Packager directly, following the steps outlined in the previous list item.

For information about how a client application should react when a user drops a file from File Manager in the client's window, see the description of the OleCreateFromFile function in the Microsoft Windows Programmer's Reference, Volume 2.

A user whose system does not include the Windows version 3.1 File Manager can follow these steps to create a package by using Object Packager:

Copy to the clipboard the data to be packaged.

Open Object Packager and paste the data into it. (At this point, the user could modify the default icon, the default label identifying the icon, or both.)

Choose Copy Package from the Object Packager Edit menu to copy the package to the clipboard.

Choose the Paste command from the Edit menu in the client application to embed the package.

For more information about Object Packager, see Section 6.1.2.1, “Packages,” or Microsoft Windows User Interface Guidelines.