clipboard-object

Arguments: clipboard-format

This generic function returns (or sets with setf) the value of the Windows clipboard for a specified format. The argument may be either :text, :rich-text, or :pixmap to indicate the format. On Windows, other custom locations can also be specified as clipbord-format values. See the Windows note below.

When using the setf, the value should match the specified format, where :text indicates a regular Lisp string, :rich-text indicates a regular Lisp string that happens to be in rich text format (such as can be retrieved by calling rich-edit-range on a rich-edit widget or rich-edit-pane), and :pixmap indicates a Common Graphics pixmap object. (Common Graphics uses the "device-independent bitmap" Windows clipboard format to pass pixmaps on the Windows clipboard to and from other applications.)

The setf of this function has an additional keyword parameter called empty-clipboard, which defaults to t. When true, this causes the clipboard to be completely cleared before placing the new value onto the clipboard. This ensures that no values of other data formats are left on the clipboard along with the new value. If it is desired to place data of multiple formats onto the clipboard, then specify this argument as nil when adding successive formats, as in:

(setf (clipboard-object :text :empty-clipboard nil) "foo")

Note that the setf of this function does not modify the Lisp clipboard stack. To modify both the Windows clipboard and the Lisp clipboard stack, use a function such as push-lisp-clipboard or copy-command rather than (setf clipboard-object).

The older functions clipboard-string and clipboard-pixmap are deprecated in favor of this newer single function.

See cg-clipboard.htm.

GTK Note

Only the :text format is supported for passing information on the system clipboard between Lisp and other applications. The :pixmap format may be supportable in the future, but the :rich-text format (or formated text in general) does not appear to be supportable. Arbitrary lisp objects may still be passed on the lisp clipboard within a lisp application by calling push-lisp-clipboard and pop-lisp-clipboard.

Windows note

It is possible to place text at alternate "locations" on the Windows system clipboard, by simply passing the clipboard-format argument as any symbol other than the standard :text, :rich-text, or :pixmap. This is probably useful only if you have multiple standalone Lisp applications, or multiple running instances of a single application, where they are all aware of the same location names. Then one instance could place text at various locations, and another instance could read the text at whichever locations it is interested in.

Here's an example, where typically one Lisp application instance would do the first pair of calls, and a second instance might do the second pair of calls, but it works in a single Lisp as well.

(setf (clipboard-object :text) "primary text")
RETURNS "primary text"

(setf (clipboard-object :place-two :empty-clipboard nil) "secondary")
RETURNS "secondary"

(clipboard-object :text)
RETURNS "primary text"

(clipboard-object :place-two)
RETURNS "secondary"

Copyright (c) 1998-2022, Franz Inc. Lafayette, CA., USA. All rights reserved.
This page has had moderate revisions compared to the 10.0 page.
Created 2019.8.20.