Class

Summary

A class that implements docking of panes.

Package

capi

Superclasses

simple-layout

Initargs

:items

A list of pane specifications. The panes become the items in the layout.

:controller

A controller for the layout, which can make multiple docking-layouts work together.

:docking-test-function

A function controlling whether a pane can be docked in a docking-layout.

:docking-callback

A function called when a pane is docked or undocked.

:divider-p

A boolean allowing a visible edge around the layout.

:orientation

One of :horizontal or :vertical.

Accessors

docking-layout-controller
docking-layout-divider-p
docking-layout-docking-test-function
docking-layout-items

Readers

docking-layout-orientation

Description

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:

• The pane itself.
• A symbol naming a slot in the interface which contains the docking-layout. The value in that slot, which must be a pane, is used. Typically the slot name is defined in the :panes or :layouts class option in the define-interface form.
• A string, denoting a title-pane with that text.
• A list, wherein the car is the name of a pane class and the cdr is a list of initialization arguments for that class. This denotes the pane created by applying make-instance to the list. Note that in this case the list cannot be the item in the items list, because it would be wrongly interpreted as a list wherein the car denotes a pane directly and the cdr is a plist of options and values.

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

:title

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.

:docked-p

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.

:visible-p

A boolean specifying whether the pane is visible. The default value is t.

:undocked-geometry

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

:start-new-line-p

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

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

See also

docking-layout-pane-docked-p
docking-layout-pane-visible-p