Next: , Previous: Colors, Up: Top

24 ClutterConstraint

Abstract class for constraints on position or size

24.1 Overview

<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.

24.2 Using Constraints

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:

this constraint binds the X, Y, width or height of an actor to the corresponding position or size of a source actor; it can also apply an offset.
this constraint "snaps" together the edges of two <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.

  1. The <clutter-rectangle> with <"name">layerA is explicitly sized to 100 pixels by 25 pixels, and it's added to the <clutter-stage>;
  2. two <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.
  3. the <clutter-rectangle> with <"name">layerB is added to the <clutter-stage> with no explicit size;
  4. the <"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;
  5. the top edge of layerB is snapped together with the bottom edge of layerA; the bottom edge of layerB is also snapped together with the bottom edge of the <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;
  6. the <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.

24.3 Implementing a ClutterConstraint

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

24.4 Usage