Using a Layout Manager inside an Actor

In order to use a ClutterLayoutManager inside a ClutterActor sub-class you should invoke clutter_layout_manager_get_preferred_width() inside the ClutterActorClass.get_preferred_width() virtual function and clutter_layout_manager_get_preferred_height() inside the ClutterActorClass.get_preferred_height() virtual functions implementation. You should also call clutter_layout_manager_allocate() inside the implementation of the ClutterActorClass.allocate() virtual function.

In order to receive notifications for changes in the layout manager policies you should also connect to the "layout-changed" signal and queue a relayout on your actor. The following code should be enough if the actor does not need to perform specific operations whenever a layout manager changes:

1
2
3
4

g_signal_connect_swapped (layout_manager,
                          "layout-changed",
                          G_CALLBACK (clutter_actor_queue_relayout),
                          actor);

Implementing a ClutterLayoutManager

The implementation of a layout manager does not differ from the implementation of the size requisition and allocation bits of ClutterActor, so you should read the relative documentation for subclassing ClutterActor.

The layout manager implementation can hold a back pointer to the ClutterContainer by implementing the set_container() virtual function. The layout manager should not hold a real reference (i.e. call g_object_ref()) on the container actor, to avoid reference cycles.

If a layout manager has properties affecting the layout policies then it should emit the "layout-changed" signal on itself by using the clutter_layout_manager_layout_changed() function whenever one of these properties changes.

Animating a ClutterLayoutManager

A layout manager is used to let a ClutterContainer take complete ownership over the layout (that is: the position and sizing) of its children; this means that using the Clutter animation API, like clutter_actor_animate(), to animate the position and sizing of a child of a layout manager it is not going to work properly, as the animation will automatically override any setting done by the layout manager itself.

It is possible for a ClutterLayoutManager sub-class to animate its children layout by using the base class animation support. The ClutterLayoutManager animation support consists of three virtual functions: ClutterLayoutManagerClass.begin_animation(), ClutterLayoutManagerClass.get_animation_progress(), and ClutterLayoutManagerClass.end_animation().

The simplest way to animate a layout is to create a ClutterTimeline inside the begin_animation() virtual function, along with a ClutterAlpha, and for each "new-frame" signal emission call clutter_layout_manager_layout_changed(), which will cause a relayout. The "completed" signal emission should cause clutter_layout_manager_end_animation() to be called. The default implementation provided internally by ClutterLayoutManager does exactly this, so most sub-classes should either not override any animation-related virtual function or simply override ClutterLayoutManagerClass.begin_animation() and ClutterLayoutManagerClass.end_animation() to set up ad hoc state, and then chain up to the parent's implementation.

static void
my_layout_manager_allocate (ClutterLayoutManager   *manager,
                            ClutterContainer       *container,
                            const ClutterActorBox  *allocation,
                            ClutterAllocationFlags  flags)
{
  MyLayoutManager *self = MY_LAYOUT_MANAGER (manager);
  ClutterActor *child;

  for (child = clutter_actor_get_first_child (CLUTTER_ACTOR (container));
       child != NULL;
       child = clutter_actor_get_next_sibling (child))
    {
      ClutterLayoutMeta *meta;
      MyLayoutMeta *my_meta;

      /* retrieve the layout meta-object */
      meta = clutter_layout_manager_get_child_meta (manager,
                                                    container,
                                                    child);
      my_meta = MY_LAYOUT_META (meta);

      /* compute the desired allocation for the child */
      compute_allocation (self, my_meta, child,
                          allocation, flags,
                          &child_box);

      /* this is the additional code that deals with the animation
       * of the layout manager
       */
      if (!self->is_animating)
        {
          /* store the last stable allocation for later use */
          my_meta->last_alloc = clutter_actor_box_copy (&child_box);
        }
      else
        {
          ClutterActorBox end = { 0, };
          gdouble p;

          /* get the progress of the animation */
          p = clutter_layout_manager_get_animation_progress (manager);

          if (my_meta->last_alloc != NULL)
            {
              /* copy the desired allocation as the final state */
              end = child_box;

              /* then interpolate the initial and final state
               * depending on the progress of the animation,
               * and put the result inside the box we will use
               * to allocate the child
               */
              clutter_actor_box_interpolate (my_meta->last_alloc,
                                             &end,
                                             p,
                                             &child_box);
            }
          else
            {
              /* if there is no stable allocation then the child was
               * added while animating; one possible course of action
               * is to just bail out and fall through to the allocation
               * to position the child directly at its final state
               */
              my_meta->last_alloc =
                clutter_actor_box_copy (&child_box);
            }
        }

      /* allocate the child */
      clutter_actor_allocate (child, &child_box, flags);
    }
}
    

