ClutterBoxLayout

## ClutterBoxLayout ClutterBoxLayout — A layout manager arranging children on a single line |

## Synopsis

    enum                ClutterBoxAlignment;
    struct              ClutterBoxLayout;
    struct              ClutterBoxLayoutClass;
    ClutterLayoutManager * clutter_box_layout_new           (void);
    void                clutter_box_layout_set_pack_start   (ClutterBoxLayout *layout,
                                                             gboolean pack_start);
    gboolean            clutter_box_layout_get_pack_start   (ClutterBoxLayout *layout);
    void                clutter_box_layout_set_spacing      (ClutterBoxLayout *layout,
                                                             guint spacing);
    guint               clutter_box_layout_get_spacing      (ClutterBoxLayout *layout);
    void                clutter_box_layout_set_vertical     (ClutterBoxLayout *layout,
                                                             gboolean vertical);
    gboolean            clutter_box_layout_get_vertical     (ClutterBoxLayout *layout);
    void                clutter_box_layout_set_homogeneous  (ClutterBoxLayout *layout,
                                                             gboolean homogeneous);
    gboolean            clutter_box_layout_get_homogeneous  (ClutterBoxLayout *layout);

    void                clutter_box_layout_pack             (ClutterBoxLayout *layout,
                                                             ClutterActor *actor,
                                                             gboolean expand,
                                                             gboolean x_fill,
                                                             gboolean y_fill,
                                                             ClutterBoxAlignment x_align,
                                                             ClutterBoxAlignment y_align);

    void                clutter_box_layout_set_alignment    (ClutterBoxLayout *layout,
                                                             ClutterActor *actor,
                                                             ClutterBoxAlignment x_align,
                                                             ClutterBoxAlignment y_align);
    void                clutter_box_layout_get_alignment    (ClutterBoxLayout *layout,
                                                             ClutterActor *actor,
                                                             ClutterBoxAlignment *x_align,
                                                             ClutterBoxAlignment *y_align);
    void                clutter_box_layout_set_expand       (ClutterBoxLayout *layout,
                                                             ClutterActor *actor,
                                                             gboolean expand);
    gboolean            clutter_box_layout_get_expand       (ClutterBoxLayout *layout,
                                                             ClutterActor *actor);
    void                clutter_box_layout_set_fill         (ClutterBoxLayout *layout,
                                                             ClutterActor *actor,
                                                             gboolean x_fill,
                                                             gboolean y_fill);
    void                clutter_box_layout_get_fill         (ClutterBoxLayout *layout,
                                                             ClutterActor *actor,
                                                             gboolean *x_fill,
                                                             gboolean *y_fill);

    void                clutter_box_layout_set_use_animations
                                                            (ClutterBoxLayout *layout,
                                                             gboolean animate);
    gboolean            clutter_box_layout_get_use_animations
                                                            (ClutterBoxLayout *layout);
    void                clutter_box_layout_set_easing_duration
                                                            (ClutterBoxLayout *layout,
                                                             guint msecs);
    guint               clutter_box_layout_get_easing_duration
                                                            (ClutterBoxLayout *layout);
    void                clutter_box_layout_set_easing_mode  (ClutterBoxLayout *layout,
                                                             gulong mode);
    gulong              clutter_box_layout_get_easing_mode  (ClutterBoxLayout *layout);

## Object Hierarchy

      GObject
       +----GInitiallyUnowned
             +----ClutterLayoutManager
                   +----ClutterBoxLayout

## Properties

      "easing-duration"          guint                 : Read / Write
      "easing-mode"              gulong                : Read / Write
      "homogeneous"              gboolean              : Read / Write
      "pack-start"               gboolean              : Read / Write
      "spacing"                  guint                 : Read / Write
      "use-animations"           gboolean              : Read / Write
      "vertical"                 gboolean              : Read / Write

## Description

The ClutterBoxLayout is a ClutterLayoutManager implementing the following layout policy:

- all children are arranged on a single line;

- the axis used is controlled by the "vertical" boolean property;

- the order of the packing is determined by the "pack-start" boolean property;

- each child will be allocated to its natural size or, if set to expand, the available size;

- if a child is set to fill on either (or both) axis, its allocation will match all the available size; the fill layout property only makes sense if the expand property is also set;

