If you do not specify any hints, the CAPI uses the default constraints. In many cases that gives useful geometry already.
When you do need to specify the constraints, the normal way is to specify the hints for the element(s) when making them by passing the appropriate keywords. The available keywords and their meanings are explained in Width and height hints, and the potential values are explained in Hint values formats.
It also possible to set the hints later, either by set-geometric-hint to set a single hint or set-hint-table to set all of them.
It is also possible to specify initial constraints, which are applicable during the creation of the window, but not later. Typically that is used to force the initial window to be large enough, but later allowing the user to reduce the size.
In CAPI, there are three kinds of geometry dimensions: external, visible and internal.
External and visible dimensions are two different ways to specify the dimensions of an element on the screen. The external dimension specifies the size of the element including its borders, while the visible dimension specifies the size of the pane inside its borders. Thus
external-width = visible-width + borders-width
external-height = visible-height + borders-height
For a non-scrolling pane, internal dimensions mean the same as visible. For a scrolling pane, internal dimensions specify the size that the pane would need to display all of its data. For example, a list-panel with 100 items of which exactly 30 items are fully visible and each line is 15 pixels high has internal height of 100 x 15 = 1500 pixels and visible height of 30 x 15 = 450 pixels.
To get the right layout on the screen, you typically need to specify constraints on the width and height on the screen, which you do by specifying either the external constraints or visible constraints. This is the main way of using constraints.
The internal dimensions are needed only to compute the size of the scrollbars. Most elements implicitly compute their own internal dimensions. You should specify the minimum internal dimensions by :scroll-height and :scroll-width when you have an output-pane with scrollbar(s) which does ordinary scrolling (the default), so the pane can compute the size of the scrollbars. However, you can use set-horizontal-scroll-parameters and set-vertical-scroll-parameters instead.
The following keywords are used to specify geometrical constraints.
External constraints control the size that the pane takes up in its parent:
:external-min-width — the minimum width of the child in its parent
:external-max-width — the maximum width of the child in its parent
:external-min-height — the minimum height of the child in its parent
:external-max-height — the maximum height of the child in its parent
Visible constraints control the size of the part of the pane that you can see:
:visible-min-width — the minimum visible width of the child.
:visible-max-width — the maximum visible width of the child.
:visible-min-height — the minimum visible height of the child.
:visible-max-height — the maximum visible height of the child.
If the visible-max-width is the same as the visible-min-width , then the element is not horizontally resizable. If the visible-max-height is the same as the visible-min-height , then the element is not vertically resizable.
Internal constraints control the size of region used to display the contents of the pane: These are all deprecated.
:internal-min-width — the minimum width of the display region.
:internal-max-width — the maximum width of the display region.
:internal-min-height — the minimum height of the display region.
:internal-max-height — the maximum height of the display region.
In addition, methods for the generic function calculate-constraints can be defined on your pane classes to compute the internal geometries. Note that when scrolling the :internal-max-width and :internal-max-height are not meaningful and are ignored.
For a scrolling pane, the internal constraints control the size of region over which you can scroll and the visible constraints control the size of the viewport. Here is an illustration of the external, internal and visible sizes in a scrolling list panel with 8 items, 4 of which are fully visible and 1 is partially visible:
Figure 6.5 External, visible and internal sizes:
Initargs :min-width, :max-width, :min-height and :max-height are deprecated. They are synonyms for the visible constraints :visible-min-width and so on.
It is often wrong to constrain CAPI elements to fixed pixel sizes, as these constraints may lead to poorer layouts in some configurations.
The order of priority is the order in Width and height hints. That is, for a non-scrolling pane when there is only one independent constraint the preference order is:
External > Visible > Internal > calculate-constraints
For a scrolling pane where there are two independent constraints the preference order for the external constraint is:
and the preference order for the internal constraint is:
Internal > calculate-constraints
The possible values for the hints listed in Width and height hints are as follows:
The size in pixels.
For :visible-max-width, t means use the value of :visible-min-width
.
For :visible-max-height, t means use the value of :visible-min-height.
The width of any text in the element.
The height of any text in the element.
The width of the screen.
The height of the screen.
A list starting with any of the following operators, followed by one or more hints:
max — the maximum size of the hints.
min — the minimum size of the hints.
- — the subtraction of hints from the first.
* — the multiplication of the hints.
/ — the division of hints from the first.
A two element list specifying the size of a certain amount of text when drawn in the element:
(:character
integer
) — the size of
integer
characters.
(character
integer
) — the size of
integer
characters.
(:string
string
) — the size of
string
.
(string
string
) — the size of
string
.
A two-element list starting with symbol-value, and containing one other symbol:
(symbol-value
foo
) — the size of the symbol-value of
foo
.
A list starting with apply or funcall, followed by a symbol and arguments:
(apply
function
arg1
arg2
...) — the result of applying the function
function
to the arguments.
(funcall
function
arg1
arg2
...) — the result of calling the function
function
with the arguments.
You can use the initarg :initial-constraints to specify constraints that apply during creation of the element's interface, but not after the interface is displayed.
initial-constraints must be a plist of constraints, where the keywords are geometry hints as described above.
For example, this creates a window that starts at least 600 pixels high, but can be made shorter by the user, because that initial constraint is transient. However, the permanent height constraints on the two output panes remain in effect:
(contain
(make-instance 'column-layout
:description
(list (make-instance 'output-pane
:visible-min-height 100
:background :red)
(make-instance 'output-pane
:visible-min-height 200
:background :blue))
:initial-constraints '(:visible-min-height 600)))
CAPI User Guide and Reference Manual (Windows version) - 3 Aug 2017