Programming Reference

Class definition file

LinkSpec.idl

Class C++ Binding

LinkSpec.xh

Class hierarchy

SOMObject
    ODObject
        ODBaseLinkSpec
            ODLinkSpec

Description

An object of the ODLinkSpec class advertises a part's ability to create a link to the data it is transferring.

A link specification is a signal that a link can be made from content in a specified source part. The link specification remains valid as long as its source part exists and the document containing it remains opened. After the document is closed, the link specification becomes meaningless.

When a source part that supports linking writes to the clipboard or drag-and-drop object, it uses a link specification to advertise its ability to create links. The source part creates a link specification by calling its draft's CreateLinkSpec method, passing as parameters a reference to itself and data sufficient to enable the source part to identify the selected content. The data in a link specification is private to the source part; it is returned to the source part if the part's CreateLink method is called to create a link. Because the link specification is valid only during the lifetime of its source part, the data can contain pointers to information maintained by the part.

A link specification provides methods for writing or reading itself to and from a focused storage unit. In addition to writing content to the storage unit of the data-transfer object (clipboard or drag-and-drop object), the source part calls the link specification's WriteLinkSpec method to write the link specification to the kODPropLinkSpec property.

For a paste or drop, the destination part creates an empty link specification by calling the draft's CreateLinkSpec method, passing null for the source part and data parameters. The destination part calls the ReadLinkSpec method of the empty link specification to read from the kODPropLinkSpec property of the content storage unit. The destination part then creates the link by passing the link specification to its draft's AcquireLink method, which in turn passes the link specification to the source part's CreateLink method.

When the source part writes a link specification to the clipboard, it should save the clipboard's current update ID, as returned by the clipboard's GetUpdateID method. The part must remove the link specification from the clipboard if any of the following conditions is true:

• It becomes infeasible to create the link, for example, because the potential source content is deleted or modified.

• The part's Release method is called.

The source part can check the clipboard update ID and compare it with the saved ID to determine whether its content is still on the clipboard.

For further information on the clipboard and drag-and-drop object, see the descriptions of the classes ODClipboard and ODDragAndDrop. For further information on the implementation of OpenDoc links, see the descriptions for the classes "ODLink" and ODLinkSource and the chapter on the data transfer in the OpenDoc Programming Guide.

Methods

The methods defined by the ODLinkSpec class include:

• ReadLinkSpec
• WriteLinkSpec

Overridden methods

There are no methods overridden by the ODLinkSpec class.