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.
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
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-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.
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.
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-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:
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
Internal > calculate-constraints
The possible values for the hints listed in Width and height hints are as follows:
The size in pixels.
t means use the value of
The width of any text in the element.
The width of the screen.
The height of the screen.
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:
CAPI User Guide and Reference Manual (Macintosh version) - 3 Aug 2017