Sub-classes of ClutterLayoutManager that support animations of the layout changes should call clutter_layout_manager_begin_animation() whenever a layout property changes value, e.g.:

1
2
3
4
5
6
7
8
9
10
11
12

if (self->orientation != new_orientation)
  {
    ClutterLayoutManager *manager;

    self->orientation = new_orientation;

    manager = CLUTTER_LAYOUT_MANAGER (self);
    clutter_layout_manager_layout_changed (manager);
    clutter_layout_manager_begin_animation (manager, 500, CLUTTER_LINEAR);

    g_object_notify (G_OBJECT (self), "orientation");
  }

The code above will animate a change in the orientation layout property of a layout manager.

Layout Properties

If a layout manager has layout properties, that is properties that should exist only as the result of the presence of a specific (layout manager, container actor, child actor) combination, and it wishes to store those properties inside a ClutterLayoutMeta, then it should override the ClutterLayoutManagerClass.get_child_meta_type() virtual function to return the GType of the ClutterLayoutMeta sub-class used to store the layout properties; optionally, the ClutterLayoutManager sub-class might also override the ClutterLayoutManagerClass.create_child_meta() virtual function to control how the ClutterLayoutMeta instance is created, otherwise the default implementation will be equivalent to:

1
2
3
4
5
6
7
8
9
10
11

ClutterLayoutManagerClass *klass;
GType meta_type;

klass = CLUTTER_LAYOUT_MANAGER_GET_CLASS (manager);
meta_type = klass->get_child_meta_type (manager);

return g_object_new (meta_type,
                     "manager", manager,
                     "container", container,
                     "actor", actor,
                     NULL);

Where manager is the ClutterLayoutManager, container is the ClutterContainer using the ClutterLayoutManager and actor is the ClutterActor child of the ClutterContainer.

Using ClutterLayoutManager with ClutterScript

ClutterLayoutManager instance can be created in the same way as other objects in ClutterScript; properties can be set using the common syntax.

Layout properties can be set on children of a container with a ClutterLayoutManager using the layout:: modifier on the property name, for instance:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28

{
  "type" : "ClutterBox",
  "layout-manager" : { "type" : "ClutterTableLayout" },
  "children" : [
    {
      "type" : "ClutterTexture",
      "filename" : "image-00.png",

      "layout::row" : 0,
      "layout::column" : 0,
      "layout::x-align" : "left",
      "layout::y-align" : "center",
      "layout::x-expand" : true,
      "layout::y-expand" : true
    },
    {
      "type" : "ClutterTexture",
      "filename" : "image-01.png",

      "layout::row" : 0,
      "layout::column" : 1,
      "layout::x-align" : "right",
      "layout::y-align" : "center",
      "layout::x-expand" : true,
      "layout::y-expand" : true
    }
  ]
}

ClutterLayoutManager

typedef struct _ClutterLayoutManager ClutterLayoutManager;

The ClutterLayoutManager structure contains only private data and should be accessed using the provided API

Since 1.2

struct ClutterLayoutManagerClass

