Class Definition File | Clipbd.idl |
Class C++ Binding | Clipbd.xh |
Class Hierarchy |
SOMObject
ODObject
ODBaseClipboard
ODClipboard
|
Description | An object of the ODClipboard class provides data-transfer services among OpenDoc documents and their parts and between OpenDoc and non-OpenDoc documents. On each platform, OpenDoc provides an implementation of the ODClipboard class that gives a common, platform-independent clipboard interface for all parts. Each such implementation of ODClipboard provides access to a platform-specific clipboard, the system clipboard, through OpenDoc storage units. This approach shields part editors from the underlying system clipboard mechanism and allows complex data transfers among different parts and documents, including linking. When a document is opened, the session object creates a single clipboard object. All parts of that document share the clipboard object; you can obtain a reference to it by calling the session object's GetClipboard method. You must not cache this object; instead, you must call the session object's GetClipboard method when you need the clipboard object. Parts typically invoke ODClipboard methods in response to Edit menu commands, such as Copy, Cut, Paste, and Paste As, and during certain linking and drag-and-drop operations. In addition to the traditional data-transfer features associated with these commands, OpenDoc's ability to clone objects allows a data-transfer operation to involve not only intrinsic content of the source part, but also the content of embedded parts, which may be of any part kind and embedded to any depth. The OpenDoc clipboard mechanism also allows more flexibility in how items are pasted. You should access the clipboard only when your part is running in the front-most process and your part owns clipboard focus. You can acquire the clipboard focus by calling the arbitrator object's RequestFocus method. Acquiring the clipboard focus ensures that no other part can access or modify the data while your transfers are taking place. An active part must, therefore, acquire the clipboard focus before enabling the appropriate commands in the Edit menu. The strategy is to acquire focus in your part's AdjustMenus method and to relinquish focus in your part's HandleEvent method. Once your part has the clipboard focus, you can write data to, or read data from, the clipboard. If you are writing data to the clipboard, you must first call the Clear method of the clipboard object. Data transfers requested by any part operate on the clipboard object's content storage unit. You obtain a reference to that storage unit by calling the clipboard's GetContentStorageUnit method. The content storage unit contains the data most recently cut or copied to the clipboard. You must not cache the storage unit; instead, you must call the GetContentStorageUnit method when you need to access the storage unit. To transfer persistent objects to or from the clipboard, you must clone them using the cloning methods of their draft object. Additional methods of ODClipboard transfer data between the system clipboard and the clipboard object's storage unit. For efficient transfer of large amounts of data to and from the clipboard, OpenDoc supports promises. The source part can delay a data transfer by writing a promise to the clipboard. If, and only if, a destination subsequently seeks to retrieve the data, the source part fulfills its promise by writing the data to the clipboard. This time-saving technique is transparent to the destination part. The GetUpdateID method of the clipboard object returns an update ID that uniquely identifies the current generation or version of the clipboard. You can save this update ID and use it to detect subsequent changes in the clipboard content. Parts that support cut and paste must support undo. If the user moves objects from one part to another and then undoes the move, the objects must be reinstated at the source. This can happen only if the part initiating the cut and the part performing the paste both support undo. Your part should notify the clipboard object when a cut, copy, or paste operation is done, redone, or undone by calling the clipboard object's ActionDone, ActionRedone, or ActionUndone method. For more information about cloning, promises, and using the clipboard object, see the chapter on data transfer in the OpenDoc Programming Guide. For more information on cloning methods, see the description of the classes ODDraft and ODPart. For information on undoing and redoing actions, see the chapter on windows and menus in the OpenDoc Programming Guide and the class description for ODUndo. For information on using a link specification to indicate that the source part can create a link, see the class description for ODLinkSpec. |
Methods | The methods defined by the ODClipboard class include: |
Overridden Methods | There are no methods overridden by the ODClipboard class. |
This method notifies this clipboard that a cut, copy, or paste action was done.
Signature
ODUpdateID ActionDone (ODCloneKind cloneKind) |
Parameters
kODCloneCopy | Copy into the content storage unit of the clipboard object or the drag-and-drop object. |
kODCloneCut | Cut into the content storage unit of the clipboard object or the drag-and-drop object. |
kODClonePaste | Paste from the content storage unit of the clipboard object or the drag-and-drop object. |
Returns
Remarks
Your part should call this method when it performs a cut, copy, or paste operation. You should cache the returned update ID in case you need to undo or redo the action.
Exception Handling
kODErrIllegalClipboardCloneKind | The specified clone kind was not kODCloneCopy, kODCloneCut, or kODClonePaste. |
Related Methods
This method notifies this clipboard that a cut, copy, or paste action was redone.
Signature
void ActionRedone (ODUpdateID update,
ODCloneKind originalCloneKind)
|
Parameters
kODCloneCopy | Copy into the content storage unit of the clipboard object or the drag-and-drop object. |
kODCloneCut | Cut into the content storage unit of the clipboard object or the drag-and-drop object. |
kODClonePaste | Paste from the content storage unit of the clipboard object or the drag-and-drop object. |
Returns
None.
Remarks
Your part should call this method when it redoes a cut, copy, or paste operation. The update ID should be the ID returned by the ActionDone method at the time your part originally performed the action. The clone kind should be the same clone kind as specified in that call to the ActionDone method.
Exception Handling
kODErrIllegalClipboardCloneKind | The specified clone kind was not kODCloneCopy, kODCloneCut, or kODClonePaste. |
Related Methods
This method notifies this clipboard that a cut, copy, or paste action was undone.
Signature
void ActionUndone (ODUpdateID update,
ODCloneKind originalCloneKind)
|
Parameters
kODCloneCopy | Copy into the content storage unit of the clipboard object or the drag-and-drop object. |
kODCloneCut | Cut into the content storage unit of the clipboard object or the drag-and-drop object. |
kODClonePaste | Paste from the content storage unit of the clipboard object or the drag-and-drop object. |
Returns
None.
Remarks
Your part should call this method when it undoes a cut, copy, or paste operation. The update ID should be the ID returned by the ActionDone method at the time your part originally performed the action. The clone kind should be the same clone kind as specified in that call to the ActionDone method.
Exception Handling
kODErrIllegalClipboardCloneKind | The specified clone kind was not kODCloneCopy, kODCloneCut, or kODClonePaste. |
Related Methods
This method queries the registration manager for a part editor that can handle the content of the clipboard storage unit.
Signature
ODBoolean CanEmbed () |
Parameters
None.
Returns
| kODTrue | A part editor was found. |
| kODFalse | No registered part editors can handle the clipboard content. |
Remarks
This method is called by container parts to determine whether to enable the Paste menu item.
This method removes all data stored in this clipboard object.
Signature
void Clear () |
Parameters
None.
Returns
None.
Remarks
For thread-safe operations, the active part must acquire the clipboard focus before invoking this method. This method also causes the system clipboard to be cleared, but at a time that is dependant on both the platform and the document shell.
The object calling this method must not be holding a storage-unit reference returned by a prior call to the GetContentStorageUnit method.
After this method executes successfully, the next call to the GetContentStorageUnit method returns a storage-unit object with no properties. On AIX, this storage unit may contain properties, because the Motif clipboard cannot be cleared.
Related Methods
This method is called by the document shell or a container application to notify this clipboard object that the specified draft is about to be closed or reverted.
Signature
void DraftClosing (ODDraft *draft) |
Parameters
Returns
None.
Remarks
The document shell or a container application calls this method when the specified draft is about to be closed or reverted. Parts must not call this method.
This method can be used to ensure the integrity of this clipboard object's reference to the destination draft object involved in paste operations. If the specified draft is closed or reverted, the clipboard's reference to the draft becomes invalid and must be deleted to avoid the possible corruption of destination draft objects.
This method is called by the document shell or a container application to notify this clipboard object that the specified draft has been saved.
Signature
void DraftSaved (ODDraft *draft) |
Parameters
Returns
None.
Remarks
The document shell calls this method after saving every draft. Parts must not call this method.
Any objects cut from the saved draft that are still on the clipboard must be treated as if they were copied if they are later pasted back into the saved draft.
This method is called by the document shell or container application to update the system clipboard if this clipboard object has been changed since the last update of the system clipboard.
Signature
void ExportClipboard () |
Parameters
None.
Returns
None.
Remarks
Parts must call this method to commit changes to the system clipboard.
Exception Handling
kODErrOutOfMemory | There is not enough memory to complete the operation. |
This method may also return platform-specific exceptions.
Related Methods
This method returns a reference to the storage unit containing this clipboard object's current content.
Signature
ODStorageUnit *GetContentStorageUnit () |
Parameters
None.
Returns
Remarks
You can read data from or write data to the returned storage unit. You must not cache the returned storage unit; instead, you must call this method when you need to access the content storage unit.
You must acquire the clipboard focus before calling this method and relinquish the focus after the data transfer. If you are writing data, you must also call the Clear method before calling this method.
The clipboard object handles the creation and destruction of its content storage unit, so you must neither dispose of nor release the returned storage unit.
Exception Handling
kODErrOutOfMemory | There is not enough memory to complete the operation. |
Related Methods
This method returns the update ID identifying the current generation or version of this clipboard object.
Signature
ODUpdateID GetUpdateID () |
Parameters
None.
Returns
Remarks
Your part may call this method to check whether another part has changed the clipboard. The returned update ID uniquely identifies the current generation or version of the clipboard. Update ID values have no significance other than in the context of testing them for equality. Also, the update ID value returned by this method is valid only during the current session.
It is possible, but dangerous, to call this method before your part has acquired the clipboard focus.
Important: Clipboard update IDs are used for a different purpose than link and link-source update IDs. You should never set the update ID of a link-source object to an update ID returned by this method.
Related Methods
This method copies any data of the specified types from this clipboard object to the system clipboard if this clipboard object has changed since the last update to the system clipboard.
Signature
void SetPlatformClipboard (ODPlatformTypeList *typeList) |
Parameters
Returns
None.
Remarks
You must call this method prior to invoking any platform-specific service that uses the system clipboard.
This method examines the value type of each value in the content property of this clipboard's storage unit. If the value type is in the specified platform type-list or if the typeList parameter is kODNULL, this method copies the data in that value to the system clipboard.
To keep system-clipboard behavior consistent, this method does not attempt translation to a specified type that is not present in this clipboard object.
Exception Handling
kODErrOutOfMemory | There is not enough memory to complete the operation. |
This method may also return platform-specific exceptions.
Related Methods
This method displays the Paste As dialog box and sets the appropriate dialog items according to the input parameters.
Signature
ODBoolean ShowpasteAs Dialog (ODBoolean canPasteLink,
ODPasteAsMargeSetting mergeSet
ODTypeToken viewType
|
Parameters
| kODTrue | The destination part allows a link to be created. |
| kODFalse | A link cannot be created. |
This parameter must be the tokenized form of one of the following frame view-ODType constants. You can call the session's Tokenize method to obtain a token corresponding to one of these constants.
| kODViewAsFrame | Framed view type. |
| kODViewAsLargeIcon | Large-icon (standard) view type |
| kODViewAsSmallIcon | Small-icon view type. |
| kODViewAsThumbNail | Thumbnail view type |
Returns
| kODTrue | The user clicked the Paste button. |
| kODFalse | The user canceled out of the dialog box. |
Remarks
You should call this method in your part's HandleEvent method to display the Paste As dialog box when the user selects Paste As from the Edit menu.
If the canPasteLink parameter is kODTrue, and if the content storage unit contains a link specification and the draft permissions allow writing, then the Paste with Link check box is checked.
If the user clicks the Paste button in the Paste As dialog box, this method returns kODTrue and sets the fields of the theResult output parameter to indicate the selections the user made. You must dispose of the non-null selectedKind, translateKind, and editor fields of the ODPasteAsResult structure when you are finished using them.
If the user cancels out of the dialog box, this method returns kODFalse, and you do not need to take any further action.
Exception Handling
| kODErrNullFacetInput | The facet parameter is null. |
| kODErrNullPasteAsResultInput | The theResult parameter is null. |
| kODErrOutOfMemory | There is not enough memory to complete the operation. |
Related Methods