simple-pane 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

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 by (setf simple-pane-enabled) 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. The keyword :background can also be used as the value for background, which is generally the same as not specifying background at all, except for layout panes where the initargs :background :background also forces the pane to have its own native GUI object. You need to do that if you want to make a layout without a background initially, and change it later using (setf simple-pane-background).

font 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.

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 8.12 Popup menus for panes.

Notes

1. foreground is ignored for buttons on Windows and Cocoa.
2. On Microsoft Windows pane-menu is not supported for title-pane. See title-pane for alternative approaches.
3. The font, foreground and background might be overridden by settings created using set-interface-pane-name-appearance or set-interface-pane-type-appearance.

Description: Cursor

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. 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.

Description: Drag and drop

drop-callback 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 drop-callback of any 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 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:

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:

When drop-callback is a list, it specifies a simple response. The list should be of the form:

(effects formats drop-stage-callback &optional checker)

Both effects and formats can be either a list of effects or formats, or an atom which is interpreted as a list of one element. effects and formats specify which effects and formats are allowed.

For the stages except :formats, the first effect of the given effects that the drop-object allows is set (by calling (setf drop-object-drop-effect)), except when checker 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

If checker returns non-nil it sets the effect. If checker returns nil for the formats, it goes to the next effect.

In the :drop stage, after setting the effect, it gets the object with first format that is provided by the drop-object, and then calls the drop-stage-callback with four arguments:

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 (:above, :item, :below), which are the results of drop-object-collection-index. Otherwise, the last two arguments are the x and y (results of drop-object-pane-x and drop-object-pane-y). It is the responsibility of the drop-stage-callback to perform whatever dropping should mean.

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 => result

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 normally return a plist result 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 format :string is understood by some other panes that expect text.

The plist result returned by drag-callback can contain the key :image-function with a function image-function as value.

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.

drag-callback can also be used in top-level interfaces. In this case the second argument info 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 drag-image (see interface).

drag-callback is allowed to return the result :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 :interface-pathname. drag-callback is allowed to return the result nil, meaning do not do dragging.

On output-pane you add dragging by adding an entry to the input-model and which initiates the dragging by calling drag-pane-object.

Notes: Drag and drop

If :image is supplied in the plist returned by drag-callback, the dragging mechanism automatically frees the image object as if by free-image when it no longer needs it.

Description: Scroll

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-panes 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:

(example-edit-file "capi/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 6.5.2 Constraint Formats for more information about height and width initargs.

scroll-bar-type controls the visibility of scroll bars on Cocoa. By default, the visibility of scroll bars depends on the System Preferences, which in newer versions of macOS is to have scroll bars that are not always visible. Supplying :always-visible causes the scroll bars to be always visible as they used to be.

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.

Description: Border

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

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.

Description: Miscellaneous

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.

Notes: Miscellaneous

1. In order to display a simple pane, it needs to be contained within an interface. In a real application you will will define your interface class, but for debugging and just playing around with pane 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.
2. You can also control automatic resizing of a simple-pane using set-object-automatic-resize.

Examples

(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:

(example-edit-file "capi/choice/drag-and-drop")

See also

contain
define-font-alias
set-object-automatic-resize
3 General Properties of CAPI Panes
6 Laying Out CAPI Panes
9 Adding Toolbars
13.10.3.2 Transparency and the alpha channel