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 forr subclassing ClutterActor.

The layout manager implementation can hold a back pointer to the ClutterContainer by implementing the ClutterLayoutManagerClass.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.

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 instances 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 is available since Clutter 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

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

The “layout-changed” signal

void
user_function (ClutterLayoutManager *manager,
               gpointer              user_data)

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

Flags: Run Last

Since: 1.2