10.2.4 The Layout Protocol

The layout protocol is triggered by
layout-frame
, which is called when a frame is adopted by a frame manager.

CLIM uses a two-pass algorithm to lay out a pane hierarchy. In the first pass (called
space composition
), the top-level pane is asked how much space it requires. This may in turn lead to the same question being asked recursively of all the panes in the hierarchy, with the answers being composed to produce the top-level pane's answer. Each pane answers the query by returning a
space requirement
(or
space-requirement
) object, which specifies the pane's desired width and height, as well as its willingness to shrink or grow along its width and height.

In the second pass (called
space allocation
), the frame manager attempts to obtain the required amount of space from the host window system. The top-level pane is allocated the space that is actually available. Each pane, in turn, allocates space recursively to each of its descendants in the hierarchy according to the pane's rules of composition.

For many types of panes, the application programmer can indicate the space requirements of the pane at creation time by using the space requirement options, as well as by calling the
change-space-requirements
function. Panes are used to display application-specific information, so the application can determine how much space should normally be given to them.

Other pane types automatically calculate their space needs based on the information they have to present. For example, the space requirement for a label pane is a function of the text to be displayed.

A composite pane calculates its space requirement based on the requirements of its children and its own particular rule for arranging them. For example, a pane that arranges its children in a vertical stack would return as its desired height the sum of the heights of its children. Note, however, that a composite pane is not required by the layout protocol to respect the space requests of its children; in fact, composite panes aren't even required to ask their children.

Space requirements are expressed for each of the two dimensions as a preferred size, a minimum size below which the pane cannot be shrunk, and a maximum size above which the pane cannot be grown. (The minimum and maximum sizes can also be specified as relative amounts.) All sizes are specified as a real number indicating the number of device units (such as pixels).

space-requirement [Protocol Class]

Summary: The protocol class of all space requirement objects. There are one or more subclasses of
space-requirement
with implementation-dependent names that implement space requirements. The exact names of these classes is explicitly unspecified. If you want to create a new class that behaves like a space requirement, it should be a subclass of
space-requirement
. Subclasses of
space-requirement
must obey the space requirement protocol.

All the instantiable space requirement classes provided by CLIM are immutable.

Summary: Returns a new space requirement whose components are the sum of each of the components of
space-req
added to the appropriate keyword argument (for example, the width component of
space-req
is added to
width
). This is intended to be a more efficient, spread version of
space-requirement+
.

change-space-requirements [Generic Function]

Arguments: pane
&key
resize-frame
&rest
space-req-keys

Summary: This function can be invoked to indicate that the space requirements for
pane
have changed. Any of the options that applied to the pane at creation time can be passed into this function as well.

resize-frame
determines whether the frame should be resized to accommodate the new space requirement of the hierarchy. If
resize-frame
is
t
, then
layout-frame
will be invoked on the frame. If
resize-frame
is
nil
, then the frame may or may not get resized depending on the pane hierarchy and the
:resize-frame
option that was supplied to
define-application-frame
.

note-space-requirements-changed [Generic Function]

Arguments: sheet pane

Summary: This function is invoked whenever
pane
's space requirements have changed.
sheet
must be the parent of
pane
. Invoking this function essentially means that
compose-space
will be reinvoked on
pane
, and it will reply with a space requirement that is not equal to the reply that was given on the last call to
compose-space
.

This function is automatically invoked by
change-space-requirements
in the cases that
layout-frame
isn't invoked. In the case that
layout-frame
is invoked, it isn't necessary to call
note-space-requirements-changed
, since a complete re-layout of the frame will be executed.

changing-space-requirements [Macro]

Arguments: (
&key
resize-frame layout)
&body
body

Summary: This macro supports batching the invocation of the layout protocol by calls to
change-space-requirements
. Within the body, all calls to
change-space-requirements
change the internal structures of the pane and are recorded. When the body is exited, the layout protocol is invoked appropriately.
body
may have zero or more declarations as its first forms.

compose-space [Generic Function]

Arguments: pane

Summary: During the space composition pass, a composite pane will typically ask each of its children how much space it requires by calling
compose-space
. They answer by returning
space-requirement
objects. The composite will then form its own space requirement by composing the space requirements of its children according to its own rules for laying out its children.

allocate-space [Generic Function]

Arguments: pane width height

Summary: During the space allocation pass, a composite pane will arrange its children within the available space and allocate space to them according to their space requirements and its own composition rules by calling
allocate-space
on each of the child panes.
width
and
height
are the width and height of
pane
in device units.