- if a child is set to expand but not to fill then it is possible to control the alignment using the X and Y alignment layout properties.

- if the "homogeneous" boolean property is set, then all widgets will get the same size, ignoring expand settings and the preferred sizes

Figure 6. Box layout

The image shows a ClutterBoxLayout with the "vertical" property set to `FALSE`.

It is possible to control the spacing between children of a ClutterBoxLayout by using `clutter_box_layout_set_spacing()`.

In order to set the layout properties when packing an actor inside a ClutterBoxLayout you should use the `clutter_box_layout_pack()` function.

ClutterBoxLayout is available since Clutter 1.2

## Details

### enum ClutterBoxAlignment

    typedef enum {
      CLUTTER_BOX_ALIGNMENT_START,
      CLUTTER_BOX_ALIGNMENT_END,
      CLUTTER_BOX_ALIGNMENT_CENTER
    } ClutterBoxAlignment;

The alignment policies available on each axis of the ClutterBoxLayout

`CLUTTER_BOX_ALIGNMENT_START` | Align the child to the top or to to the left, depending on the used axis
`CLUTTER_BOX_ALIGNMENT_END` | Align the child to the bottom or to the right, depending on the used axis
`CLUTTER_BOX_ALIGNMENT_CENTER` | Align the child to the center

Since 1.2

### struct ClutterBoxLayout

    struct ClutterBoxLayout;

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

Since 1.2

### struct ClutterBoxLayoutClass

    struct ClutterBoxLayoutClass {
    };

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

Since 1.2

### clutter_box_layout_new ()

    ClutterLayoutManager * clutter_box_layout_new           (void);

Creates a new ClutterBoxLayout layout manager

Returns : | the newly created ClutterBoxLayout

Since 1.2

### clutter_box_layout_set_pack_start ()

    void                clutter_box_layout_set_pack_start   (ClutterBoxLayout *layout,
                                                             gboolean pack_start);

Sets whether children of `layout` should be layed out by appending them or by prepending them

`layout` : | a ClutterBoxLayout
`pack_start` : | `TRUE` if the `layout` should pack children at the beginning of the layout

Since 1.2

### clutter_box_layout_get_pack_start ()

    gboolean            clutter_box_layout_get_pack_start   (ClutterBoxLayout *layout);

Retrieves the value set using `clutter_box_layout_set_pack_start()`

`layout` : | a ClutterBoxLayout
Returns : | `TRUE` if the ClutterBoxLayout should pack children at the beginning of the layout, and `FALSE` otherwise

Since 1.2

### clutter_box_layout_set_spacing ()

    void                clutter_box_layout_set_spacing      (ClutterBoxLayout *layout,
                                                             guint spacing);

Sets the spacing between children of `layout`

`layout` : | a ClutterBoxLayout
`spacing` : | the spacing between children of the layout, in pixels

Since 1.2

### clutter_box_layout_get_spacing ()

    guint               clutter_box_layout_get_spacing      (ClutterBoxLayout *layout);

Retrieves the spacing set using `clutter_box_layout_set_spacing()`

`layout` : | a ClutterBoxLayout
Returns : | the spacing between children of the ClutterBoxLayout

Since 1.2

### clutter_box_layout_set_vertical ()

    void                clutter_box_layout_set_vertical     (ClutterBoxLayout *layout,
                                                             gboolean vertical);

Sets whether `layout` should arrange its children vertically alongside the Y axis, instead of horizontally alongside the X axis

`layout` : | a ClutterBoxLayout
`vertical` : | `TRUE` if the layout should be vertical

Since 1.2

### clutter_box_layout_get_vertical ()

    gboolean            clutter_box_layout_get_vertical     (ClutterBoxLayout *layout);

Retrieves the orientation of the `layout` as set using the `clutter_box_layout_set_vertical()` function

`layout` : | a ClutterBoxLayout
Returns : | `TRUE` if the ClutterBoxLayout is arranging its children vertically, and `FALSE` otherwise

Since 1.2

### clutter_box_layout_set_homogeneous ()

    void                clutter_box_layout_set_homogeneous  (ClutterBoxLayout *layout,
                                                             gboolean homogeneous);

Sets whether the size of `layout` children should be homogeneous

`layout` : | a ClutterBoxLayout
`homogeneous` : | `TRUE` if the layout should be homogeneous

Since 1.4

