paste-selection

Arguments: window-or-widget object

Adds object to the current content of window-or-widget if it knows how to do so, generally at the "current position" in the window or widget. Returns object if a paste was done, and nil otherwise. This function is called by paste-command, which grabs an object off of the clipboard to pass to this function. An application could call either function, or add methods to either in order to extend the clipboard functionality. An application might call this function with a value that was retrieved by calling copy-selection or cut-selection.

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

The default method does nothing (and therefore returns nil). The methods for editable-text-pane and text-edit-pane replace the selected text with a printed representation of the object if any text was selected, and otherwise insert the object at the text cursor position. The combo-box-pane method does likewise, but only if the typable property of its associated combo-box is true.

The bitmap-pane method calls copy-to-stream to copy the object to the window if it is a pixmap, and otherwise does nothing. The drawable-pane method does that as well, but only if its use-bitmap-stream property is true.

The methods for single-item-list-pane and multi-item-list-pane add the bbject as a new value to the range of the associated single-item-list or multi-item-list widget. If the object is a list, then one item is added for each member of the list. If the pastable property of the widget is :after, then the new item is added just after the currently focused item, and otherwise it is added just before it (that is, at the "current position" in the range).

The method for dialog-item simply calls paste-selection on the window of the dialog-item if the widget is currently on a parent window.

An around method on widget-window causes nothing to be done if window-or-widget is either a dialog-item or its associated window, and the widget's pastable property is nil. By default, pastable is true only for text-editing widgets.

An anomaly: The only way to paste formatted text into a rich-edit-pane using this function is to first make sure that rich text is currently on the clipboard, and then to call this function with nil as the object argument. (Or just call paste-command.) If the object received here is non-nil, then it will always be pasted as a simple string, using the formatting of the window at the insertion point. Calling (setf rich-edit-range) is a way to insert formatted text without using the clipboard.

See copy-selection for a note abouting adding additional methods for other types of widgets.

Compatibility note

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.

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.