The background color of the pane.
The foreground color of the pane.
The default font for the pane.
are colors specified using the Graphics Ports color system. Additionally on Cocoa, the special value
:transparent is supported, which makes the pane's background match that of its parent.
should be a font, a font-description, a font alias, or
nil. If it is not a font, it is converted to a font when the pane is created.
nil is converted to the default font, and a font-description is converted as if by calling find-best-font.
can be used to specify or create a menu to be displayed when the
:post-menu gesture is received by the pane. It has the default value
:default which means that make-pane-popup-menu is called to create the menu. For a full description of
, see Popup menus for panes.
cursor specifies a cursor for the pane. On Cocoa and GTK+, the cursor initarg has an effect only in output-pane and its subclasses. On other platforms it changes the cursor for other CAPI pane classes, although this may contravene style guidelines.
nil means use the default cursor, and this is the default value.
can also be a cursor object as returned by load-cursor. The other allowed values are keywords naming built-in cursors which are supported on each platform as shown in the table below.
can be specified for a pane that is an instance of output-pane, interface, list-panel, tree-view or a subclass of one of these. When the user drags an object over a window, the CAPI first tries to call the
of any pane under the mouse and otherwise calls the
of the top-level interface. The default value of
nil, which means that there is no support for dropping into the pane.
:default, which provides support for dropping a string into the pane and inserting the string into the pane's editor buffer.
If drop-callback is any other non-nil value, it should be either a list (for simple cases) or function designator (to use all options). When it is a function designator, it needs to have this signature:
The function drop-callback is called by the CAPI at various times such as when the pane is displayed and when the user attempts to drop data into the pane. pane is the pane itself, drop-object is an object used to communicate information about the current dropping operation (see below) and stage is a keyword. drop-callback should handle these values of stage :
This might occur when the pane is being displayed or might occur each time the user drags or drops an object over the pane. It should call set-drop-object-supported-formats with the drop-object and a list of formats that the pane wants to receive. Each format is a keyword. The list of the formats must be the same each time it is called.
This occurs when the user drags an object into a pane which is an output-pane or interface (but not for a pane which is a list-panel or tree-view). It can query the
using drop-object-provides-format and drop-object-allows-drop-effect-p to discover what the user is dragging. It can also use drop-object-pane-x and drop-object-pane-y to query the mouse position relative to the pane. It should call
with an effect if it wants to allow the object to be dropped. If this is not called, then the object cannot be dropped into the pane.
This occurs while the user is dragging an object over the pane. It can query the
using drop-object-provides-format and drop-object-allows-drop-effect-p to discover what the user is dragging. For output-pane, it can use drop-object-pane-x and drop-object-pane-y to query the mouse position relative to the pane. For list-panel and tree-view, it can use drop-object-collection-index or drop-object-collection-item to query where the user is attempting to drop the object and can call their setf functions to adjust this position. It should call
with an effect if it wants to allow the object to be dropped. If this is not called, then the object cannot be dropped into the pane. For output-pane and interface, it might also want to update the pane to indicate where the object will be dropped.
This occurs when the user drops an object over the pane. It can query the
as for the
:drag stage, but can also obtain the object itself using drop-object-get-object for one of the formats in the list returned by drop-object-provides-format. Once the object is received, it should call
with the effect that has been used by the callback. It should also update the pane to incorporate the object in whatever way the application requires.
( effects formats drop-stage-callback &optional checker )
For the stages except
:formats, the first effect of the given effects that the
allows is set (by calling
(setf drop-object-drop-effect)), except when
is supplied. In the latter case, before setting an effect it loops through the formats and calls the checker with three arguments:
funcall checker pane effect format
funcall drop-stage-callback pane object x-or-index y-or-placement
If the pane is a tree-view or list-panel, the last two arguments are the item index (for get-collection-item) and placement (
:below), which are the results of drop-object-collection-index. Otherwise, the last two arguments are the
(results of drop-object-pane-x and drop-object-pane-y). It is the responsibility of the
to perform whatever dropping should mean.
can be specified for a pane that is an instance of list-panel or tree-view. The default value of
nil, which means that there is no support for dragging from the pane. Otherwise, it should be a function designator with this signature:
drag-callback pane info => result
should normally return a plist
whose keys are the data formats to be dragged, with a value associated with each format. Formats are arbitrary keywords that must be interpreted by the pane where you intend to drop the values (see the
). The format
:string is understood by some other panes that expect text.
This function is used to generate the image that is used in the dragging itself, exactly as the image-function in drag-pane-object is used. On Cocoa, tree-view and list-panel ignore this key in result .
can also be used in top-level interfaces. In this case the second argument
is a flag describing the gesture that caused the call. Currently the only value is
:drag-image, which means it was invoked by dragging the
is allowed to return the
:default rather than a plist.
:default tells the system to do default dragging if there is any. At the time of writing the only place where there is default dragging is on Cocoa for an interface with an
is allowed to return the
nil, meaning do not do dragging.
Any simple pane can be made scrollable by specifying
:vertical-scroll. By default these values are
nil, but some subclasses of
simple-pane default them to
t where appropriate (for instance
s always default to having a vertical scroll-bar).
The height and width of a scrollable simple pane can be specified by the initargs
:scroll-width, which have the same meaning as
:internal-min-width. See Constraint Formats for more information about height and width initargs.
controls scrolling behavior of the parent when the pane is given the input focus.
:non-mouse. See scroll-if-not-visible-p for details. When this initarg is supplied, the generic function
(setf scroll-if-not-visible-p) is called with it.
Has no border.
Has a border.
Use the default for the window type.
Add an outline border.
There are various platform/pane class combinations which do not respond to all values of
. For instance, on Windows XP with the default theme,
option-pane always have a visible border regardless of the value of
, while other classes including
graph-pane have three distinct border styles, with
:default meaning the same as
automatic-resize makes the pane resize automatically. This has an effect only if it is placed inside a static-layout (including subclasses like pinboard-layout). The effect is that when the static-layout is resized then the pane also changes its geometry.
The value of automatic-resize defines how the pane's geometry changes. It must be a plist of keywords and values which match the keywords of the function set-object-automatic-resize and are interpreted in the same way.
If the pane is used in the toolbar-items list of an interface, then toolbar-title should be a short string that will be shown near to the pane if required for the toolbar.
CAPI User Guide and Reference Manual (Macintosh version) - 25 Feb 2015