### clutter_box_layout_get_homogeneous ()

    gboolean            clutter_box_layout_get_homogeneous  (ClutterBoxLayout *layout);

Retrieves if the children sizes are allocated homogeneously.

`layout` : | a ClutterBoxLayout
Returns : | `TRUE` if the ClutterBoxLayout is arranging its children homogeneously, and `FALSE` otherwise

Since 1.4

### clutter_box_layout_pack ()

    void                clutter_box_layout_pack             (ClutterBoxLayout *layout,
                                                             ClutterActor *actor,
                                                             gboolean expand,
                                                             gboolean x_fill,
                                                             gboolean y_fill,
                                                             ClutterBoxAlignment x_align,
                                                             ClutterBoxAlignment y_align);

Packs `actor` inside the ClutterContainer associated to `layout` and sets the layout properties

`layout` : | a ClutterBoxLayout
`actor` : | a ClutterActor
`expand` : | whether the `actor` should expand
`x_fill` : | whether the `actor` should fill horizontally
`y_fill` : | whether the `actor` should fill vertically
`x_align` : | the horizontal alignment policy for `actor`
`y_align` : | the vertical alignment policy for `actor`

Since 1.2

### clutter_box_layout_set_alignment ()

    void                clutter_box_layout_set_alignment    (ClutterBoxLayout *layout,
                                                             ClutterActor *actor,
                                                             ClutterBoxAlignment x_align,
                                                             ClutterBoxAlignment y_align);

Sets the horizontal and vertical alignment policies for `actor` inside `layout`

`layout` : | a ClutterBoxLayout
`actor` : | a ClutterActor child of `layout`
`x_align` : | Horizontal alignment policy for `actor`
`y_align` : | Vertical alignment policy for `actor`

Since 1.2

### clutter_box_layout_get_alignment ()

    void                clutter_box_layout_get_alignment    (ClutterBoxLayout *layout,
                                                             ClutterActor *actor,
                                                             ClutterBoxAlignment *x_align,
                                                             ClutterBoxAlignment *y_align);

Retrieves the horizontal and vertical alignment policies for `actor` as set using `clutter_box_layout_pack()` or `clutter_box_layout_set_alignment()`

`layout` : | a ClutterBoxLayout
`actor` : | a ClutterActor child of `layout`
`x_align` : | return location for the horizontal alignment policy. [out]
`y_align` : | return location for the vertical alignment policy. [out]

Since 1.2

### clutter_box_layout_set_expand ()

    void                clutter_box_layout_set_expand       (ClutterBoxLayout *layout,
                                                             ClutterActor *actor,
                                                             gboolean expand);

Sets whether `actor` should expand inside `layout`

`layout` : | a ClutterBoxLayout
`actor` : | a ClutterActor child of `layout`
`expand` : | whether `actor` should expand

Since 1.2

### clutter_box_layout_get_expand ()

    gboolean            clutter_box_layout_get_expand       (ClutterBoxLayout *layout,
                                                             ClutterActor *actor);

Retrieves whether `actor` should expand inside `layout`

`layout` : | a ClutterBoxLayout
`actor` : | a ClutterActor child of `layout`
Returns : | `TRUE` if the ClutterActor should expand, `FALSE` otherwise

Since 1.2

### clutter_box_layout_set_fill ()

    void                clutter_box_layout_set_fill         (ClutterBoxLayout *layout,
                                                             ClutterActor *actor,
                                                             gboolean x_fill,
                                                             gboolean y_fill);

Sets the horizontal and vertical fill policies for `actor` inside `layout`

`layout` : | a ClutterBoxLayout
`actor` : | a ClutterActor child of `layout`
`x_fill` : | whether `actor` should fill horizontally the allocated space
`y_fill` : | whether `actor` should fill vertically the allocated space

Since 1.2

### clutter_box_layout_get_fill ()

    void                clutter_box_layout_get_fill         (ClutterBoxLayout *layout,
                                                             ClutterActor *actor,
                                                             gboolean *x_fill,
                                                             gboolean *y_fill);

Retrieves the horizontal and vertical fill policies for `actor` as set using `clutter_box_layout_pack()` or `clutter_box_layout_set_fill()`

`layout` : | a ClutterBoxLayout
`actor` : | a ClutterActor child of `layout`
`x_fill` : | return location for the horizontal fill policy. [out]
`y_fill` : | return location for the vertical fill policy. [out]

