6.5 Constraining the size of layouts

The size of a layout (often referred to as its geometry) is calculated automatically on the basis of the size of each of its children. The algorithm used takes account of hints provided by the children, and from the description of the layout itself. Hints are specified via the panes' initargs when they are created. The various pane classes have useful default values for these initargs.

6.5.1 Default Constraints

If you do not specify any hints, the CAPI calculates the on-screen geometry based on its default constraints. With this geometry the various elements are displayed with adequate space in the window.

This is designed to work regardless of variable factors such as the user's configuration, for example specifying large font sizes. It is often wrong to constrain CAPI elements to fixed pixel sizes, as these constraints may lead to poorer layouts in some configurations.

For information about the effect of constraints on scrolling, see 6.4.1 Width and height hints.

6.5.2 Constraint Formats

Hints can take arguments in a number of formats, which are described in full under 6.4.2 Hint values formats. When given a number, this should be an integer and the layout is constrained to that number of pixels. A constraint can also be specified in terms of character widths or heights, as shown in the next section.

6.5.2.1 Character constraints

In 6.3 Combining different layouts, you created a window with five panes, by combining row and column layouts. Now consider changing the definition of the editor pane so that it is required to have a minimum size. This would be a sensible change to make, because editor panes need to be large enough to work with comfortably.

(setq editor2 
      (make-instance 'editor-pane
                     :text "An editor pane with minimum size"
                     :visible-min-width '(:character 30)
                     :visible-min-height '(:character 10)))

Now display a window similar to the last example, but with the editor2 editor pane. Note that it is only the description of the top-level column layout which differs. Before entering the following into the listener, you should close all the windows created in this chapter in order to free up the instances of button1, button2 and so forth.

(contain (make-instance 'column-layout
                        :description 
                        (list row1 row2 editor2)))

You will not be able to resize the window any smaller than this:

6.5.2.2 String constraints

To make a pane that is wide enough to accommodate a given string, use the :visible-min-width hint with a (:string string) constraint.

In this example we also supply :visible-max-width t, which fixes the maximum visible width to be the same as the minimum visible width. Hence the pane is wide enough, but no wider:

(defvar *text* "Exactly this wide")
 
(capi:contain
 (make-instance 'capi:text-input-pane
                :text *text*
                :visible-min-width `(:string ,*text*)
                :visible-max-width t
                :font (gp:make-font-description
                       :size (+ 6 (random 30)))))

Note that the width constraint works regardless of the font used.

6.5.3 Changing the constraints

If you need to alter the constraints on an existing element, use the function set-hint-table. See how the interface in 6.5.2.1 Character constraints resizes after this call:

(apply-in-pane-process editor2
 'set-hint-table editor2 '(:visible-min-width (:character 100)))

If you define your own pinboard-object class, ensure that its hint table matches the visible geometry and is kept synchronized after any movement of the object, otherwise redrawing may be incorrect.

Similarly if you draw pinboard objects under a transform, call set-hint-table with the transformed geometry to ensure correct redrawing.