View figure.
Linking is a mechanism for placing information into a part and allowing that information to be updated, based on changes to source information in another part or document.
Linking support in OpenDoc is a combination of event-handling code and storage code. It includes a set of notification calls that keep the transferred data synchronized with its source.
Some aspects of linking are closely related to the other data-transfer objects. Link specifications, used in writing data to the clipboard or drag and drop object, are described in "Link Specification". The interactions between cutting and pasting and the preservation of link-related objects are listed in "Transfer Rules for Links and Link Sources".
Linking requires the cooperation of one or two parts with several linking-related objects. Figure 66 is a schematic illustration of the objects and data involved in linking. The figure shows a link between two separate parts (which can be in the same document or in different documents), although links can also occur within a single part.
Figure 66. Objects and Data Involved in Linking
The user creates a link by requesting it during a paste or drop operation. The part that contains the source of the information to be linked is called the source part. The content that is to be copied and sent to another part is called the source content or source. The source part creates an object, the link source, that contains a copy of the source data; that copy is stored in the same document as the source part.
The part that contains the destination of the information to be linked is called the destination part. The content that is actually copied into the destination part is called the destination content or destination. The draft object of the destination part creates an object, the link, that is stored in the same document as the destination part.
The link-source object contains references to all link objects for which it is the source. The user is free to edit the source of a link; when a change occurs in the source part and the link needs to be updated, the source part copies the source content into the link-source object. The destination part then copies the content from the link object into the destination itself.
OpenDoc links are unidirectional; changes are propagated from the source to the destination only. You should not permit users to edit any link destinations that you maintain; such edits would be overwritten when the link is updated.
Whether it contains the source or the destination of a link, your part is responsible for defining the exact content that constitutes the linked data and for knowing what visual area it covers in your part's display. Linked data, whether source or destination, is part of your own content; you store and manipulate it according to your own content model and under your own control.
Each link source and each link destination must have an associated update ID. A link source or link destination is a region of content. The source part determines the update ID associated with the link and updates the ID each time the source changes. The destination part stores the update ID of the link that was current at the time the destination was last updated through the link.
Whenever the content in your part changes, you need to assign a new update ID to all link sources directly affected by that change. All link sources affected by a given change must have the same update ID. You obtain a new update ID by calling the session object's UniqueChangeID method.
When you update a link source, you can save the update ID in your source content and use it later to determine whether your source content and the content of the link-source object are identical.
A circular link or recursive link can occur when changes to a link's destination directly or indirectly affect its source. To avoid endless recursive updates, it is important that your part take these steps:
It is possible that your part containing the link destination is embedded in the link source content of another part. In that case, you must call your frame's ContentUpdated method so that the part owning the link source can be notified that your content has changed and be given the update ID of the change.
OpenDoc informs destination parts when the sources of their links have been updated. The update notification can be:
Automatic | Immediately (if the source is in the same document as the destination) or whenever the user saves the source document (if the source is in a different location) |
Manual | Only when instructed to do so by the user |
The user initiates a manual update by pressing the Update Now button in the Link Destination Info dialog box. Pressing the Update Now button in the Link Destination Info dialog box updates only the link destination from the link object.
To be notified automatically of changes to the source of a link, your destination part calls the link object's RegisterDependent method, supplying it the update ID of the last content it read from the link. Each link object maintains a private registry of dependent parts and calls their LinkUpdated methods whenever the link source changes. Your part should respond to this method call by updating its destination content from the link object, as described in "Updating a Link at the Destination".
If updating is to be automatic, your part should register for update notification when it first creates the link (passing an update ID of kODUnknownUpdate), and whenever your part reads itself from storage (passing the appropriate stored update ID from its link info structure). Be sure you are prepared to receive a notification when you call RegisterDependent, because your LinkUpdated method may be called before RegisterDependent returns. You can unregister and re-register as desired, but be careful not to register more than once at a time with the same link.
If your draft permissions are read-only, you should not register for update notification. Even if you do register, you do not receive notifications.
Updating a manual link without user instruction
If you maintain a link source set for manual updating, the state of your source content at any given time may be different from the contents of the link-source object. If another destination is added to the link, you must update the link-source object so the new destination and all existing destinations show the same content.
OpenDoc allows owners of source parts to either specify that changes to link source content become visible as soon as the content changes (automatic), or only when explicitly requested (manually) by the source part. The source part calls the IsAutoUpdate method to determine the update mode. In the automatic mode (default), the part should update the Link Source Content Storage Unit (CSU) as soon as possible after the editing operation, which changed the content completely. In the manual mode, the parts should suppress updating the Link Source Content Storage Unit until asked (by the user pressing the Update Now button in the Link Source Info dialog box.)
All frames have a link status that describes the frame's participation in links. Parts are responsible for setting the link status of all frames that they embed; the link status indicates whether the frame is in the source of a link, in the destination of a link, or not involved in any link, or both. Parts can use this information to decide whether to allow editing of linked data, and whether to allow creation of a link within an existing link; see Table 11 for a list of the possible combinations.
In general, any time that you create a link involving an embedded frame or add an embedded frame to your part, you should set the frame's link status.
Note:
If you do not support linking, you must nevertheless set the link status of your embedded frames (to kODNotInLink).
The ChangeLinkStatus method changes the value of the frame's link status, if necessary, and calls the LinkStatusChanged method of the frame's part, so that the part can change the link status of any of its own embedded frames.
When you set the link status of a frame in any of these situations, you need to take into account only the links that your part maintains; you can ignore your own display frame's link status. OpenDoc automatically adjusts the link status of frames that you embed to account for your display frame's status.
You can examine the link status of a frame by calling its GetLinkStatus method.
Your own part's LinkStatusChanged method is called by the ChangeLinkStatus method of any of your display frames, whenever the display frame's link status is changed. This is its interface:
void LinkStatusChanged (in ODFrame frame); |
Your implementation of LinkStatusChanged should iterate through all of your part's embedded frames, calling each one's ChangeLinkStatus method.
It is important to make this call to all of your embedded frames, so that they can in turn call their parts' LinkStatusChanged method to change the link status of more deeply embedded frames, and so on.
You need not call the ChangeLinkStatus method of all of your embedded frames immediately upon receiving a call to ChangeLinkStatus. If you instantiate frame objects only when needed for display (see "Lazy Instantiation"), you can internally record which frames are affected, and the set their link status when you bring them into memory.
Note:
If the user attempts to edit the content of any of your display frames whose link status is kODInLinkDestination, you should disallow the attempt.See "Editing a Link Destination" for details.
Because linked content can contain embedded frames, there must be a way for an embedded part to inform its containing part that its content has changed, so that the link can be updated.
Any time a content change occurs in one of your part's display frames, you should follow the procedures described in "Making Content Changes Known". Part of the procedure is to call the frame's ContentUpdated method. The ContentUpdated method then calls the EmbeddedFrameUpdated method of your part's containing part, informing it that the content of one of its embedded frames has changed. If your display frame is involved in a link source maintained by your part's containing part, the containing part can then choose to update the link-source object with the new data.
(This ContentUpdated method is unrelated to the ContentUpdated method of ODLinkSource, discussed in "Updating a Link at the Source". However, you pass the same update ID to both ContentUpdated methods when a content change to your part is entirely due to a content change to its link source.)
Your part's EmbeddedFrameUpdated method is called by the ContentUpdated method of any of your embedded frames, whenever the content of the frame's part has changed. This is its interface:
void EmbeddedFrameUpdated(in ODFrame frame,
in ODUpdateID change);
|
The method is passed a reference to the embedded frame and an update ID identifying the modification. You should respond by saving the Update ID and updating any link-source objects that you maintain that involve that frame (and whose updating is automatic). When updating the link source, pass it the Update ID that you received in the call to this method.
Your EmbeddedFrameUpdated method should also call the ContentUpdated method of your own display frames that contain the embedded frame. In this way, the change is propagated upward throughout the embedding hierarchy.
If your part contains the source or destination of a link, you are responsible for drawing an appropriate border around the linked content area when requested to do so.
Whenever you draw your part's content in a facet, first call the ShouldShowLinks method of the facet's window. If ShouldShowLinks returns kODTrue, draw borders around any link sources and destinations.
The link info structure (type ODLinkInfo) contains fields that hold information about the nature of a link, such as the part kind of its intrinsic data, its creation date, and its update ID. Your part should allocate and maintain a link info structure for every link destination that it contains.
Here is the structure's definition:
struct ODLinkInfo
{
ODType kind;
ODTime creationTime;
ODTime changeTime;
ODUpdateID change;
ODBoolean autoUpdate;
};
|
Just as the basic data-transfer actions (cutting, pasting, and dropping) should be undoable, so should their variations that involve linked data. The user should be able to undo (and redo) any of these actions:
When a link is created, the part receiving the data and creating the link destination adds a begin action and end action to the undo action history (see "Adding Multistage Actions"), whereas the source part adds a single action to the history when it creates the link source.
Edits to the source content of a link must be undoable. However, updates to a link source object from its source content do not need to be undoable.
Note:
Automatic updating is not a user action and cannot be undone.
Likewise, updates to the destination content of a link from its link object do not need to be undoable:
When you delete or cut content that includes a link source or destination, or when you break a link, follow the procedures outlined in "Breaking and Cutting Links" to make sure that you can undo the actions.
This section describes some of the basic procedures you follow in creating links, reading and writing linked data, and updating links.
Related information is described as part of general data-transfer considerations earlier in this chapter. Creating and removing link specifications are described in "Link Specification" and "Removing a Link Specification from the Clipboard".
Both the source and destination parts of a link, or even separate destinations of a single source, may attempt to access linked data simultaneously. Therefore, many methods of the classes ODLinkSource and ODLink require that you provide a key before accessing the storage unit containing the content of a link. You obtain the key by first calling the Lock method of the link-source object or link object involved.
A link is created when the user decides, using the Paste As dialog box, to link rather than statically transfer data during a paste. The destination part, the part receiving the paste or drop, retrieves the link specification from the clipboard or drag and drop object and calls the destination draft's AcquireLink method for the part. The source's part draft calls the CreateLink method of the source part that placed the data in the clipboard or drag and drop object.
If your part is the destination part that creates a link to pasted data from the data's source, you can use the following steps. It assumes that you called the ShowPasteAsDialog (OS/2 and Windows) method of the clipboard or drag and drop object (see "Handling the Paste As Dialog Box"), and are ready to act on the results of the Paste As dialog box. For clipboard transfer, this means that you have already acquired the clipboard focus (see "Acquiring and Relinquishing the Clipboard Focus").
Never read the link content from the storage unit of the clipboard or drag and drop object when creating the link; always read link content from the link object's storage unit.
Every time the link is updated, your part (the destination part) must discard the data in the link destination and read it again from the link object. This process can entail discarding embedded parts and creating them anew from the updated link content. See "Updating a Link at the Destination" for details.
Your destination part must be able to draw a border around the link content area when asked to do so, as described in "Link Borders". Parts embedded in linked data are not involved in the maintenance of the link; even in the case of a link destination that consists of a single embedded part, you draw the link border around the embedded part's frame.
Only the draft should call CreateLink; if your part is a destination part that needs a link to be created, you should call your draft's AcquireLink method.
When the user decides to create a link to data that your part placed on the clipboard or drag and drop object, the destination part's draft calls the CreateLink method of your part (the source part). The draft passes back the data of the link specification that your part originally wrote when it placed the data on the clipboard or drag and drop object. This is the interface to CreateLink:
ODLinkSource CreateLink(in ODByteArray data); |
When your source part's CreateLink method is called, the method should duplicate in a link-source object all of the content that your part originally wrote (or promised) to the clipboard or drag and drop object.
In your source part's CreateLink method, you can follow these general steps:
(If the link-source object does exist and does contain a complete set of promises or data, you could return the existing link-source object and take no further action. However, it may be simpler just to rewrite all part kinds than to test to see if you have a complete set.)
If your part's CreateLink method is called and the link-specification data provided describes an existing link source that you maintain, your part must ensure that all content kinds that you support are made available to the destination. If your part writes promises to the link source, you can ensure that all kinds are promised by replacing the current content in your link-source object. The procedure for replacing is similar to the regular updating procedure, except that you pass an existing update ID to the link-source object's Clear method, and you do not call the link-source object's ContentUpdated method. See "Updating a Link at the Source" for details.
When a source part updates its link-source object and calls the object's ContentUpdated method, the link-source object notifies its associated link objects of the change (except for link objects in other documents, which do not receive the notification until the source document is saved). The link destinations receive notification of the change in this manner:
If your part contains the destination of a link, you can update the destination in your part's LinkUpdated method. This is the interface to LinkUpdated:
void LinkUpdated(in ODLink updatedLink,
in ODUpdateID change);
|
Your part will receive such a call in response to the user's request for an update in the Link Destination Info dialog box.
You can perform automatic updates in your part's LinkUpdated method, and manual updates in response to a user command in the Link Destination Info dialog box.
It is not always necessary to update immediately, during execution of LinkUpdated or when manually instructed to do so by the user. For example, if the destination has scrolled offscreen but is still registered as a dependent of the source, updating does not need to occur until the destination scrolls back into view. Your part editor can, if desired, perform link updates as a background task.
You can take the steps shown here to read the contents of a link object when updating your link destinations.
Incorporate or embed the updated destination data into your part from the link object's contents property:
In any of these cases, the only differences from other data-transfer operations are that you call the Clone method of the link object's storage unit's draft, you specify a clone transaction of kODCloneFromLink, and you read from the link object's content storage unit.
You must discard any previously embedded parts and frames, replacing them with new ones cloned from the link. Also, you must connect the frames to your frame hierarchy, create facets for the currently visible ones, and change their link status by calling their ChangeLinkStatus method, passing the value kODInLinkDestination.
If your part maintains the destination of a link whose source has been transferred from one part to another, the new source part might not write its data using all of the same part kinds as the original source part. Your part, therefore, might not be able to obtain updates in the format that it expects. If that situation occurs, your part should read whatever part kind it can, or else break the link.
The part maintaining the source of a link can rewrite values into the link-source object as necessary to update the link. If your part is the source part, take the steps listed here to update the contents of your link source (or to write it for the first time). The "Automatic and Manual Propagation of Updates". describes how the user chooses whether updating should be automatic or manual. If the user has selected automatic (on-save) updating of the link source, perform this task whenver there is a change to the link-source content. If the user has selected manual updating of the link source, perform this task only on user command. The basic procedure for updating a link source is to first remove all content from the link source by calling its Clear method. By calling Clear, you ensure that all unneeded storage units are removed from the link, thereby saving space in your draft.
The Clear method deletes the contents property of the link-source storage unit and all its data. You need to add a contents property and values back into the storage unit after calling Clear, just as if creating the link source from scratch.
In summary, follow these steps:
Either way, specify a clone operation of kODCloneToLink. You are encouraged to write one or more promises instead of writing the actual data, to avoid placing unused content into the link source.
In general, it is not necessary and not always desirable to perform automatic updates to link-source objects immediately in response to every content change. When content is changing rapidly, such as during text entry, it is reasonable to wait for a pause before updating any affected links.
When your part writes itself to storage (see "Writing a Part to Storage"), or when it writes all or a portion of itself to a data-transfer object (see "Writing to a Data-Transfer Object"), it writes any linked data, whether source or destination. However, it must write information for reconstructing the link and link source objects involved.
There is no standard way to associate a link-source object or link object with a specific region of your content; how you create that association depends on the nature of your content. However, for all links your Externalize method and your methods that write to data-transfer objects need to write persistent references to the objects themselves, plus additional information. You should write the information in a format that is standard to your part kind; that way, any part editor that reads your part kind can reconstruct links from the stored data.
For the source of a link, you need to include, in addition to a persistent reference to the storage unit of the ODLinkSource object, the update ID associated with the linked content.
For the destination of a link, you need to include a persistent reference to the storage unit of the ODLink object, plus the information in the fields of the ODLinkInfo structure: the part kind, creation time, modification time, update ID, and auto-update setting of the linked data.
Your part may also store extra information for convenience. For example, because your part needs to be able to draw a border around linked data, it may store link-border shapes in a private structure.
If your part writes a single embedded frame (without surrounding intrinsic content) to the clipboard or drag-and-drop object, and if that frame is a link source or link destination, clone the link or link source object into the data-transfer object's draft and add a property with the name kODPropProxyContents to the clipboard or drag and drop storage unit. In that property write a value that references the link or link source object, as well as the link info fields and other necessary information. Any destination part that understands the proxy format can then recover the link.
If you write linked content to a data-transfer object and the destination part does not support linking, the content may be transferred but the links will not be.
When your part reads itself into memory, it may need to read in link-source objects and link objects as well. Likewise, when your part incorporates data that the user has pasted or dropped, your part may need to modify link sources or link destinations contained in that data.
Special care is necessary because OpenDoc can eliminate links during data transfer (see,for example, Table 10). Therefore, you must perform the following two tasks when reading in data that includes links:
Here are the steps you can take to handle linked data when reading your part (in InitPartFromStorage). The general procedure for reading a part is described in "The InitPartFromStorage Method".
Here are the steps you can take to handle linked data when reading (cloning) from the clipboard or drag and drop object. The overall procedure for reading from a data-transfer object is described in "Incorporating Intrinsic Content".
If IsValidID returns true, call your draft's AcquireLinkSource or AcquireLink method to read in the object. If IsValidID returns false, the link-source object or link object no longer exists and was not cloned.
If you have incorporated an existing link source into your part, you may not be able to write all the data types (part kinds) to the link source object that its previous owner did. That is not an error; simply write the part kinds that you support.
Users need to be able to navigate from the destination of a link to the source content. When the user selects the Show Link Source button in the Link Destination Info dialog box the destination part calls the ShowSourceContent method of the link object. OpenDoc, in turn, calls the source part's RevealLink method. This is its interface:
void RevealLink(in ODLinkSource linkSource); |
If your part contains the source of a link, your RevealLink method should display the part content that corresponds to the link source, following these general steps:
If your part is the part that needs to reveal an embedded frame containing a link source, you receive a call to your RevealFrame method. This is its interface:
ODBoolean RevealFrame (in ODFrame embeddedFrame,
in ODShape revealShape);
|
Scroll your content, if necessary, to reveal the portion of the specified embedded frame containing the specified shape. If the embedded frame is not currently visible because your containing part has scrolled your display frame out of view, call your containing part's RevealFrame method, passing it your own display frame and an appropriate shape (such as the shape of the embedded frame to be revealed).
Because OpenDoc links are unidirectional from source to destination, you should restrict the editing that a user can perform within the destination of a link. Basically, changing of content in a link destination is not allowed.
It is the responsibility of the destination part to block attempts to edit its link destinations. However, the part that initially receives an editing event may be a frame embedded within, perhaps deeply embedded within, the destination part. If your part's display frame has the status kODInLinkDestination and the user attempts to edit content within it, your part should call the EditInLink method of your frame. OpenDoc in turn calls the EditInLinkAttempted method of the part that maintains the link destination that includes your frame. This is the interface to EditInLinkAttempted:
ODBoolean EditInLinkAttempted (in ODFrame frame); |
The part that maintains the link destination should, in its EditInLinkAttempted method, take steps similar to these:
If EditInLinkAttempted returns true, then EditInLink returns true to your part (the part in whose display frame the edit attempt occurred). If the user has broken the link, your part's display frame now has a different link status and you can therefore allow editing of your content.
If EditInLinkAttempted returns false, then EditInLink returns false and OpenDoc cannot find the part that maintains the link destination or it cannot navigate to the link source. Your part should then put up its own simple alert box informing the user that editing in a link destination is not allowed.
If the user selects more than one link destination in your part and then attempts to edit the data, your part cannot even call EditInLink. It should then disallow editing and display a dialog box, suggesting that the user select a single destination.
Users can delete links in several ways. When you delete or cut content that includes a link source, or when you break a link at its source, your part relinquishes ownership of the link source object, as noted in Table 10. You should:
It is not necessary at this point to update the link source to delete its contents. If the user subsequently undoes the action, you can reverse the steps listed in the previous paragraph. You must be sure to call the link source object's SetSourcePart method once again to reestablish your part as the link's source.
When you delete or cut content that includes a link destination, or when you break a link at its destination, you should:
Reversing these actions undoes the break or cut. Your part should hold the references to a cut or broken link source or link until your DisposeActionState method is called, at which time you can release the link or link-source object.
This section summarizes the semantics of data transfer involving link objects and link-source objects. This discussion is for informational purposes only; if you follow the procedures presented earlier in this chapter, the correct semantics will always occur.
During some data-transfer operations, OpenDoc may delete or redirect link or link-source objects. Other operations are permitted by OpenDoc but should not be supported by your part. This section lists the basic data-transfer operations, in terms of:
OpenDoc enforces the behaviors listed in Table 10
when existing links or link sources and their associated intrinsic
content are transferred by drag and drop or with the clipboard,
according to the specified kind of cloning operation.
Table 10. Behavior of Existing Links During Data Transfer
| Operation | Object | Behavior |
|---|---|---|
| Copy (Drag-copy, or Copy followed by Paste) | Link source | Data is transferred; link source is not. |
| Link destination | In same document: Data is copied; link destination is copied also.
Across documents: Data is copied; link destination is not copied | |
| Source and destination of same link | Data is copied; link source and destination are both copied (but any uncopied destinations of the original source remain linked to the original source) | |
| Move (Drag-move, or Cut followed by Paste) | Link source | In same document: Data is transferred; link source is transferred also
Across documents: Data is transferred; link source is deleted (destinations within original document become unlinked) |
| Link destination | In same document: Data is transferred; link destination is transferred also
Across documents: Data is transferred; link destination is deleted | |
| Source and destination of same link | In same document: Data is transferred;
link source and destination are both transferred
Across documents: Data is transferred; any unmoved destinations of the link source become unlinked. |
When pasting or accepting a drop into your part, you can incorporate or embed data that includes existing link sources or destinations and at the same time attempt to make the data a link destination. In that situation, OpenDoc transfers that data and creates a link destination, but does not maintain any link sources or destinations that were included in the transferred data.
You can create links within links; OpenDoc does not prevent you from creating or pasting the source or destination of one link within the source or destination of another link. However, only some configurations make sense, as shown in Table 11.
You can use your display frame's link status (see
"Frame Link Status"), as well as private link-status information
about your own intrinsic content, to decide whether to allow the
creation of a link source or destination in any given situation.
In general, you cannot edit a link destination.
Table 11. Creating Links within Links
| To create a new... | Within an existing... | Recommendation |
|---|---|---|
| Link source | Link source | Okay, result is two separate link sources with partially or completely overlapping content. |
| Link source | Link destination | No, when the destination updates, it is generally impossible to know which changes should become part of the updated source. |
| Link destination | Link source | Okay, updates to the destination simply become part of the source. |
| Link destination | Link destination | No, updates to either link destination will overwrite the other. |