Class

Summary

A tab-layout displays multiple tabs and a pane which shows the main contents. The user can select a tab, which affects what is displayed in the pane.

Package

capi

Superclasses

choice
layout

Initargs

:description

The main layout description.

:items

Specifies the tabs of the tab layout.

:visible-child-function

Returns the visible child for a given selection in switchable mode.

:combine-child-constraints

A generalized boolean which influences the initial size of the layout.

:print-function

The function used to print a name on each tab.

:callback-type

The type of data passed to the callback function in callback mode.

:selection-callback

The function called when a tab is selected, in callback mode.

:image-function

Returns an image for an item, on Microsoft Windows.

:image-lists

A plist of keywords and image-list objects, on Microsoft Windows.

Accessors

tab-layout-visible-child-function

Readers

tab-layout-combine-child-constraints
tab-layout-image-function

Description

tab-layout is a subclass of choice. Most importantly it inherits choice's selection and selection-callback behavior, and its print-function (which is used to determine the string that appear in each tab), and its items behavior (which in turn derives from collection).

tab-layout has two modes:

Switchable mode

Selecting a different tab causes a different pane to be displayed.

Callback mode

Selecting a tab merely calls a callback. This callback is responsible for make any required change.

The mode of a tab-layout is determined by the initarg :visible-child-function. A non-nil value specifies switchable mode, nil specifies callback mode.

In switchable mode, selecting on a tab causes a call to the function visible-child-function (after doing the selection-callback ) with the selected item as a single argument. visible-child-function must return a pane, which is then displayed. The pane that is returned by visible-child-function must not be displayed elsewhere, but can be any pane. Repeated calls with the same item should return the same pane, otherwise it will create a new pane each time the tab is selected.

In callback mode there is only one pane, which you must specify by the initarg :description (which is inherited from layout). In this case the selection-callback must perform any changes that are needed.

In either mode combine-child-constraints influences the initial size of the layout. When combine-child-constraints is nil the constraints of the tab layout depend only on its currently visible tab. Switching to a different tab might cause the layout to resize. When combine-child-constraints is non-nil, the constraints depend on all of the tabs, including those that are not visible. This might increase the time taken to create the tab layout initially, but can prevent unexpected resizing later. The default value of combine-child-constraints is nil.

If image-lists is specified, it should be a plist containing the keyword :normal as a key. The corresponding value should be an image-list object. No other keys are supported at the present time. The image-list associated with the :normal key is used with the image-function to specify an image to display in each tab.

The image-function is called on an item to return an image associated with the item. It can return one of the following:

A pathname or string

This specifies the filename of a file suitable for loading with load-image. Currently this must be a bitmap file.

A symbol

The symbol must have been previously registered by means of a call to register-image-translation.

An image object, as returned by load-image.

An image locator object

This allowing a single bitmap to be created which contains several button images side by side. See make-image-locator for more information. On Microsoft Windows, it also allows access to bitmaps stored as resources in a DLL.

An integer

This is a zero-based index into the tab-layout's image-list. This is generally only useful if the image list is created explicitly. See image-list for more details.

Notes

image-lists and image-function are implemented only on Microsoft Windows.

Example

The following example shows the use of the switchable mode of tab-layout. Each tab is linked to an output pane by pairing them in the items list.

(defun switchable-tab-layout ()

  (let* ((red-pane (make-instance

                    'capi:output-pane

                    :background :red))

         (blue-pane (make-instance

                     'capi:output-pane

                     :background :blue))

         (tl (make-instance

              'capi:tab-layout

              :items 

              (list (list "Red" red-pane)

                    (list "Blue" blue-pane))

              :print-function 'car

              :visible-child-function 'second)))

    (capi:contain tl)))

(switchable-tab-layout)

Here is an example of the callback mode of tab-layout, which uses the selection of a tab to change the nodes of a graph pane through the selection-callback .

(defun non-switchable-tab-layout (tabs)

  (let* ((gp (make-instance 

              'capi:graph-pane))

         (tl (make-instance 

              'capi:tab-layout

              :description (list gp)

              :items tabs

              :visible-child-function nil

              :print-function 

              (lambda (x) 

                (format nil "~R" x))

              :callback-type :data

              :selection-callback 

              #'(lambda (data) 

                  (setf (capi:graph-pane-roots gp)

                        (list data))))))

    (capi:contain tl)))

(non-switchable-tab-layout '(1 2 4 5 6))

See also

callbacks
simple-layout
switchable-layout
tab-layout-panes
tab-layout-visible-child
Tab layouts
Programming with CAPI Windows