All Manuals > CAPI User Guide and Reference Manual > 21 CAPI Reference Entries

docking-layout Class


A class that implements docking of panes.





A list of pane specifications. The panes become the items in the layout.
A docking layout controller.
A function controlling whether a pane can be docked.
A function called when a pane is docked or undocked.
A boolean allowing a visible edge around the layout.
One of :horizontal or :vertical.





The class docking-layout defines a region in which panes can be docked and undocked. The undocking functionality works only in LispWorks for Windows.

If controller is non-nil, it must be a controller object as returned by a call to make-docking-layout-controller. In this case the docking-layout is one of a group of docking-layouts which share that same controller, known as the Docking Group. The panes that can be docked and undocked are shared between the members of the Docking Group. If controller is nil (the default value), the docking-layout is in a Docking Group of one.

A pane pane is dockable in a Docking Group when it is an item of any member of the Docking Group. This is the case when it is one of the items passed to make-instance for some member of the group, or it has been set in some member by (setf docking-layout-items). The user can dock and undock pane in any member of the Docking Group. You can change the dockable status of panes programmatically by (setf docking-layout-items). You can query a pane's docked and visible status in a docking-layout by docking-layout-pane-docked-p and docking-layout-pane-visible-p. You can change a pane's docked and visible status in a docking-layout by (setf docking-layout-pane-docked-p) and (setf docking-layout-pane-visible-p).

By default, the context menu allows the user to alter the visibility status of each of the panes in the Docking Group.

items is a list of pane specifications. Each specification in the list is either an atom denoting a pane, or a list wherein the cl:car is an object denoting a pane and the cl:cdr is a plist of options and values. The object denoting the pane can be:

When an item in the items list is a list, the cdr is a plist of options and values, which can contain these options:

A string which is title associated with the pane. This is used when the pane is presented to the user, for example in the default context menu.
A boolean specifying whether the pane should be docked. The default value is t. When a pane is not docked and is visible, it is displayed in its own window.
A boolean specifying whether the pane is visible. The default value is t.

A list of four integers specifying the geometry of the pane when undocked, as (x y width height).


A boolean specifying whether to place the pane on a new line in the docking-layout. The default value is nil.

docking-layout-items always returns the items as lists, with the cdr containing the options and values.

docking-test-function is a function of two arguments with a boolean return value. When the user attempts to dock a pane pane in the docking-layout, docking-test-function is called with the docking-layout and pane. If it returns nil, pane is not docked. If it returns true, pane is docked. The default behavior is that all panes under the controller which is the controller in this docking-layout, and only these panes, can be docked.

docking-callback, if non-nil, is a function of three arguments: the docking-layout, the pane and a boolean. This third argument is t when the pane is docked, and nil when the pane is undocked. The default value of docking-callback is nil.

divider-p controls whether a visible edge is drawn around the border of the docking-layout. The default value is nil.

orientation specifies whether the items are laid out horizontally or vertically. The default value is :horizontal.

(example-edit-file "capi/layouts/docking-layout")
See also


CAPI User Guide and Reference Manual (Macintosh version) - 01 Dec 2021 19:31:27