struct ClutterLayoutManagerClass {
  void               (* get_preferred_width)    (ClutterLayoutManager   *manager,
                                                 ClutterContainer       *container,
                                                 gfloat                  for_height,
                                                 gfloat                 *min_width_p,
                                                 gfloat                 *nat_width_p);
  void               (* get_preferred_height)   (ClutterLayoutManager   *manager,
                                                 ClutterContainer       *container,
                                                 gfloat                  for_width,
                                                 gfloat                 *min_height_p,
                                                 gfloat                 *nat_height_p);
  void               (* allocate)               (ClutterLayoutManager   *manager,
                                                 ClutterContainer       *container,
                                                 const ClutterActorBox  *allocation,
                                                 ClutterAllocationFlags  flags);

  void               (* set_container)          (ClutterLayoutManager   *manager,
                                                 ClutterContainer       *container);

  GType              (* get_child_meta_type)    (ClutterLayoutManager   *manager);
  ClutterLayoutMeta *(* create_child_meta)      (ClutterLayoutManager   *manager,
                                                 ClutterContainer       *container,
                                                 ClutterActor           *actor);

  /* deprecated */
  ClutterAlpha *     (* begin_animation)        (ClutterLayoutManager   *manager,
                                                 guint                   duration,
                                                 gulong                  mode);
  /* deprecated */
  gdouble            (* get_animation_progress) (ClutterLayoutManager   *manager);
  /* deprecated */
  void               (* end_animation)          (ClutterLayoutManager   *manager);

  void               (* layout_changed)         (ClutterLayoutManager   *manager);
};

The ClutterLayoutManagerClass structure contains only private data and should be accessed using the provided API

Since 1.2

clutter_layout_manager_get_preferred_width ()

void                clutter_layout_manager_get_preferred_width
                                                        (ClutterLayoutManager *manager,
                                                         ClutterContainer *container,
                                                         gfloat for_height,
                                                         gfloat *min_width_p,
                                                         gfloat *nat_width_p);

Computes the minimum and natural widths of the container according to manager.

See also clutter_actor_get_preferred_width()

Since 1.2

clutter_layout_manager_get_preferred_height ()

void                clutter_layout_manager_get_preferred_height
                                                        (ClutterLayoutManager *manager,
                                                         ClutterContainer *container,
                                                         gfloat for_width,
                                                         gfloat *min_height_p,
                                                         gfloat *nat_height_p);

Computes the minimum and natural heights of the container according to manager.

See also clutter_actor_get_preferred_height()

Since 1.2

clutter_layout_manager_allocate ()

void                clutter_layout_manager_allocate     (ClutterLayoutManager *manager,
                                                         ClutterContainer *container,
                                                         const ClutterActorBox *allocation,
                                                         ClutterAllocationFlags flags);

Allocates the children of container given an area

See also clutter_actor_allocate()

Since 1.2

clutter_layout_manager_layout_changed ()

void                clutter_layout_manager_layout_changed
                                                        (ClutterLayoutManager *manager);

Emits the "layout-changed" signal on manager

This function should only be called by implementations of the ClutterLayoutManager class

Since 1.2

clutter_layout_manager_set_container ()

void                clutter_layout_manager_set_container
                                                        (ClutterLayoutManager *manager,
                                                         ClutterContainer *container);

If the ClutterLayoutManager sub-class allows it, allow adding a weak reference of the container using manager from within the layout manager

The layout manager should not increase the reference count of the container

Since 1.2

clutter_layout_manager_get_child_meta ()

ClutterLayoutMeta * clutter_layout_manager_get_child_meta
                                                        (ClutterLayoutManager *manager,
                                                         ClutterContainer *container,
                                                         ClutterActor *actor);

Retrieves the ClutterLayoutMeta that the layout manager associated to the actor child of container, eventually by creating one if the ClutterLayoutManager supports layout properties

Since 1.0

clutter_layout_manager_child_set ()

void                clutter_layout_manager_child_set    (ClutterLayoutManager *manager,
                                                         ClutterContainer *container,
                                                         ClutterActor *actor,
                                                         const gchar *first_property,
                                                         ...);

