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_homogeneous  (ClutterBoxLayout *layout,
                                                             gboolean homogeneous);
    gboolean            clutter_box_layout_get_homogeneous  (ClutterBoxLayout *layout);
    enum                ClutterOrientation;
    ClutterOrientation  clutter_box_layout_get_orientation  (ClutterBoxLayout *layout);
    void                clutter_box_layout_set_orientation  (ClutterBoxLayout *layout,
                                                             ClutterOrientation orientation);
    void                clutter_box_layout_set_vertical     (ClutterBoxLayout *layout,
                                                             gboolean vertical);
    gboolean            clutter_box_layout_get_vertical     (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
      "orientation"              ClutterOrientation    : 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 "orientation" 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 "x-expand"/"y-expand" is set, the available size;

- honours the ClutterActor's "x-align" and "y-align" properties to fill the available size;

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

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_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

### enum ClutterOrientation

    typedef enum {
      CLUTTER_ORIENTATION_HORIZONTAL,
      CLUTTER_ORIENTATION_VERTICAL
    } ClutterOrientation;

Represents the orientation of actors or layout managers.

`CLUTTER_ORIENTATION_HORIZONTAL` | An horizontal orientation
`CLUTTER_ORIENTATION_VERTICAL` | A vertical orientation

Since 1.12

### clutter_box_layout_get_orientation ()

    ClutterOrientation  clutter_box_layout_get_orientation  (ClutterBoxLayout *layout);

Retrieves the orientation of the `layout`.

`layout` : | a ClutterBoxLayout
Returns : | the orientation of the layout

Since 1.12

### clutter_box_layout_set_orientation ()

    void                clutter_box_layout_set_orientation  (ClutterBoxLayout *layout,
                                                             ClutterOrientation orientation);

Sets the orientation of the ClutterBoxLayout layout manager.

`layout` : | a ClutterBoxLayout
`orientation` : | the orientation of the ClutterBoxLayout

Since 1.12

### clutter_box_layout_set_vertical ()

    void                clutter_box_layout_set_vertical     (ClutterBoxLayout *layout,
                                                             gboolean vertical);

### Warning

`clutter_box_layout_set_vertical` has been deprecated since version 1.12 and should not be used in newly-written code. Use `clutter_box_layout_set_orientation()` instead.

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

### Warning

`clutter_box_layout_get_vertical` has been deprecated since version 1.12 and should not be used in newly-written code. Use `clutter_box_layout_get_orientation()` instead

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

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

### Warning

`clutter_box_layout_pack` has been deprecated since version 1.12 and should not be used in newly-written code. ClutterBoxLayout honours ClutterActor's align and expand properties. The preferred way is adding the `actor` with `clutter_actor_add_child()` and setting "x-align", "y-align", "x-expand" and "y-expand"

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

### Warning

`clutter_box_layout_set_alignment` has been deprecated since version 1.12 and should not be used in newly-written code. ClutterBoxLayout will honour ClutterActor's "x-align" and "y-align" properies

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

### Warning

`clutter_box_layout_get_alignment` has been deprecated since version 1.12 and should not be used in newly-written code. ClutterBoxLayout will honour ClutterActor's "x-align" and "y-align" properies

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

### Warning

`clutter_box_layout_set_expand` has been deprecated since version 1.12 and should not be used in newly-written code. ClutterBoxLayout will honour ClutterActor's "x-expand" and "y-expand" properies

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

### Warning

`clutter_box_layout_get_expand` has been deprecated since version 1.12 and should not be used in newly-written code. ClutterBoxLayout will honour ClutterActor's "x-expand" and "y-expand" properies

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

### Warning

`clutter_box_layout_set_fill` has been deprecated since version 1.12 and should not be used in newly-written code. ClutterBoxLayout will honour ClutterActor's "x-align" and "y-align" properies

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

### Warning

`clutter_box_layout_get_fill` has been deprecated since version 1.12 and should not be used in newly-written code. ClutterBoxLayout will honour ClutterActor's "x-align" and "y-align" properies

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

### Warning

`clutter_box_layout_set_use_animations` has been deprecated since version 1.12 and should not be used in newly-written code. The layout manager will honour the easing state of the children when allocating them.

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

Enabling animations will override the easing state of each child of the actor using `layout`, and will use the "easing-mode" and "easing-duration" properties instead.

`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);

### Warning

`clutter_box_layout_get_use_animations` is deprecated and should not be used in newly-written code. 1.12

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

`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);

### Warning

`clutter_box_layout_set_easing_duration` has been deprecated since version 1.12 and should not be used in newly-written code. The layout manager will honour the easing state of the children when allocating them.

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

`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);

### Warning

`clutter_box_layout_get_easing_duration` is deprecated and should not be used in newly-written code. 1.12

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

### Warning

`clutter_box_layout_set_easing_mode` has been deprecated since version 1.12 and should not be used in newly-written code. The layout manager will honour the easing state of the children when allocating them.

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

`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);

### Warning

`clutter_box_layout_get_easing_mode` is deprecated and should not be used in newly-written code. 1.12

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

### Warning

`ClutterBoxLayout:easing-duration` has been deprecated since version 1.12 and should not be used in newly-written code. The ClutterBoxLayout will honour the easing state of the children when allocating them.

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

### Warning

`ClutterBoxLayout:easing-mode` has been deprecated since version 1.12 and should not be used in newly-written code. The ClutterBoxLayout will honour the easing state of the children when allocating them.

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 `"orientation"` property

      "orientation"              ClutterOrientation    : Read / Write

The orientation of the ClutterBoxLayout, either horizontal or vertical

Default value: CLUTTER_ORIENTATION_HORIZONTAL

Since 1.12

### 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

### Warning

`ClutterBoxLayout:use-animations` has been deprecated since version 1.12 and should not be used in newly-written code. ClutterBoxLayout will honour the easing state of the children when allocating them.

Whether the ClutterBoxLayout should animate changes in the layout, overriding the easing state of the children.

Default value: FALSE

Since 1.2

### The `"vertical"` property

      "vertical"                 gboolean              : Read / Write

### Warning

`ClutterBoxLayout:vertical` has been deprecated since version 1.12 and should not be used in newly-written code. Use "orientation" instead.

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

Default value: FALSE

Since 1.2