ClutterLayoutManager

ClutterLayoutManager — Layout managers base class

Synopsis

                    ClutterLayoutManager;
                    ClutterLayoutManagerClass;
void                clutter_layout_manager_get_preferred_width
                                                        (ClutterLayoutManager *manager,
                                                         ClutterContainer *container,
                                                         gfloat for_height,
                                                         gfloat *min_width_p,
                                                         gfloat *nat_width_p);
void                clutter_layout_manager_get_preferred_height
                                                        (ClutterLayoutManager *manager,
                                                         ClutterContainer *container,
                                                         gfloat for_width,
                                                         gfloat *min_height_p,
                                                         gfloat *nat_height_p);
void                clutter_layout_manager_allocate     (ClutterLayoutManager *manager,
                                                         ClutterContainer *container,
                                                         const ClutterActorBox *allocation,
                                                         ClutterAllocationFlags flags);
void                clutter_layout_manager_layout_changed
                                                        (ClutterLayoutManager *manager);
void                clutter_layout_manager_set_container
                                                        (ClutterLayoutManager *manager,
                                                         ClutterContainer *container);

void                clutter_layout_manager_add_child_meta
                                                        (ClutterLayoutManager *manager,
                                                         ClutterContainer *container,
                                                         ClutterActor *actor);
void                clutter_layout_manager_remove_child_meta
                                                        (ClutterLayoutManager *manager,
                                                         ClutterContainer *container,
                                                         ClutterActor *actor);
ClutterLayoutMeta * clutter_layout_manager_get_child_meta
                                                        (ClutterLayoutManager *manager,
                                                         ClutterContainer *container,
                                                         ClutterActor *actor);
void                clutter_layout_manager_child_set    (ClutterLayoutManager *manager,
                                                         ClutterContainer *container,
                                                         ClutterActor *actor,
                                                         const gchar *first_property,
                                                         ...);
void                clutter_layout_manager_child_set_property
                                                        (ClutterLayoutManager *manager,
                                                         ClutterContainer *container,
                                                         ClutterActor *actor,
                                                         const gchar *property_name,
                                                         const GValue *value);
void                clutter_layout_manager_child_get    (ClutterLayoutManager *manager,
                                                         ClutterContainer *container,
                                                         ClutterActor *actor,
                                                         const gchar *first_property,
                                                         ...);
void                clutter_layout_manager_child_get_property
                                                        (ClutterLayoutManager *manager,
                                                         ClutterContainer *container,
                                                         ClutterActor *actor,
                                                         const gchar *property_name,
                                                         GValue *value);

Object Hierarchy

  GObject
   +----GInitiallyUnowned
         +----ClutterLayoutManager
               +----ClutterFixedLayout
               +----ClutterBinLayout
               +----ClutterFlowLayout
               +----ClutterBoxLayout

Signals

  "layout-changed"                                 : Run Last

Description

ClutterLayoutManager is a base abstract class for layout managers. A layout manager implements the layouting policy for a composite or a container actor: it controls the preferred size of the actor to which it has been paired, and it controls the allocation of its children.

Any composite or container ClutterActor subclass can delegate the layouting of its children to a ClutterLayoutManager. Clutter provides a generic container using ClutterLayoutManager called ClutterBox.

Clutter provides some simple ClutterLayoutManager sub-classes, like ClutterFixedLayout and ClutterBinLayout.

Using ClutterLayoutManager 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 ClutterActor::get_preferred_width() virtual function and clutter_layout_manager_get_preferred_height() inside the ClutterActor::get_preferred_height() virtual function implementations. You should also call clutter_layout_manager_allocate() inside the implementation of the ClutterActor::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:

  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 reference to the ClutterContainer by implementing the set_container() virtual function. The layout manager should not hold a reference on the container actor, to avoid reference cycles.

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

ClutterLayoutManager is available since Clutter 1.2

Details

ClutterLayoutManager

typedef struct _ClutterLayoutManager ClutterLayoutManager;

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

Since 1.2


ClutterLayoutManagerClass