Since 1.2

### clutter_box_layout_set_use_animations ()

    void                clutter_box_layout_set_use_animations
                                                            (ClutterBoxLayout *layout,
                                                             gboolean animate);

Sets whether `layout` should animate changes in the layout properties

The duration of the animations is controlled by `clutter_box_layout_set_easing_duration()`; the easing mode to be used by the animations is controlled by `clutter_box_layout_set_easing_mode()`

`layout` : | a ClutterBoxLayout
`animate` : | `TRUE` if the `layout` should use animations

Since 1.2

### clutter_box_layout_get_use_animations ()

    gboolean            clutter_box_layout_get_use_animations
                                                            (ClutterBoxLayout *layout);

Retrieves whether `layout` should animate changes in the layout properties

Since `clutter_box_layout_set_use_animations()`

`layout` : | a ClutterBoxLayout
Returns : | `TRUE` if the animations should be used, `FALSE` otherwise

Since 1.2

### clutter_box_layout_set_easing_duration ()

    void                clutter_box_layout_set_easing_duration
                                                            (ClutterBoxLayout *layout,
                                                             guint msecs);

Sets the duration of the animations used by `layout` when animating changes in the layout properties

Use `clutter_box_layout_set_use_animations()` to enable and disable the animations

`layout` : | a ClutterBoxLayout
`msecs` : | the duration of the animations, in milliseconds

Since 1.2

### clutter_box_layout_get_easing_duration ()

    guint               clutter_box_layout_get_easing_duration
                                                            (ClutterBoxLayout *layout);

Retrieves the duration set using `clutter_box_layout_set_easing_duration()`

`layout` : | a ClutterBoxLayout
Returns : | the duration of the animations, in milliseconds

Since 1.2

### clutter_box_layout_set_easing_mode ()

    void                clutter_box_layout_set_easing_mode  (ClutterBoxLayout *layout,
                                                             gulong mode);

Sets the easing mode to be used by `layout` when animating changes in layout properties

Use `clutter_box_layout_set_use_animations()` to enable and disable the animations

`layout` : | a ClutterBoxLayout
`mode` : | an easing mode, either from ClutterAnimationMode or a logical id from `clutter_alpha_register_func()`

Since 1.2

### clutter_box_layout_get_easing_mode ()

    gulong              clutter_box_layout_get_easing_mode  (ClutterBoxLayout *layout);

Retrieves the easing mode set using `clutter_box_layout_set_easing_mode()`

`layout` : | a ClutterBoxLayout
Returns : | an easing mode

Since 1.2

## Property Details

### The `"easing-duration"` property

      "easing-duration"          guint                 : Read / Write

The duration of the animations, in case "use-animations" is set to `TRUE`

The duration is expressed in milliseconds

Default value: 500

Since 1.2

### The `"easing-mode"` property

      "easing-mode"              gulong                : Read / Write

The easing mode for the animations, in case "use-animations" is set to `TRUE`

The easing mode has the same semantics of "mode": it can either be a value from the ClutterAnimationMode enumeration, like `CLUTTER_EASE_OUT_CUBIC`, or a logical id as returned by `clutter_alpha_register_func()`

The default value is `CLUTTER_EASE_OUT_CUBIC`

Since 1.2

### The `"homogeneous"` property

      "homogeneous"              gboolean              : Read / Write

Whether the ClutterBoxLayout should arrange its children homogeneously, i.e. all childs get the same size

Default value: FALSE

Since 1.4

### The `"pack-start"` property

      "pack-start"               gboolean              : Read / Write

Whether the ClutterBoxLayout should pack items at the start or append them at the end

Default value: FALSE

Since 1.2

### The `"spacing"` property

      "spacing"                  guint                 : Read / Write

The spacing between children of the ClutterBoxLayout, in pixels

Default value: 0

Since 1.2

### The `"use-animations"` property

      "use-animations"           gboolean              : Read / Write

Whether the ClutterBoxLayout should animate changes in the layout properties

Default value: FALSE

Since 1.2

### The `"vertical"` property

      "vertical"                 gboolean              : Read / Write

Whether the ClutterBoxLayout should arrange its children alongside the Y axis, instead of alongside the X axis

Default value: FALSE

Since 1.2