5.8.2 Implementing a Links Command

When a user chooses the Links command from the Edit menu, the client application needs to display a Links dialog box listing every linked object in the document. The selected links are highlighted in the dialog box. The dialog box allows the user to select whether link updating should be automatic or manual, update a link immediately, cancel a link, and repair broken links. For more information about this dialog box, see Chapter 3, "OLE User Interface."

A client application can use the OleGetLinkUpdateOptions and OleSetLinkUpdateOptions functions to support the link-update radio buttons in the Links dialog box.

There are three possible update options for linked objects:

Option Description

oleupdate_always Update the linked object whenever possible. This option supports the Automatic link-update radio button in the Links dialog box.
oleupdate_onsave Update the linked object when the source document is saved by the server application.
oleupdate_oncall Update the linked object only on request from the client application. This option supports the Manual link-update radio button in the Links dialog box.

These update options control when updates occur to the presentation of an object. The contents of the source document are used to update the presentation whenever the link is activated.

To support the Update Now button in the Links dialog box, a client application can call the OleUpdate function. When a user chooses Update Now, the client application should update the links the user selected.

The Cancel Link button in the Links dialog box changes an object into a picture that an application cannot edit by using standard OLE techniques. An application can implement the Cancel Link button by using the OleObjectConvert function.

A client application should activate the Change Link button in the Links dialog box only if all the selected links are to the same source document. When the client has the correct information, it can repair the link by using the OleGetData and OleSetData functions.

To retrieve the link information for an object, a client application can call the OleGetData function, specifying the ObjectLink format. The call to OleGetData fails if ObjectLink is specified and the object is not a link. A client application can retrieve class information by using OleGetData and specifying either the OwnerLink format for embedded objects or the ObjectLink format for linked objects. The client application could allow the user to edit the link information and store it into the object by using the OleSetData function, specifying the ObjectLink format.