Enabling clipboard operations
OLE containers often allow any embedded or linked OLE object to be copied to the system clipboard for pasting into another application. To support this activity, the OleClient class provides a special clipboard format rendering that manages the underlying OLE formats required to make this work.
This format is OLE object and its rendering is obtained from an OleClient through its instance method oleObjectDescriptor. This special OLE object clipboard rendering is copied to the clipboard using the standard Common Graphics clipboard operations on a CgDisplay object:
•clipboardStartCopy:clipLabel:itemIdReturn:
•clipboardCopy:itemId:formatName:buffer:privateId:
•clipboardEndCopy:itemId:
For more information, refer to the Common Graphics discussion in
Common Graphics.
As an example, consider the following callback method for the Copy menu item:
menuEditCopy
"Private - Process the Edit menu Copy item."
| widget display window itemIdHolder |
(widget := self shell focusWidget) isOleClient
ifFalse: [^self].
display := self shell display.
window := self shell window.
itemIdHolder := ReturnParameter new.
(display
clipboardStartCopy: window
clipLabel: self shell title
itemIdReturn: itemIdHolder) = ClipboardSuccess
ifFalse: [^false].
display
clipboardCopy: window
itemId: itemIdHolder value
formatName: 'Ole Object'
buffer: widget oleObjectDescriptor
privateId: 0.
^(display clipboardEndCopy: window itemId: itemIdHolder value) = ClipboardSuccess
This example first finds the widget that currently has focus in the shell's widget tree. It then queries that widget, using isOleClient, to determine whether it is an OleClient widget. If it is, the remainder of the method uses standard clipboard protocol on the shell's CgDisplay to copy the special OLE clipboard format rendering.
Conversely, performing a direct paste operation of an OLE object from the clipboard requires getting the OLE object format rendering from the clipboard and giving it to an OleClient widget to create and connect to the referenced OLE object.
The paste operation uses the standard CgDisplay protocols for retrieving format renderings from the clipboard:
•clipboardStartRetrieve:
•clipboardRetrieve:formatName:bufferReturn:privateIdReturn:
•clipboardEndRetrieve:
For example, the Paste menu item of the Edit menu might look like:
menuEditPaste
"Private - Process the Edit menu Paste item."
| display window bufferHolder result |
display := self shell display.
window := self shell window.
display clipboardStartRetrieve: window.
result := (display
clipboardRetrieve: window
formatName: 'Ole Object'
bufferReturn: (bufferHolder := ReturnParameter new)
privateIdReturn: ReturnParameter null) == ClipboardSuccess.
display clipboardEndRetrieve: window.
result ifFalse: [^self].
^self paste: bufferHolder value
Here, the value returned from the bufferHolder (a ReturnParameter) is an instance of OleObjectDescriptor that contains all the data required by an OleClient to recreate the OLE object that was copied to the clipboard. The paste: method is similar to menuEditInsertObject: and menuEditPasteSpecial: described above, except that instead of invoking the dialogs to create and connect the OLE object, the OleClient is asked to do it from the OleObjectDescriptor:
paste: oleObjectDescriptor
"Private - Paste the OLE object into the receiver."
| client |
oleObjectDescriptor == nil
ifTrue: [^self]. "Nothing to paste"
client := composite
createOleClient: counter printString
argBlock: [:w |
w
x: 50;
y: 50;
width: 200;
height: 200].
client
mappedWhenManaged: false;
manageChild;
pasteFromOleObjectDescriptor: oleObjectDescriptor;
mappedWhenManaged: true
Here, the OleClient does all the work of creating and connecting the OLE object through its instance method pasteFromOleObjectDescriptor:.
Note:
The OLE object format and its rendering are also used for drag and drop operations on OleClient widgets. The OleClient method oleObjectDescriptor is used to obtain the source OLE object format rendering for a drag operation, and the OleClient method pasteFromOleObjectDescriptor: is used to create and connect an OLE object described in a OLE object rendering obtained from a drop operation.
The isConnected instance method is used to determine whether an OleClient is connected to its embedded or linked OLE object.