Class

Summary

A layout which positions its children on a two dimensional grid.

Package

capi

Superclasses

x-y-adjustable-layout

Subclasses

row-layout
column-layout

Initargs

:columns

The number of columns in the grid.

:has-title-column-p

A boolean specifying whether the first column is a title column.

:orientation

The orientation of the children.

:rows

The number of rows in the grid.

:x-ratios

The ratios between the columns.

:y-ratios

The ratios between the rows.

:x-gap

The gap between each column.

:y-gap

The gap between each row.

:x-uniform-size-p

If t, make each of the columns the same size.

:y-uniform-size-p

If t, make each of the rows the same size.

:min-column-width

nil, or a real number which provides a minimum of the width of each column.

:min-row-height

nil, or a real number which provides a minimum of the height of each row.

Accessors

layout-x-ratios
layout-y-ratios
layout-x-gap
layout-y-gap

Description

The row and column sizes are controlled by the constraints on their children. For example, the visible-min-width of any column is the maximum of the visible-min-width in of the children in the column. The size of the layout is controlled by the constraints on the rows and columns.

For grid-layout description is either a two dimensional array or a list in the order specified by orientation (which defaults to :row). In the case of a list, one of columns or rows can be supplied to specify the dimensions (the default is two columns). As well as panes, slot names and strings, description may contain the element nil, which is interpreted as a special dummy pane with suitable geometry for resizable gaps. This special interpretation of nil in the description is specific to grid-layout and its subclasses.

The x-ratios and y-ratios slots control the sizes of the elements in a grid layout in the following manner:

The elements of x-ratios (or y-ratios ) control the size of each child relative to the others. If an element in x-ratios (or y-ratios ) is nil the child is fixed at its minimum size. Otherwise the size is calculated as follows

(round (* total ratio ) ratio-sum )

where ratio-sum is the sum of the non-nil elements of x-ratios (or y-ratios ) and ratio is the element of ratios corresponding to the child. If this ideal ratio size does not fit the maximum or minimum constraints on the child size, and the constraint means that changing the ratio size would not assist the sum of the child sizes fitting the total space available, then the child is fixed at its constrained size, the child is removed from the ratio calculation, and the calculation is performed again. If x-ratios (or y-ratios ) has fewer elements than the number of children, 1 is used for each of the missing ratios. Leaving x-ratios (or y-ratios ) nil causes all of the children to be the same size.

The positions of each pane in the layout can be specified using x-adjust and y-adjust like every other x-y-adjustable-layout, except that if there is one value then it is used for all of the panes, whereas if it is a list then each value in the list refers to one row or column. If the list does not contain a value for every row or column then the last value is taken to refer to all of the remaining panes.

Normally, the items in a grid-layout are arranged to look like a set of columns that are joined horizontally and rows that are joined vertically. All the cells in each column have the same width and all the cells in each row have the same height. The keyword :right-extend (or :bottom-extend) can be used to allow an item to span more than one column (or row). The keyword should be placed in the cell of the description that you want the item to expand into. For :right-extend, the cell immediately to the left will be extended to fill both columns in that row. For :bottom-extend, the cell immediately above will be extended to fill both rows in that column. Note that the item can only be extended if its constraints allow this. Fosr example, a push-button-panel will not extend by default with :bottom-extend because its constraints fix its height at its min-height.

If has-title-column-p is true, then the items in the description which correspond to the first column are treated specially:

A string

Equivalent to specifying (:title string )

A list of the form (:title string . options )

Make a title using the given list as initargs. options is a plist of options, which can include the keys :title-font, :title-args, :mnemonic or :mnemonic-escape. See titled-object for how these are processed.

A list of the form (:mnemonic-title string . options )

Make a title using the given list as initargs. string can contain the mnemonic escape. options is a plist of options, which can include the keys :title-font, :title-args, or :mnemonic-escape. See titled-object for how these are processed.

Notes

Mnemonics are not supported on all platforms.

Example

(capi:contain (make-instance

               'capi:grid-layout

               :description '("1" "2" "3"

                              "4" "5" "6"

                              "7" "8" "9")

               :columns 3))

(capi:contain (make-instance

               'capi:grid-layout

               :description (list "List:"

                                  (make-instance

                                   'capi:list-panel

                                   :items '(1 2 3))

                                   "Buttons:"

                                  (make-instance

                                   'capi:button-panel

                                   :items '(1 2 3)))))

(capi:contain (make-instance

               'capi:grid-layout

               :description (list "List:"

                                  (make-instance 

                                   'capi:list-panel

                                   :items '(1 2 3))

                                  "Buttons:"

                                  (make-instance 

                                   'capi:button-panel

                                   :items '(1 2 3)))

               :x-adjust '(:right :left)

               :y-adjust '(:center :bottom)))

(capi:contain (make-instance

               'capi:grid-layout

               :description (list "List:"

                                  (make-instance

                                   'capi:list-panel

                                   :items '(1 2 3))

                                  "Buttons:"

                                  (make-instance

                                   'capi:button-panel

                                   :items '(1 2 3)))

               :orientation :column))

This example illustrates the special interpretation of nil in the description :

(capi:contain 

 (make-instance 

  'capi:grid-layout 

  :description 

  (cdr 

   (loop for i below 5 

         appending 

         (list 

          nil 

          (make-instance 'capi:simple-pane 

                         :background :red 

                         :visible-min-width 50 

                         :visible-max-width t 

                         :visible-min-height 50 

                         :visible-max-height t)))) 

  :columns 3) 

 :height 150 :width 150 :title "Resize Me")

This example illustrates the use of :right-extend and :bottom-extend to make cells span multiple columns and rows:

(example-edit-file "capi/layouts/extend")

There are more examples here:

(example-edit-file "capi/applications/")

This example is a grid with :has-title-column-p t :

(example-edit-file "capi/layouts/titles-in-grid")

See also

layout
CAPI elements
Controlling Mnemonics
Laying Out CAPI Panes