Apple, the Apple logo, and Macintosh are registered trademarks of Apple Computer, Inc.
Mac and OpenDoc are trademarks of Apple Computer, Inc.
About Clipboard Recipes
This document describes the basic techniques for reading and writing the Clipboard. It assumes familarity with the document “Basic Data Interchange”, and references coding examples there. For further details on the Clipboard operations involving embedded frames, see the Layout recipes. For more information on Clipboard operations involving links, including the posting of link specifications and incorporation of linked content, see the Linking recipes.
For a description of individual methods used in the recipes, refer to the Class Documentation for the appropriate class.
About The Coding Examples
This document contains a number of coding examples in addition to descriptive text. The coding examples cover:
MyWriteToClipboard -- Writing intrinsic content to the clipboard.
MyCloneEmbeddedFrameToClipboard -- Writing a single embedded frame to the clipboard.
MyIncorporateFromClipboard -- Incorporating content from the clipboard.
MyEmbedFromClipboard -- Embedding content from the clipboard.
For simplicity, the coding examples use ODByteArrays to represent the content to be read or written. If your part does not maintain its content as an ODByteArray, you can either copy it into an ODByteArray, or, more likely, write data out or read data in in chunks using the StorageUnitSetValue or StorageUnitGetValue utility functions.
The examples use exception handling in the form of TRY…CATCH_ALL…ENDTRY blocks to catch exceptions, and assumes that errors returned by SOM methods are automatically thrown upon return.
WARNING: CODE APPEARING IN THESE RECIPES HAS NOT BEEN TESTED, AND MAY CONTAIN ERRORS.
Summary of changes from the DR3 Recipes
• Information common to the Clipboard, Drag and Drop, and Linking have been moved into the recipe document “Data Interchange Basics.”
• Added comment that parts should read from or write to the clipboard synchronously, rather than spawning a thread to complete the operation. See the section “When Parts May Access the Clipboard”.
• Parts must notify the clipboard when a Cut, Copy, or Paste is done, undone or redone. New methods ActionDone, ActionUndone, and ActionRedone have been added to ODClipboard. See the section “Undoing Clipboard Operations”.
• In "Relinquishing the Clipboard Focus", an erroneous reference to the non-existent part method RelinquishFocus was removed.
Summary of changes from the DR2 Recipes
The differences between these recipes and those that accompanied DR2 are summarized here.
• Important information was added to “Undoing Clipboard Operations”:
- the effect of undo on the clipboard content was clarified.
- as a temporary work around, parts should clear the clipboard after undoing a cut.
• Recipes were updated to conform to API changes in DR3:
- Calls to BeginClone include the destFrame argument.
- References to XXXChanged methods changed to XXXXUpdated as appropriate.
- ODChangeID replaced by ODUpdateID.
- GetChangeID has been renamed to GetUpdateID, and it returns an ODUpdateID value.
- GetXXXX has been changed to AcquireXXXX as necessary.
• A discussion of the ODPasteAsMergeSetting parameter to ShowPasteAsDialog has been added.
• Parts are reminded that the Clipboard should only be accessed in the foreground process.
• The kODPropFrameShape property has been changed to kODPropSuggestedFrameShape, and some elaboration on the property has been added.
• The recipe for copying content to the clipboard was broken into two simpler recipes, one a basic recipe for writing to the content storage unit of a Data Transfer object (clipboard, drag and drop, or link source).
Summary of changes from the November 1994 (DR1) Recipes
The differences between the DR2 recipes and those that accompanied DR1 are summarized here.
• Added the recipe for embedding a part via the Paste As dialog.
• Added recipe for determining if a draft can be modified.
• Parts must write a kODPropName property to the clipboard (or drag-and-drop storage unit) whenever they write content. See the recipe "Putting intrinsic content on the clipboard" for details.
• Parts may now assume that a call to their AdjustMenus method will be followed by a call to their HandleEvent method. This simplifies the recipes for acquiring and relinquishing the clipboard focus. Parts can request the focus in AdjustMenus, and relinquish the focus in HandleEvent.
• A brief section for container applications describes when the clipboard object's ExportClipboard and DraftClosing methods should be called. Parts do not call these methods!
• The section “Cleanup in ReleaseAll” has been changed. Parts no longer need to remove their link spec from the Clipboard in their ReleaseAll method, nor do they need to initiate fulfilling promises. This is now handled automatically by the Clipboard when the draft is closed.
• Parts that support Cut & Paste, or Drag and Drop, must support undo of those operations. See the section “Undoing Clipboard Operations.”
Summary of changes from a6 Recipes
The differences between the DR1 recipes and those that accompanied a6 are summarized here.
• Conversion to SOM.
• The Lock() and Unlock() methods have been removed from the clipboard. Instead, parts should use the clipboard focus.
• Clipboard key parameters have been removed from class methods.
• The recipe for copying a single embedded frame has been modified to allow the embedded part to promise its content. This requires a modification to the embedded part's CloneInto() method. The a6 recipe for copying a single embedded frame will still work, however.
• The recipe for cut-paste (and drag-move) have changed to allow objects to be reused if the move is within the same draft.
When a part receives a drop or pastes, the part should use the display frame provided if it chooses to embed the content. The receiving part may create a new display frame instead, but if the display frame was moved its more efficient to use the provided frame.
After a cut, or after a drop of moved content, the source part must release moved objects carefully. As before, the source part needs to delete any facets displaying moved embedded frames. If the operation was a drag, the source part must take into account that a moved frame may now be embedded in another part, and may have new facets in its new containing frame. The source part cannot use the moved frame's facet iterator. It must instead use the containing facet's iterator to identify the facets to be deleted. The a6 recipes did not discuss this detail, but the frame's facet iterator was used in the engineering Draw part.
• kODPropContentFrame has been added, and kODPropContentIsFrame has been removed.
• The recipe for incorporating content from the clipboard has been changed to have the receiving part read values from the root storage unit on the clipboard, rather than cloning the root first.
• The recipe for putting content on the clipboard now recommends performing a BeginClone-EndClone transaction, even if cloning is not performed because content is promised. By performing a clone transaction, parts inform OpenDoc of the semantics of the operation, so that should cloning occur later during the fulfilling of promises, the correct behavior will result.
Header File
Parts that access the clipboard need to include the clipboard header file:
#ifndef SOM_ODClipboard_xh
#include <Clipbd.xh>
#endif
When Parts May Access the Clipboard
Parts should access the clipboard only when two conditions are true. First, the part must be running in the frontmost process. The Clipboard is only defined for the frontmost process; any attempt to access it in a background process is meaningless (the clipboard method Clear now returns error kODErrBackgroundClipboardClear if called when the process is in the background). Second, the part must own the clipboard focus.
In addition, note that if a part's draft is read only, it should disable Clipboard operations that would change the draft, such as Cut, Paste, and Paste As.
Except for the special case of AdjustMenus, described below, parts should complete their access to the clipboard before returning from the method that initiated the access. For example, parts should modify the clipboard within their HandleEvent method, and relinquish the clipboard focus before returning from HandleEvent. Parts should not spawn a thread that copies data to the clipboard, all the while holding the clipboard focus. Parts can minimize the amount of data transferred on a Cut or Copy by writing promises to the clipboard.
Determining that a Draft Can Be Modified
If a part calls an OpenDoc method that modifies a draft, and the draft's permissions do not allow modifications, the OpenDoc method will return an error. Parts can determine if a draft can be modified by testing the draft permissions:
Parts should check draft permissions before attempting an operation that modifies a draft. For example, a part should not enable the Cut, Paste, or Paste As menu items if the draft cannot be modified.
The Clipboard Focus
To be thread safe, parts should acquire the clipboard focus prior to accessing the clipboard. Since parts usually need to inspect the clipboard to enable items on the Edit menu, they should call Arbitrator::RequestFocus from AdjustMenus to request the clipboard focus. If granted, a part can enable the Cut, Copy, Paste, and Paste As items as appropriate. A part can assume that a call to AdjustMenus will be followed by a call to HandleEvent; most parts should request the clipboard focus in AdjustMenus and relinquish the focus in HandleEvent.
Note: Your editor should not call ShowPartFrameInfo to display info on its own part. The user may pick another editor for that part, so your display frames may have been closed before ShowPartFrameInfo returns. In particular, the display frame parameter to HandleEvent may not be valid after your part calls ShowPartFrameInfo. The Part Info menu item applies to the current selection, so your part shouldn't attempt to do this if it sticks to the guidelines.
Parts may retain the clipboard focus while active, but must be prepared to relinquish the clipboard focus to allow other parts to inspect the clipboard. Parts must also relinquish the clipboard focus in their DeactivateFrame method if the deactivated frame owns the focus.
Relinquishing the Clipboard Focus
If your part retains the clipboard focus while active, it must be prepared to relinquish the clipboard focus in BeginRelinquishFocus/CommitRelinquishFocus to allow other parts to inspect the clipboard. Parts must also relinquish the clipboard focus in their DeactivateFrame method if the deactivated frame owns the focus.
// Insert in your part's DeactivateFrame method (only necessary if
Whenever a part puts data on the clipboard, even if object cloning is not performed, it should do so within a BeginClone-EndClone transaction (using the clone kind kODCloneCut or kODCloneCopy, as described in the Data Interchange Basics document). Using a clone transaction helps OpenDoc ensure that unfulfilled promises are resolved when a draft is closed.
Note that the first paste following a cut is always a move in OpenDoc. There is no way for the part performing a paste to force pasting a copy of the data. This should not matter to your part; the paste recipes work whether the content is being moved or copied into your part. However, the behavior of links and embedded content will be different when moved versus copied.
Clipboard Update IDs
The update ID returned by the ActionDone and GetUpdateID methods of the clipboard object identifies a particular clipboard generation, not a particular change. When your part pastes data from the clipboard, your part must remember the clipboard update ID in case the operation is later undone, but your part should generate a new update ID (using the UniqueUpdateID method of the session object) to associated with the pasted content. If the user pastes the contents of the clipboard twice, the clipboard’s update ID will be the same both times. Each paste is a separate change, however, with which your part must associated different update IDs. See the Linking Recipes for more information on update IDs.
Undoing Clipboard Operations
Parts that support Cut, Paste, Drag or Drop must support undoing and redoing those operations. If the user moves frames, links, or other objects from one part to another, via Cut & Paste or Drag and Drop, objects may be reused at the destination. If the clipboard or Drag and Drop operation is undone, the objects must be reinstated at the source. This can only happen if the the part initiating the cut or drag and the part performing the paste or drop both support undo.
Your part is responsible for notifying the clipboard whenever a Cut, Copy, or Paste operation is done, undone, or redone. (Your part should not perform this notification when pasting a link from the clipboard.) When yor part performs a Cut, Copy, or Paste, call the ActionDone method of the clipboard. This method takes as its argument the cloneKind your part used to access the clipboard (either kODCloneCut, kODCloneCopy, or kODClonePaste). When your part undoes a Cut, Copy, or Paste, call the ActionUndone method of the clipboard object, specifying the update ID returned by the clipboard's ActionDone method at the time of the original action, and the clone kind used at the original access. When your part redoes a Cut, Copy, or Paste, call the ActionRedone method of the clipboard object instead.
When a cut or copy operation is undone, it is not necessary to restore the clipboard to its previous contents. Because of this, code implementing the redo of a paste operation cannot assume the clipboard content is the same as it was when the original paste was performed. Redo of a paste operation must be implemented by restoring content from a private cache.
When a part cuts an object to the clipboard, a reference to the object should be saved in an undo action. If the part’s UndoAction method is called, it must (1) reinstate the object into its content model from its undo information, and (2) notify the clipboard that the cut was undone (see below). Similarly, if the part’s RedoAction method is called, it should (1) remove the object from its content model, and (2) notify the clipboard that the cut was redone. When the part’s DisposeActionState method is called, the object reference in the action data should be released. See the section below for special instructions on handling embedded frames that have been cut or pasted.
Undoing the Cut or Paste of Embedded Frames
The part performing a cut or paste of one or more embedded frames is responsible for handling the in-limbo status of the frame correctly. If the user undoes the cut of an embedded frame, your part must set the in-limbo flag to kODFalse in its UndoAction method. If the user redoes the cut of an embedded frame, your part must set the in-limbo flag to kODTrue. When your DisposeActionState method is called to commit a cut, your part must examine the state of the in-limbo flag. If the IsInLimbo returns kODFalse, your part must release the frame reference it holds; if IsInLimbo returns kODTrue, your part must remove the frame by calling the Remove method of the frame.
Similarly, if the user undoes the paste of an embedded frame, your part's UndoAction method must restore the in-limbo flag to the value it had before the paste was performed. If the user redoes the paste of an embedded frame, your part must set the in-limbo flag to kODFalse. When your DisposeActionState method is called to commit a paste, your part must examine the state of the in-limbo flag. If the IsInLimbo returns kODFalse, your part must release the frame reference it holds. If IsInLimbo returns kODTrue, your part's action depends on the in-limbo status of the frame at the time the paste was performed. If the frame was in-limbo, your part must release the frame reference it holds (some other part will remove it.) If the frame was not in-limbo, your part must remove the frame by calling the Remove method of the frame.
Cleanup in ReleaseAll
When a part's ReleaseAll method is called, the part should check to see if it has a promise or a link specification on the clipboard. If so, it needs to fulfill the promise or remove the link specification.
Writing Intrinsic Content to the Clipboard
MyWriteToClipboard demonstrates how a part might implement a routine to copy intrinsic content to the clipboard. It uses the MyWriteToContentSU method, described in the Data Interchange Basics recipe, to write promises for the data.
MyWriteToClipboard should only be called when this part holds the clipboard focus and is in the foreground, as described earlier.
The promiseData parameter is whatever information the part needs to identify the promised content when its FulfillPromise method is called.
The contentShape parameter will be written as the suggested frame shape annotation. This property will be used as the frame shape should content be embedded from the clipboard.
The partName parameter will be written as the part name annotation. If your part associates a name with the content written, you may want the part created should the content be embedded at the destination to bear this name. If not, the partName may be null, and no part name annotation will be created.
The optional linkSpecData parameter will be written into a link specification if the operation is a copy.
The cloneKind parameter is either kODCloneCut or kODCloneCopy.
This method returns the update ID of this clipboard operation. This ID can be saved and later compared to the current clipboard update ID to determine if the contents of the clipboard have been replaced.
If the operation is a cut, after putting content on the clipboard, the intrinsic content should be removed. When an embedded frame is cut, the part must delete any facets displaying that frame. Call the containing facet's RemoveFacet method to remove a facet, then delete the facet object. The cut frame’s containing frame should be set to kODNULL to remove it from the layout hierarchy, but not removed from the part. A reference to the cut frame should be placed in undo action data. Other frames displaying the part are not affected.
When content is cut, any objects cloned to the clipboard may be reused if pasted back into the same draft. This includes embedded frames, link and link source objects that a part typically references directly. If the cut content references any other persistent objects, those references should retained in undo data so the operation can be undone. When the references are no longer needed to support undo, the objects should be released. See the section “Undoing Clipboard Operations” for more information.
Each embedded frame cut along with intrinsic content must have its in-limbo flag set to kODTrue.
cutEmbeddedFrame->SetInLimbo(ev, kODTrue);
Copying a Single Embedded Frame to the Clipboard.
Your part should follow this recipe to put a single embedded frame on the clipboard. The promiseProxyData parameter. Note the similarity to MyWriteToClipboard; only the line calling MyCloneEmbeddedFrameToContentSU is different!
The embeddedFrame parameter is the frame being cut or copied.
The optional promiseProxyData is proxy content that this part associates with the embedded frame and will be written as proxy content.
The optional linkSpecData parameter will be written into a link specification if the operation is a copy.
The cloneKind parameter is either kODCloneCut or kODCloneCopy.
This method returns the update ID of this clipboard operation.
Incorporating from the clipboard is demonstrated by this code that gets the clipboard content storage unit and calls the MyReadFromContentSU routine described in the Data Interchange Basics document. In this simple example, the incorporated content is inserted where there are no source links maintained by this part. Because Paste must be an undoable operation, action data is added to the undo history if incorporation is successful.
The targetFrame argument identifies the frame being incorporated into and is passed to MyReadFromContentSU.
This method returns the update ID of this clipboard operation. (This is not the same as the update ID associated with the content change to this part!)
// Return the update id associated with this clipboard operation.
return clipboardUpdateID;
}
Embedding a Part from the Clipboard
Embedding from the clipboard is demonstrated using the routine MyEmbedContentSU, which performs the actual work and is described in the Data Interchange Basics document.
The targetFrame argument identifies the frame being incorporated into and is passed to MyEmbedContentSU.
This method returns the update ID of this clipboard operation.
// Return the update id associated with this clipboard operation.
return clipboard->ActionDone(ev, kODClonePaste);
}
Container Application Requirements
Container applications need to call clipboard object methods to ensure synchronization with the host platform clipboard mechanism, and to inform the clipboard of draft closings so the correct move or copy semantics can be enforced. Parts do not call these methods.
The ExportClipboard method must be called by the Container Application whenever the current content of the OpenDoc clipboard must be transferred to the platform clipboard. On the Macintosh, this includes when the application is suspended or quit.
The DraftSaved method must be called to notify the clipboard object that a document draft has been saved.
The DraftClosing method must be called to notify the clipboard object that a document draft is closing. This call must be made before the draft object is closed.
