Programming Reference: ODClipboard

# Programming Reference

## ODClipboard

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:

- ActionDone
- ActionRedone
- ActionUndone
- CanEmbed
- Clear
- DraftClosing
- DraftSaved
- ExportClipboard
- GetContentStorageUnit
- GetUpdateID
- SetPlatformClipboard
- ShowPasteAsDialog (OS/2, Windows)

Overridden Methods | There are no methods overridden by the ODClipboard class.

### ActionDone

This method notifies this clipboard that a cut, copy, or paste action was done.

Signature

    ODUpdateID ActionDone (ODCloneKind cloneKind)

Parameters

cloneKind (ODCloneKind) - input

  The type of clone operation that copied data to or from the clipboard. This parameter can be set to one of the following values:

  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

rv (ODUpdateID) - returns

  The update ID identifying the version of the clipboard content involved with this operation.

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

- ODClipboard::ActionRedone
- ODClipboard::ActionUndone
- ODPart::RedoAction
- ODPart::UndoAction
- ODUndo class

### ActionRedone

This method notifies this clipboard that a cut, copy, or paste action was redone.

Signature

    void ActionRedone (ODUpdateID update,
                       ODCloneKind originalCloneKind)

Parameters

update (ODUpdateID) - input

  The update ID identifying the version of the clipboard content involved with this operation.

originalCloneKind (ODCloneKind) - input

  The type of clone operation that copied data to or from the clipboard. This parameter can be set to one of the following values:

  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

- ODClipboard::ActionDone
- ODClipboard::ActionUndone
- ODPart::RedoAction
- ODUndo class

### ActionUndone

This method notifies this clipboard that a cut, copy, or paste action was undone.

Signature

    void ActionUndone (ODUpdateID update,
                       ODCloneKind originalCloneKind)

Parameters

update (ODUpdateID) - input

  The update ID identifying the version of the clipboard content involved with this operation.

originalCloneKind (ODCloneKind) - input

  The type of clone operation that copied data to or from the clipboard. This parameter can be set to one of the following values:

  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

- ODClipboard::ActionDone
- ODClipboard::ActionRedone
- ODPart::UndoAction
- ODUndo class

### CanEmbed

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

rv (ODBoolean) - returns

  A flag indicating whether a part editor was found.

  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.

### Clear

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

- ODArbitrator::RequestFocus
- ODClipboard::GetContentStorageUnit

### DraftClosing

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

draft (ODDraft *) - input

  A reference to the draft to be closed or reverted.

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.

### DraftSaved

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

draft (ODDraft *) - input

  A reference to the draft that was saved.

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.

### ExportClipboard

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

- ODClipboard::SetPlatformClipboard

### GetContentStorageUnit

This method returns a reference to the storage unit containing this clipboard object's current content.

Signature

    ODStorageUnit *GetContentStorageUnit ()

Parameters

None.

Returns

rv (ODStorageUnit *) - returns

  A reference to the storage-unit object containing the content of the clipboard.

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

- ODClipboard::Clear
- ODClipboard::GetUpdateID

### GetUpdateID

This method returns the update ID identifying the current generation or version of this clipboard object.

Signature

    ODUpdateID GetUpdateID ()

Parameters

None.

Returns

rv (ODUpdateID) - returns

  The update ID of the current clipboard content.

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

- ODClipboard::ActionDone
- ODLink::GetUpdateID
- ODLinkSource::GetUpdateID

### SetPlatformClipboard

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

typeList (ODPlatformTypeList *) - input

  A reference to the list of platform-dependent types to be copied to the system clipboard.

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

- ODClipboard::ExportClipboard
- ODPart::AdjustMenus

### ShowPasteAsDialog (OS/2, Windows)

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

canPasteLink (ODBoolean) - input

  A flag indicating whether the destination part allows a link to be created. This parameter can be set to one of the following values:

  kODTrue | The destination part allows a link to be created.
  kODFalse | A link cannot be created.

mergeSetting (ODPasteAsMergeSetting) - input

  A flag indicating whether embedding and merging are supported. The value of this parameter determines which radio button in the At the Destination group box is initially selected and whether the other button is available. For a list of ODPasteAsMergeSetting options, see ODPasteAsMergeSetting.

facet (ODFacet *) - input

  A reference to the facet from which the Paste As dialog box is triggered.

viewType (ODTypeToken) - input

  A tokenized string representing the initial setting for the view type of the embedded part, if embedding is chosen.

  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

theResult (ODPasteAsResult *) - output

  A structure reflecting the user's selection in the Paste As dialog box.

Returns

rv (ODBoolean) - returns

  A flag indicating whether the user clicked the Paste button to leave the Paste As dialog box.

  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

- ODSession::Tokenize

[ Top | Previous | Next | Contents | Index | Documentation Homepage ]