The clipboard commands Cut, Copy, and Paste constitute a common mechanism for transferring data within and across conventional documents, even documents of different data formats. For OpenDoc documents, these commands perform the same tasks, but with added capabilities:
Similar to data in a conventional clipboard, if your part editor stores multiple formats on the clipboard, including standard formats, the user has a greater chance of incorporating, rather than embedding, the data into more kinds of parts.
These concepts are some basic clipboard operations common to reading and writing. These concepts include acquiring the clipboard focus, using the clipboard update ID, and special considerations related to updating the clipboard and cutting data from your part.
Enabling the Cut and Paste menu items
OpenDoc does not permit changes to your draft (and therefore your part's content) if the draft permissions are read-only. You should check your draft permissions (see "Drafts") before enabling the Cut, Paste, or Paste As items in the Edit menu and before allowing the user to perform a cut or paste operation using keyboard equivalents.
The CanEmbed method can help parts determine whether or not they should enable the Paste menu items. The CanEmbed method queries the registration manager for a part editor capable of handling the content of the clipboard storage unit. It is intended for use by the container parts.
To be thread-safe, you must always acquire the clipboard focus before writing or reading clipboard data. As long as you hold the clipboard focus, no other part can access or modify the data.
Typically, your part needs to inspect the contents of the clipboard before deciding whether to enable Edit menu items, so your AdjustMenus method can include a call to the arbitrator's RequestFocus method to acquire the clipboard focus.
After acquiring the clipboard focus, you can access the clipboard when responding to a menu command (or its keyboard equivalent) with your HandleEvent method by calling the session object's GetClipboard method. You should then unilaterally relinquish the clipboard focus in your HandleEvent method, after having handled the clipboard command. (Your HandleEvent method is always called after AdjustMenus is called, even if the user does not choose a menu command.)
These are the steps you take to acquire the clipboard focus and prepare to write to it or read from it:
You relinquish the Clipboard focus by calling the arbitrator's RelinquishFocus method.
Whenever you copy data to the clipboard, you should get and save the clipboard's current update ID, a number used to identify this particular instance of clipboard contents. You typically obtain the update ID in this situation by calling the clipboard's ActionDone method. In other situations, you may need to inspect the clipboard's current update ID; you can do so by calling the clipboard's GetUpdateID method.
If a link specification that you have written to the clipboard becomes invalid because of changes to your content that was copied to the clipboard, you must remove the link specification from the clipboard, as described in "Removing a Link Specification from the Clipboard". You can examine the clipboard's current update ID at any time and compare it with your saved update ID; if they are identical, the clipboard has not changed.
If your part copies some of its content to the clipboard and the user then modifies the equivalent content in your part (without copying anything else to the clipboard), the clipboard data no longer exactly matches the source data in your part. The potential link represented by the link specification you wrote in the clipboard therefore no longer reflects the content at the source of the link. If your source content has changed to the extent that creating a link is no longer feasible, your part must remove the link specification.
By saving the update ID of the clipboard whenever you copy data to it, you can check that ID against the current update ID of the clipboard whenever your source data changes to the extent that creating a link to the previous data is impossible. If the IDs match, the clipboard still contains the data that you placed in it, and you should remove the link specification.
You can follow these steps to remove a link specification:
If your part supports cutting, copying, or pasting, it must also support undoing those operations. Data transfer between parts is undoable only if both parts have undo support. Undo support in general is described in "Undo".
Whenever your part performs a cut, copy, or paste operation, it must call the clipboard's ActionDone method, to notify the clipboard of the kind of cloning transaction that took place. ActionDone returns a clipboard ID that identifies the current clipboard contents. Save that update ID.
When your part cuts an object to the clipboard, it should remove the object from its content data structures. However, your part should not release the object, but instead save a reference to the object in an undo action. (For a cut embedded frame, you also set its in-limbo flag to true, as shown in Table 5. Then, if the user chooses the Undo command and your part's UndoAction method is called, your part should:
Calling ActionDone, ActionUndone, and ActionRedone notifies the clipboard whether it is involved in a cut, a copy, or the restoration of a cut or a copy; the clipboard's internal handling of its objects differs in each case.
If and when your part's DisposeActionState method is called, you can at that point release (not remove from your draft) the object referenced in your undo action. (For an embedded frame, you either release or remove it, as shown in Table 5.)
To undo a cut, copy, or paste operation requires the restoration of the previous state of the document involved, but it does not require the restoration of the previous state of the clipboard. Therefore, if you redo a paste operation that has been undone, you cannot assume that the clipboard once again contains the original data that had been pasted. You must implement the redo from your own data. For this reason, you should retain a copy of pasted data in a private cache.
You write data to the clipboard as a result of the user selecting the Cut command or the Copy command from the Edit menu (or their keyboard equivalents). These are the basic steps to take:
In either case, when you call the BeginClone method, specify either kODCloneCopy or kODCloneCut, depending on whether you are copying or cutting the data to the clipboard.
You read data from the clipboard as a result of the user selecting the Paste command or the Paste As command from the Edit menu. These are the basic steps to take:
In either case, when you call the BeginClone method, specify kODClonePaste.