Abstract class for constraints on position or size
<clutter-constraint> is a base abstract class for modifiers of a
<clutter-actor> position or size.
A <clutter-constraint> sub-class should contain the logic for
modifying the position or size of the <clutter-actor> to which it
is applied, by updating the actor's allocation. Each
<clutter-constraint> can change the allocation of the actor to
which they are applied by overriding the update-allocation
virtual function.
Constraints can be used with fixed layout managers, like
<clutter-fixed-layout>, or with actors implicitly using a fixed
layout manager, like <clutter-group> and <clutter-stage>.
Constraints provide a way to build user interfaces by using relations
between <clutter-actor>s, without explicit fixed positioning and
sizing, similarly to how fluid layout managers like
<clutter-box-layout> and <clutter-table-layout> lay out
their children.
Constraints are attached to a <clutter-actor>, and are available
for inspection using clutter-actor-get-constraints.
Clutter provides different implementation of the
<clutter-constraint> abstract class, for instance:
<clutter-actor>s; if an actor uses two constraints on both its
horizontal or vertical edges then it can also expand to fit the empty
space.
The example below uses various <clutter-constraint>s to lay out
three actors on a resizable stage. Only the central actor has an
explicit size, and no actor has an explicit position.
<clutter-rectangle> with <"name">layerA is
explicitly sized to 100 pixels by 25 pixels, and it's added to the
<clutter-stage>;
<clutter-align-constraint>s are used to anchor layerA
to the center of the stage, by using 0.5 as the alignment
<"factor"> on both the X and Y axis.
<clutter-rectangle> with <"name">layerB is
added to the <clutter-stage> with no explicit size;
<"x"> and <"width"> of layerB are bound to the
same properties of layerA using two
<clutter-bind-constraint> objects, thus keeping layerB
aligned to layerA;
<clutter-stage>; an offset
is given to the two <clutter-snap-constraint>s to allow for some
padding; since layerB is snapped between two different
<clutter-actor>s, its height is stretched to match the gap;
<clutter-rectangle> with <"name">layerC mirrors
layerB, snapping the top edge of the <clutter-stage> to
the top edge of layerC and the top edge of layerA to the
bottom edge of layerC;
You can try resizing interactively the <clutter-stage> and verify
that the three <clutter-actor>s maintain the same position and
size relative to each other, and to the <clutter-stage>.
It's important to note that Clutter does not avoid loops or competing
constraints; if two or more <clutter-constraint>s are operating
on the same positional or dimensional attributes of an actor, or if the
constraints on two different actors depend on each other, then the
behavior is undefined.
Creating a sub-class of <clutter-constraint> requires the
implementation of the update-allocation virtual function.
The update-allocation virtual function is called during
the allocation sequence of a <clutter-actor>, and allows any
<clutter-constraint> attached to that actor to modify the
allocation before it is passed to the allocate
implementation.
The <clutter-actor-box> passed to the
update-allocation implementation contains the original
allocation of the <clutter-actor>, plus the eventual
modifications applied by the other <clutter-constraint>s.
Constraints are queried in the same order as they were applied using
clutter-actor-add-constraint or
clutter-actor-add-constraint-with-name.
It is not necessary for a <clutter-constraint> sub-class to chain
up to the parent's implementation.
If a <clutter-constraint> is parametrized - i.e. if it contains
properties that affect the way the constraint is implemented - it should
call clutter-actor-queue-relayout on the actor to which it is
attached to whenever any parameter is changed. The actor to which it is
attached can be recovered at any point using
clutter-actor-meta-get-actor.
<clutter-constraint> is available since Clutter 1.4