According to the specification, "COMPOSE-SPACE" is first invoked on the the top-level pane which then asks its children recursivly, resulting in a "SPACE-REQUIREMENT" for each pane in the hierarchy.  When this recursive process terminates, the opt-level pane asks the system for space.  The system may or may not return the exact amount that was asked for.  The actual space given must therefore be distributed by the top-level pane to its children recursiveley through calls to "ALLOCATE-SPACE".
According to the specification, "COMPOSE-SPACE" is first invoked on the
the top-level pane which then asks its children recursivly, resulting
in a "SPACE-REQUIREMENT" for each pane in the hierarchy.  When this
recursive process terminates, the opt-level pane asks the system for
space.  The system may or may not return the exact amount that was
asked for.  The actual space given must therefore be distributed by
the top-level pane to its children recursiveley through calls to
"ALLOCATE-SPACE".

When "ALLOCATE-SPACE" is called on a pane P, it must compare the
space-requirement of the children of P to the available space in order
to distribute it in the most preferable way.  In order to avoid a
second recursive invokation of "COMPOSE-SPACE" at this point, we store
the result of the previous call to "COMPOSE-SPACE" in each pane.

The situation is complicated by the fact that a user can (according to
the spacification) give explicit values for the pane sizes (such as
:width and :height) at the time the pane is created.  These explicit
values override the ones obtained by the normal rule of composing a
space requirement from the requirements of the children.  For that
reason, we use an :around method on "COMPOSE-SPACE".

This way, we can control the composition protocol. The :around method
will call the primary method only if necessary (i.e., (eq (slot-value pane
'space-requirement) nil)), and store this request.
Then we'll compute the space-requirement of the pane as follow:
     (setf (space-requirement-width ...)
           (or explicit-width (space-requirement-width request))
           ...
           (space-requirement-max-width ...)
           (or explicit-max-width
               explicit-width
               (space-requirement-max-width request))
           ...)

When the call to the primary method is not necessary we simply
return the stored value.

[minor issue]: We have a special case for the spacer-pane. Indeed,
  the explicit size you can give for this pane should represent the margin
  size.  So its primary method should only call compose on the child.
  And the around method will compute the explicits-sizes for it from
  the space requirement of the child and for the values given for the
  surrounding space.

Looking at the change-space notification protocol, it suggest that
the function "NOTE-SPACE-REQUIREMENT-CHANGED" should invalidate the
stored value of the compose protocol, and reinvoke "COMPOSE-SPACE" on
the pane. Then, according to the rules of the spec, it should notify its
parents if (not (or (typep pane 'restraining-pane)
                    (typep pane 'top-level-sheet-pane)))

        and if no explicit width and height had been given.
In those "stop cases" a call to allocate-space is made.

ALLOCATE PROTOCOL.

For this, the hardest thing to do is respecting the children's
desires, and the actual ratio between the children.
We can regard that problem in four different ways:

   1 - horizontal panes (box, rack)
   2 - vertical panes
   3 - table-pane
   4 - grid-pane.

 1,2.
We will use two sorted lists.
Those lists should be sorted by ratio (i.e., (/ size
extremeum-size)) of each child depending on the main size of the pane.

-- for example :  h(box, pane) --

(/ width max-width) <== sort by >
(/ width min-width) <== sort by <

---------------------------------

Now we can distribute the space correctly by iterating over one of the
lists (depending on whether we are increasing or decreasing the size).

 3.
We will use the same method as before.  We should have a list for the
first column and one for the first line.  Then we can iterate again.

[minor issue]: those lists have to be created and stored after the
call to compose-space.

 4.
This pane is the simplest: indeed what we have to do is equaly
dividing the sizes by the number of children.
       - child width = (/ new-size nb-children-per-line)
       - child height = (/ new-size nb-children-per-column)

[minor issue]: we do those operations for each child.  Otherwise we
take the risk that the result sizes are not integers.



According to the specification, "COMPOSE-SPACE" is first invoked on the
the top-level pane which then asks its children recursivly, resulting
in a "SPACE-REQUIREMENT" for each pane in the hierarchy.  When this
recursive process terminates, the opt-level pane asks the system for
space.  The system may or may not return the exact amount that was
asked for.  The actual space given must therefore be distributed by
the top-level pane to its children recursively recursivly through
calls to "ALLOCATE-SPACE".

When "ALLOCATE-SPACE" is called on a pane P, it must compare the
space-requirement of the children of P to the available space in order
to distribute it in the most preferable way.  In order to avoid a
second recursive invokation of "COMPOSE-SPACE" at this point, we store
the result of the previous call to "COMPOSE-SPACE" in each pane.

The situation is complicated by the fact that a user can (according to
the spacification) give explicit values for the pane sizes (such as
:width and :height) at the time the pane is created.  These explicit
values override the ones obtained by the normal rule of composing a
space requirement from the requirements of the children.  For that
reason, we use an :around method on "COMPOSE-SPACE".

This way, we can control the composition protocol. The :around method
will call the primary method only if necessary (i.e., (eq (slot-value pane
'space-requirement) nil)), and store this request.
Then we'll compute the space-requirement of the pane as follow:
     (setf (space-requirement-width ...)
           (or explicit-width (space-requirement-width request))
           ...
           (space-requirement-max-width ...)
           (or explicit-max-width
               explicit-width
               (space-requirement-max-width request))
           ...)

When the call to the primary method is not necessary we simply
return the stored value.

[minor issue]: We have a special case for the spacer-pane. Indeed,
  the explicit size you can give for this pane should represent the margin
  size.  So its primary method should only call compose on the child.
  And the around method will compute the explicits-sizes for it from
  the space requirement of the child and for the values given for the
  surrounding space.

Looking at the change-space notification protocol, it suggest that
the function "NOTE-SPACE-REQUIREMENT-CHANGED" should invalidate the
stored value of the compose protocol, and reinvoke "COMPOSE-SPACE" on
the pane. Then, according to the rules of the spec, it should notify its
parents if (not (or (typep pane 'restraining-pane)
                    (typep pane 'top-level-sheet-pane)))

        and if no explicit width and height had been given.
In those "stop cases" a call to allocate-space is made.

ALLOCATE PROTOCOL.

For this, the hardest thing to do is respecting the children's
desires, and the actual ratio between the children.
We can regard that problem in four different ways:

   1 - horizontal panes (box, rack)
   2 - vertical panes
   3 - table-pane
   4 - grid-pane.

 1,2.
We will use two sorted lists.
Those lists should be sorted by ratio (i.e., (/ size
extremeum-size)) of each child depending on the main size of the pane.

-- for example :  h(box, pane) --

(/ width max-width) <== sort by >
(/ width min-width) <== sort by <

---------------------------------

Now we can distribute the space correctly by iterating over one of the
lists (depending on whether we are increasing or decreasing the size).

 3.
We will use the same method as before.  We should have a list for the
first column and one for the first line.  Then we can iterate again.

[minor issue]: those lists have to be created and stored after the
call to compose-space.

 4.
This pane is the simplest: indeed what we have to do is equaly
dividing the sizes by the number of children.
       - child width = (/ new-size nb-children-per-line)
       - child height = (/ new-size nb-children-per-column)

[minor issue]: we do those operations for each child.  Otherwise we
take the risk that the result sizes are not integers.

quek/mcclim,informatimago/mcclim,quek/mcclim,informatimago/mcclim