ClutterLayout

ClutterLayout — An interface for implementing layouts

Synopsis




                    ClutterLayoutIface;
enum                ClutterLayoutFlags;
ClutterLayoutFlags  clutter_layout_get_layout_flags     (ClutterLayout *layout);
void                clutter_layout_height_for_width     (ClutterLayout *layout,
                                                         gint width,
                                                         gint *height);
void                clutter_layout_natural_request      (ClutterLayout *layout,
                                                         gint *width,
                                                         gint *height);
void                clutter_layout_tune_request         (ClutterLayout *layout,
                                                         gint given_width,
                                                         gint given_height,
                                                         gint *width,
                                                         gint *height);
void                clutter_layout_width_for_height     (ClutterLayout *layout,
                                                         gint *width,
                                                         gint height);


Description

ClutterLayout is an interface that ClutterActors might implement to provide complex or extended layouts. The default size allocation of a ClutterActor inside a ClutterGroup is to make the group size allocation grow enough to contain the actor. A ClutterActor implementing the ClutterLayout interface will be queried for its size when it is added to a ClutterGroup subclass that honours the ClutterLayout interface; the resulting size allocation will depend on the ClutterLayoutFlags that the actor supports.

There are various types of layout available for actors implementing the ClutterLayout interface: CLUTTER_LAYOUT_WIDTH_FOR_HEIGHT will ask the actor for its width given the height allocated by the container; CLUTTER_LAYOUT_HEIGHT_FOR_WIDTH will ask the actor for its height given the width allocated by the container. These two layout types are especially useful for labels and unidirectional container types, like vertical and horizontal boxes.

Another layout available is CLUTTER_LAYOUT_NATURAL, which will query the actor for its natural (default) width and height; the container actor will then try to allocate as much as it can, and might resort to scaling the actor to fit the allocation. This layout type is suited for ClutterTextures and shapes.

Finally, the CLUTTER_LAYOUT_TUNABLE is an iterative layout. An actor will be queried multiple times until it's satisfied with the size given.

A ClutterGroup subclass that honours the ClutterLayout interface should check whether an actor is implementing this interface when adding it, by using the CLUTTER_IS_LAYOUT type check macro. If the actor does implement the interface, the ClutterGroup should get the supported layouts using clutter_layout_get_layout_flags() and verify which layout is compatible with the group's own layout; for instance, vertical containers should check for actors implementing the CLUTTER_LAYOUT_WIDTH_FOR_HEIGHT layout management, while horizontal containers should check for actors implementing the CLUTTER_LAYOUT_HEIGHT_FOR_WIDTH layout management. If the actor satisfies the layout requirements, the container actor should query the actor for a geometry request using the appropriate function and allocate space for the newly added actor accordingly.

ClutterLayout is available since Clutter 0.4

Details

ClutterLayoutIface

typedef struct {
  /* Retrieve the layout mode used by the actor */
  ClutterLayoutFlags (* get_layout_flags) (ClutterLayout *layout);
  
  /* Width-for-Height and Height-for-Width: one size is known
   * and the other is queried. useful for labels and unidirectional
   * containers, like vertical and horizontal boxes.
   */
  void               (* width_for_height) (ClutterLayout *layout,
                                           ClutterUnit   *width,
                                           ClutterUnit    height);
  void               (* height_for_width) (ClutterLayout *layout,
                                           ClutterUnit    width,
                                           ClutterUnit   *height);

  /* Natural size request: the actor is queried for its natural
   * size and the container can decide to either scale the actor
   * or to resize itself to make it fit. useful for textures
   * or shapes.
   */
  void               (* natural_request)  (ClutterLayout *layout,
                                           ClutterUnit   *width,
                                           ClutterUnit   *height);

  /* Iterative allocation: the actor is iteratively queried
   * for its size, until it finds it.
   */
  gboolean           (* tune_request)     (ClutterLayout *layout,
                                           ClutterUnit    given_width,
                                           ClutterUnit    given_height,
                                           ClutterUnit   *width,
                                           ClutterUnit   *height);
} ClutterLayoutIface;

Interface for extended layout support in actors.

get_layout_flags () Retrieve the layout mode used by the actor
width_for_height () Compute width for a given height
height_for_width () Compute height for a given width
natural_request () Natural size of an actor
tune_request () Iterative size allocation

Since 0.4


enum ClutterLayoutFlags

typedef enum {
  CLUTTER_LAYOUT_NONE             = 0,
  CLUTTER_LAYOUT_WIDTH_FOR_HEIGHT = 1 << 0,
  CLUTTER_LAYOUT_HEIGHT_FOR_WIDTH = 1 << 1,
  CLUTTER_LAYOUT_NATURAL          = 1 << 2,
  CLUTTER_LAYOUT_TUNABLE          = 1 << 3
} ClutterLayoutFlags;

Type of layouts supported by an actor.

CLUTTER_LAYOUT_NONE No layout (default behaviour)
CLUTTER_LAYOUT_WIDTH_FOR_HEIGHT Width-for-height
CLUTTER_LAYOUT_HEIGHT_FOR_WIDTH Height-for-width
CLUTTER_LAYOUT_NATURAL Natural size request
CLUTTER_LAYOUT_TUNABLE Tunable size request

Since 0.4


clutter_layout_get_layout_flags ()

ClutterLayoutFlags  clutter_layout_get_layout_flags     (ClutterLayout *layout);

Retrieves the supported layout types from the ClutterLayout

layout : a ClutterLayout
Returns : bitwise or of ClutterLayoutFlags

Since 0.4


clutter_layout_height_for_width ()

void                clutter_layout_height_for_width     (ClutterLayout *layout,
                                                         gint width,
                                                         gint *height);

Queries a ClutterLayout actor for its height with a known width.

layout : a ClutterLayout
width : width allocated by the parent
height : return location for the height

Since 0.4


clutter_layout_natural_request ()

void                clutter_layout_natural_request      (ClutterLayout *layout,
                                                         gint *width,
                                                         gint *height);

Queries a ClutterLayout actor for its natural (default) width and height.

layout : a ClutterLayout
width : return location for the natural width
height : return location for the natural height

Since 0.4


clutter_layout_tune_request ()

void                clutter_layout_tune_request         (ClutterLayout *layout,
                                                         gint given_width,
                                                         gint given_height,
                                                         gint *width,
                                                         gint *height);

Iteratively queries a ClutterLayout actor until it finds its desired size, given a width and height tuple.

layout : a ClutterLayout
given_width : width allocated by the parent
given_height : height allocated by the parent
width : return location for the new width
height : return location for the new height

Since 0.4


clutter_layout_width_for_height ()

void                clutter_layout_width_for_height     (ClutterLayout *layout,
                                                         gint *width,
                                                         gint height);

Queries a ClutterLayout actor for its width with a known height.

layout : a ClutterLayout
width : return location for the width
height : height allocated by the parent

Since 0.4