copy-selection

Arguments: window-or-widget

Returns an object from the specified window or widget that is suitable for placing onto the clipboard, or nil if no suitable object is found. This function is called by copy-command, which does the actual placing of the object onto the clipboard. An application could call either function, or add methods to either in order to extend the clipboard functionality.

window-or-widget should be an instance of a basic-pane subclass or a dialog-item subclass.

If a copy was done, then a second value is returned that indicates the clipboard format that is appropriate for the copied object on the underlying platform's system-wide clipboard. This will be one of the keywords :text, :rich-text, or :pixmap. The Windows clipboard knows how to hold one value of each of its clipboard formats simultaneously.

The default method returns the object returned by calling selected-object, plus :text as the second value. The methods for bitmap-pane and drawable-pane return a pixmap that is created by calling get-pixmap on the window, plus :pixmap as the second value. The method for rich-edit-pane returns the selected text as a rich text string, plus :rich-text as the second value. The method for dialog-item simply calls copy-selection on the window of the dialog-item if the widget is currently on a parent window.

An anomaly: When called on a rich-edit-pane in Windows, it is copy-selection rather than copy-command that actually places the object onto the clipboard. This is due to a problem with mapping the Common Graphics behavior onto the Windows clipboard and rich-edit APIs. In this case, both the rich text string and the plain text string are placed onto the clipboard, with the rich text string being topmost on the lisp clipboard stack.

An application could add methods for additional widget or window classes if you would like to call copy-selection (or copy-command) on the selected widget or window without regard to its class, letting it handle the command if it knows how. To do this for a widget (rather than a window), you could specialize on the dialog-item subclass if you will only call copy-selection on the widget; if you might instead pass the widget's associated window, then you would need to specialize on the widget-window subclass. Doing so requires subclassing both the dialog-item class and the widget-window class, and associating the two subclasses together with a trivial widget-device method.

cut-selection does what this function does and also deletes the returned object from the window or widget. See also paste-selection.

Compatibility notes

In releases prior to 7.0, this function passed its action to the lowest selected descendent child window of the specified window, though some applications may not desire such automatic redirection. The functions focus-component, get-focus, or selected-window may be useful for finding a suitable widget or window to pass to this function. Earlier releases also returned the window where the copy was actually done as the first value, and the copied object as the second value.

See cg-clipboard.htm.

Copyright (c) 1998-2016, Franz Inc. Oakland, CA., USA. All rights reserved.
This page was not revised from the 8.1 page.
Created 2010.1.21.