Class

Summary

The class simple-pane is the superclass for any elements that actually appear as a native window, and is itself an empty window.

Package

capi

Superclasses

element

Subclasses

display-pane
interface
title-pane
button-panel
list-panel
option-pane
output-pane
progress-bar
slider
text-input-pane
tree-view
toolbar
layout
button

Initargs

:enabled

A boolean controlling whether the pane is enabled.

:background

The background color of the pane.

:foreground

The foreground color of the pane.

:font

The default font for the pane.

:horizontal-scroll

t , :without-bar , or nil . If true the pane can scroll horizontally.

:vertical-scroll

t , :without-bar , or nil . If true the pane can scroll vertically.

:visible-border

A boolean or a keyword controlling whether the pane has a border, for some pane classes.

:internal-border

A non-negative integer, or nil . Controls the width of the internal border.

:cursor

A keyword naming a built-in cursor, or a cursor object, or nil .

:pane-menu

Specifies a menu to be raised by the :post-menu gesture.

:drop-callback

Specifies a drop callback for output-pane or interface (and on Cocoa, list-panel or tree-view).

:drag-callback

Specifies a drag callback for list-panel or tree-view.

:scroll-if-not-visible-p

Defines whether, when the focus is given to the pane and the pane is not fully visible, the pane's parent is automatically scrolled to show it.

:toolbar-title

A string.

Accessors

simple-pane-enabled
simple-pane-background
simple-pane-foreground
simple-pane-font
simple-pane-cursor
simple-pane-scroll-callback
simple-pane-drop-callback
simple-pane-drag-callback

Readers

simple-pane-horizontal-scroll
simple-pane-vertical-scroll
simple-pane-visible-border

Description

enabled determines whether the pane is enabled. The default value is t . Note that changing the enabled state of a visible pane changes its appearance.

background and foreground 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.

font should be font, a font description, or nil .

The value for visible-border can be any of the following, with the stated meanings where applicable:

nil

Has no border.

t

Has a border.

:default

Use the default for the window type.

:outline

Add an outline border.

There are various platform/pane class combinations which do not respond to all values of visible-border . For instance, on Windows XP with the default theme, text-input-choice and option-pane always have a visible border regardless of the value of visible-border , while other classes including display-pane , text-input-pane , list-panel , editor-pane and graph-pane have three distinct border styles, with visible-border :default meaning the same as visible-border t .

If internal-border is non-nil, it should be a non-negative integer specifying the width of an empty region around the edge of the pane.

Any simple pane can be made scrollable by specifying t to :horizontal-scroll or :vertical-scroll . By default these values are nil , but some subclasses of simple-pane default them to t where appropriate (for instance editor-pane s always default to having a vertical scroll-bar).

For a pane which is scrollable but does not display a scroll bar, pass the value :without-bar for :horizontal-scroll or :vertical-scroll . See the example in output-panes/scrolling-without-bar.lisp .

The height and width of a scrollable simple pane can be specified by the initargs :scroll-height and :scroll-width , which have the same meaning as :internal-min-height and :internal-min-width . See the LispWorks CAPI User Guide for more information about height and width initargs.

cursor specifies a cursor for the pane. nil means use the default cursor, and this is the default value. cursor 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.

 

cursor	Cocoa	Windows	Motif
:busy	No	Yes	Yes
:i-beam	Yes	Yes	Yes
:top-left-arrow	Yes	Yes	Yes
:h-double-arrow	Yes	Yes	Yes
:v-double-arrow	Yes	Yes	Yes
:left-side	Yes	Yes	Yes
:right-side	Yes	Yes	Yes
:top-side	Yes	Yes	Yes
:bottom-side	Yes	Yes	Yes
:wait	No	Yes	Yes
:crosshair	Yes	Yes	Yes
:gc-notification	No	Yes	Yes
:top-left-corner	No	Yes	Yes
:top-right-corner	No	Yes	Yes
:bottom-left-corner	No	Yes	Yes
:bottom-right-corner	No	Yes	Yes
:hand	Yes	Yes	Yes
:fleur	Yes	Yes	Yes
:move	Yes	Yes	Yes
:closed-hand	Yes	No	No
:open-hand	Yes	No	No
:disappearing-item	Yes	No	No

Note: On Cocoa in Mac OS X 10.2, only :i-beam is supported.

pane-menu 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 pane-menu , see the section "Popup menus for panes" in the LispWorks CAPI User Guide .

drop-callback can be specified for a pane that is an instance of output-pane, interface or a subclass of one of these. On Cocoa, list-panel and tree-view also support drop-callback . When the user drags an object over a window, the CAPI first tries to call the drop-callback of any output-pane under the mouse and otherwise calls the drop-callback of the top-level interface. The default value of drop-callback is nil , which means that there is no support for dropping into the pane.

For editor-pane, drop-callback can be :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 a function designator with this signature:

drop-callback pane drop-object stage

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 :

:formats

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.

:enter

This occurs when the user drags an object over the pane which is an output-pane or interface (not tree-view or list-panel). It can query the drop-object 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 (setf drop-object-drop-effect) 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.

:drag

This occurs while the user is dragging an object over the pane. It can query the drop-object 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 (setf drop-object-drop-effect) 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.

:drop

This occurs when the user drops an object over the pane. It can query the drop-object 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 (setf drop-object-drop-effect) 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.

drag-callback can be specified for a pane that is an instance of list-panel or tree-view. The default value of drag-callback is 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 => plist

When the user drags items in the pane, the CAPI calls the drag-callback . pane is the pane itself and info is a list of item indices that are being dragged (compare with choice-selection). The drag-callback should return the plist 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 drop-callback ). The :string format is understood by some other panes that expect text.

scroll-if-not-visible-p controls scrolling behavior of the parent when the pane is given the input focus. scroll-if-not-visible-p can be t , nil , or :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.

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.

Notes

1. foreground is ignored for buttons on Windows and Cocoa.
2. In order to display a simple pane, it needs to be contained within an interface. The two convenience functions make-container and contain are provided to create an interface with enough support for that pane. The function make-container just returns a container for an element, and the function contain displays an interface created for the pane using make-container.

Example

(capi:contain (make-instance 'capi:output-pane

                  :background :red

                  :scroll-width 300

                  :horizontal-scroll t))

(setf ep

      (capi:contain

       (make-instance 'capi:editor-pane

                      :visible-border t)))

(setf (capi:simple-pane-cursor ep) :crosshair)

For an example illustrating the use of drag-callback , see
examples/capi/choices/drag-and-drop.lisp

See also

contain