Sets a list of properties and their values on the ClutterLayoutMeta associated by manager to a child of container

Languages bindings should use clutter_layout_manager_child_set_property() instead

Since 1.2

clutter_layout_manager_child_set_property ()

void                clutter_layout_manager_child_set_property
                                                        (ClutterLayoutManager *manager,
                                                         ClutterContainer *container,
                                                         ClutterActor *actor,
                                                         const gchar *property_name,
                                                         const GValue *value);

Sets a property on the ClutterLayoutMeta created by manager and attached to a child of container

Since 1.2

clutter_layout_manager_child_get ()

void                clutter_layout_manager_child_get    (ClutterLayoutManager *manager,
                                                         ClutterContainer *container,
                                                         ClutterActor *actor,
                                                         const gchar *first_property,
                                                         ...);

Retrieves the values for a list of properties out of the ClutterLayoutMeta created by manager and attached to the child of a container

Since 1.2

clutter_layout_manager_child_get_property ()

void                clutter_layout_manager_child_get_property
                                                        (ClutterLayoutManager *manager,
                                                         ClutterContainer *container,
                                                         ClutterActor *actor,
                                                         const gchar *property_name,
                                                         GValue *value);

Gets a property on the ClutterLayoutMeta created by manager and attached to a child of container

The GValue must already be initialized to the type of the property and has to be unset with g_value_unset() after extracting the real value out of it

Since 1.2

clutter_layout_manager_find_child_property ()

GParamSpec *        clutter_layout_manager_find_child_property
                                                        (ClutterLayoutManager *manager,
                                                         const gchar *name);

Retrieves the GParamSpec for the layout property name inside the ClutterLayoutMeta sub-class used by manager

Since 1.2

clutter_layout_manager_list_child_properties ()

GParamSpec **       clutter_layout_manager_list_child_properties
                                                        (ClutterLayoutManager *manager,
                                                         guint *n_pspecs);

Retrieves all the GParamSpecs for the layout properties stored inside the ClutterLayoutMeta sub-class used by manager

Since 1.2

clutter_layout_manager_begin_animation ()

ClutterAlpha *      clutter_layout_manager_begin_animation
                                                        (ClutterLayoutManager *manager,
                                                         guint duration,
                                                         gulong mode);

Begins an animation of duration milliseconds, using the provided easing mode

The easing mode can be specified either as a ClutterAnimationMode or as a logical id returned by clutter_alpha_register_func()

The result of this function depends on the manager implementation

Since 1.2

clutter_layout_manager_end_animation ()

void                clutter_layout_manager_end_animation
                                                        (ClutterLayoutManager *manager);

Ends an animation started by clutter_layout_manager_begin_animation()

The result of this call depends on the manager implementation

Since 1.2

clutter_layout_manager_get_animation_progress ()

gdouble             clutter_layout_manager_get_animation_progress
                                                        (ClutterLayoutManager *manager);

Retrieves the progress of the animation, if one has been started by clutter_layout_manager_begin_animation()

The returned value has the same semantics of the "alpha" value

Since 1.2

The "layout-changed" signal

void                user_function                      (ClutterLayoutManager *manager,
                                                        gpointer              user_data)      : Run Last

The ::layout-changed signal is emitted each time a layout manager has been changed. Every ClutterActor using the manager instance as a layout manager should connect a handler to the ::layout-changed signal and queue a relayout on themselves:

1
2
3
4
5
6
7
8
9
10

static void layout_changed (ClutterLayoutManager *manager,
                            ClutterActor         *self)
{
  clutter_actor_queue_relayout (self);
}
...
  self->manager = g_object_ref_sink (manager);
  g_signal_connect (self->manager, "layout-changed",
                    G_CALLBACK (layout_changed),
                    self);

Sub-classes of ClutterLayoutManager that implement a layout that can be controlled or changed using parameters should emit the ::layout-changed signal whenever one of the parameters changes, by using clutter_layout_manager_layout_changed().

Since 1.2