typedef struct {
  void               (* get_preferred_width)  (ClutterLayoutManager   *manager,
                                               ClutterContainer       *container,
                                               gfloat                  for_height,
                                               gfloat                 *minimum_width_p,
                                               gfloat                 *natural_width_p);
  void               (* get_preferred_height) (ClutterLayoutManager   *manager,
                                               ClutterContainer       *container,
                                               gfloat                  for_width,
                                               gfloat                 *minimum_height_p,
                                               gfloat                 *natural_height_p);
  void               (* allocate)             (ClutterLayoutManager   *manager,
                                               ClutterContainer       *container,
                                               const ClutterActorBox  *allocation,
                                               ClutterAllocationFlags  flags);

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

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

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

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

get_preferred_width ()

virtual function; override to provide a preferred width for the layout manager. See also the get_preferred_width() virtual function in ClutterActor

get_preferred_height ()

virtual function; override to provide a preferred height for the layout manager. See also the get_preferred_height() virtual function in ClutterActor

allocate ()

virtual function; override to allocate the children of the layout manager. See also the allocate() virtual function in ClutterActor

set_container ()

virtual function; override to set a back pointer on the ClutterContainer using the layout manager. The implementation should not take a reference on the container, but just take a weak reference, to avoid potential leaks due to reference cycles

create_child_meta ()

virtual function; override to create a ClutterChildMeta instance associated to a ClutterContainer and a child ClutterActor, used to maintain layout manager specific properties

layout_changed ()

class handler for the "layout-changed" signal

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

manager :

a ClutterLayoutManager

container :

the ClutterContainer using manager

for_height :

the height for which the width should be computed, or -1

min_width_p :

out) (allow-none. out. allow-none.

nat_width_p :

out) (allow-none. out. allow-none.

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

manager :

a ClutterLayoutManager

container :

the ClutterContainer using manager

for_width :

the width for which the height should be computed, or -1

min_height_p :

out) (allow-none. out. allow-none.

nat_height_p :

out) (allow-none. out. allow-none.

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

manager :

a ClutterLayoutManager

container :

the ClutterContainer using manager

allocation :

the ClutterActorBox containing the allocated area of container

flags :

the allocation flags

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

manager :

a ClutterLayoutManager

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

manager :

a ClutterLayoutManager

container :

a ClutterContainer using manager. allow-none.

Since 1.2


clutter_layout_manager_add_child_meta ()

void                clutter_layout_manager_add_child_meta
                                                        (ClutterLayoutManager *manager,
                                                         ClutterContainer *container,
                                                         ClutterActor *actor);

Creates and binds a ClutterLayoutMeta for manager to a child of container

This function should only be used when implementing containers using ClutterLayoutManager and not by application code

Typically, containers should bind a ClutterLayoutMeta created by a ClutterLayoutManager when adding a new child, e.g.:

  static void
  my_container_add (ClutterContainer *container,
                    ClutterActor     *actor)
  {
    MyContainer *self = MY_CONTAINER (container);

    self->children = g_slist_append (self->children, actor);
    clutter_actor_set_parent (actor, CLUTTER_ACTOR (self));

    clutter_layout_manager_add_child_meta (self->layout,
                                           container,
                                           actor);

    clutter_actor_queue_relayout (CLUTTER_ACTOR (self));

    g_signal_emit_by_name (container, "actor-added");
  }

The ClutterLayoutMeta should be removed when removing an actor; see clutter_layout_manager_remove_child_meta()

manager :

a ClutterLayoutManager

container :

a ClutterContainer using manager

actor :

a ClutterActor child of container

Since 1.2


clutter_layout_manager_remove_child_meta ()

void                clutter_layout_manager_remove_child_meta
                                                        (ClutterLayoutManager *manager,
                                                         ClutterContainer *container,
                                                         ClutterActor *actor);

Unbinds and unrefs a ClutterLayoutMeta for manager from a child of container

This function should only be used when implementing containers using ClutterLayoutManager and not by application code

Typically, containers should remove a ClutterLayoutMeta created by a ClutterLayoutManager when removing a child, e.g.:

  static void
  my_container_remove (ClutterContainer *container,
                       ClutterActor     *actor)
  {
    MyContainer *self = MY_CONTAINER (container);

    g_object_ref (actor);

    self->children = g_slist_remove (self->children, actor);
    clutter_actor_unparent (actor);

    clutter_layout_manager_remove_child_meta (self->layout,
                                              container,
                                              actor);

    clutter_actor_queue_relayout (CLUTTER_ACTOR (self));

    g_signal_emit_by_name (container, "actor-removed");

    g_object_unref (actor);
  }

See also clutter_layout_manager_add_child_meta()

manager :

a ClutterLayoutManager

container :

a ClutterContainer using manager

actor :

a ClutterActor child of 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

manager :

a ClutterLayoutManager

container :

a ClutterContainer using manager

actor :

a ClutterActor child of container

Returns :

a ClutterLayoutMeta or NULL

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

manager :

a ClutterLayoutManager

container :

a ClutterContainer using manager

actor :

a ClutterActor child of container

first_property :

the first property name

... :

a list of property name and value pairs

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

manager :

a ClutterLayoutManager

container :

a ClutterContainer using manager

actor :

a ClutterActor child of container

property_name :

the name of the property to set

value :

a GValue with the value of the property to set

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

manager :

a ClutterLayoutManager

container :

a ClutterContainer using manager

actor :

a ClutterActor child of container

first_property :

the name of the first property

... :

a list of property name and return location for the value pairs

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

manager :

a ClutterLayoutManager

container :

a ClutterContainer using manager

actor :

a ClutterActor child of container

property_name :

the name of the property to get

value :

a GValue with the value of the property to get

Since 1.2

Signal Details

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:

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

manager :

the ClutterLayoutManager that emitted the signal

user_data :

user data set when the signal handler was connected.

Since 1.2