Clutter Reference Manual: ClutterTableLayout

## ClutterTableLayout ClutterTableLayout — A layout manager arranging children in rows and columns |

## Synopsis

    enum                ClutterTableAlignment;
    struct              ClutterTableLayout;
    struct              ClutterTableLayoutClass;
    ClutterLayoutManager * clutter_table_layout_new         (void);
    void                clutter_table_layout_set_row_spacing
                                                            (ClutterTableLayout *layout,
                                                             guint spacing);
    guint               clutter_table_layout_get_row_spacing
                                                            (ClutterTableLayout *layout);
    void                clutter_table_layout_set_column_spacing
                                                            (ClutterTableLayout *layout,
                                                             guint spacing);
    guint               clutter_table_layout_get_column_spacing
                                                            (ClutterTableLayout *layout);
    gint                clutter_table_layout_get_row_count  (ClutterTableLayout *layout);
    gint                clutter_table_layout_get_column_count
                                                            (ClutterTableLayout *layout);

    void                clutter_table_layout_pack           (ClutterTableLayout *layout,
                                                             ClutterActor *actor,
                                                             gint column,
                                                             gint row);

    void                clutter_table_layout_set_alignment  (ClutterTableLayout *layout,
                                                             ClutterActor *actor,
                                                             ClutterTableAlignment x_align,
                                                             ClutterTableAlignment y_align);
    void                clutter_table_layout_get_alignment  (ClutterTableLayout *layout,
                                                             ClutterActor *actor,
                                                             ClutterTableAlignment *x_align,
                                                             ClutterTableAlignment *y_align);
    void                clutter_table_layout_set_expand     (ClutterTableLayout *layout,
                                                             ClutterActor *actor,
                                                             gboolean x_expand,
                                                             gboolean y_expand);
    void                clutter_table_layout_get_expand     (ClutterTableLayout *layout,
                                                             ClutterActor *actor,
                                                             gboolean *x_expand,
                                                             gboolean *y_expand);
    void                clutter_table_layout_set_fill       (ClutterTableLayout *layout,
                                                             ClutterActor *actor,
                                                             gboolean x_fill,
                                                             gboolean y_fill);
    void                clutter_table_layout_get_fill       (ClutterTableLayout *layout,
                                                             ClutterActor *actor,
                                                             gboolean *x_fill,
                                                             gboolean *y_fill);
    void                clutter_table_layout_get_span       (ClutterTableLayout *layout,
                                                             ClutterActor *actor,
                                                             gint *column_span,
                                                             gint *row_span);
    void                clutter_table_layout_set_span       (ClutterTableLayout *layout,
                                                             ClutterActor *actor,
                                                             gint column_span,
                                                             gint row_span);

    void                clutter_table_layout_set_use_animations
                                                            (ClutterTableLayout *layout,
                                                             gboolean animate);
    gboolean            clutter_table_layout_get_use_animations
                                                            (ClutterTableLayout *layout);
    void                clutter_table_layout_set_easing_duration
                                                            (ClutterTableLayout *layout,
                                                             guint msecs);
    guint               clutter_table_layout_get_easing_duration
                                                            (ClutterTableLayout *layout);
    void                clutter_table_layout_set_easing_mode
                                                            (ClutterTableLayout *layout,
                                                             gulong mode);
    gulong              clutter_table_layout_get_easing_mode
                                                            (ClutterTableLayout *layout);

## Object Hierarchy

      GObject
       +----GInitiallyUnowned
             +----ClutterLayoutManager
                   +----ClutterTableLayout

## Properties

      "column-spacing"           guint                 : Read / Write
      "easing-duration"          guint                 : Read / Write
      "easing-mode"              gulong                : Read / Write
      "row-spacing"              guint                 : Read / Write
      "use-animations"           gboolean              : Read / Write

## Description

The ClutterTableLayout is a ClutterLayoutManager implementing the following layout policy:

- children are arranged in a table

- each child specifies the specific row and column cell to appear;

- a child can also set a span, and this way, take more than one cell both horizontally and vertically;

- 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 horizontal and vertical alignment layout properties.

It is possible to control the spacing between children of a ClutterTableLayout by using `clutter_table_layout_set_row_spacing()` and `clutter_table_layout_set_column_spacing()`.

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

A ClutterTableLayout can use animations to transition between different values of the layout management properties; the easing mode and duration used for the animations are controlled by the "easing-mode" and "easing-duration" properties and their accessor functions.

Figure 7. Table layout

The image shows a ClutterTableLayout.

ClutterTableLayout is available since Clutter 1.4

## Details

### enum ClutterTableAlignment

    typedef enum {
      CLUTTER_TABLE_ALIGNMENT_START,
      CLUTTER_TABLE_ALIGNMENT_CENTER,
      CLUTTER_TABLE_ALIGNMENT_END
    } ClutterTableAlignment;

The alignment policies available on each axis of the ClutterTableLayout

`CLUTTER_TABLE_ALIGNMENT_START` | Align the child to the top or to the left of a cell in the table, depending on the axis
`CLUTTER_TABLE_ALIGNMENT_CENTER` | Align the child to the center of a cell in the table
`CLUTTER_TABLE_ALIGNMENT_END` | Align the child to the bottom or to the right of a cell in the table, depending on the axis

Since 1.4

### struct ClutterTableLayout

    struct ClutterTableLayout;

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

Since 1.4

### struct ClutterTableLayoutClass

    struct ClutterTableLayoutClass {
    };

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

Since 1.4

### clutter_table_layout_new ()

    ClutterLayoutManager * clutter_table_layout_new         (void);

Creates a new ClutterTableLayout layout manager

Returns : | the newly created ClutterTableLayout

Since 1.4

### clutter_table_layout_set_row_spacing ()

    void                clutter_table_layout_set_row_spacing
                                                            (ClutterTableLayout *layout,
                                                             guint spacing);

Sets the spacing between rows of `layout`

`layout` : | a ClutterTableLayout
`spacing` : | the spacing between rows of the layout, in pixels

Since 1.4

### clutter_table_layout_get_row_spacing ()

    guint               clutter_table_layout_get_row_spacing
                                                            (ClutterTableLayout *layout);

Retrieves the spacing set using `clutter_table_layout_set_row_spacing()`

`layout` : | a ClutterTableLayout
Returns : | the spacing between rows of the ClutterTableLayout

Since 1.4

### clutter_table_layout_set_column_spacing ()

    void                clutter_table_layout_set_column_spacing
                                                            (ClutterTableLayout *layout,
                                                             guint spacing);

Sets the spacing between columns of `layout`

`layout` : | a ClutterTableLayout
`spacing` : | the spacing between columns of the layout, in pixels

Since 1.4

### clutter_table_layout_get_column_spacing ()

    guint               clutter_table_layout_get_column_spacing
                                                            (ClutterTableLayout *layout);

Retrieves the spacing set using `clutter_table_layout_set_column_spacing()`

`layout` : | a ClutterTableLayout
Returns : | the spacing between columns of the ClutterTableLayout

Since 1.4

### clutter_table_layout_get_row_count ()

    gint                clutter_table_layout_get_row_count  (ClutterTableLayout *layout);

Retrieve the current number rows in the `layout`

`layout` : | A ClutterTableLayout
Returns : | the number of rows

Since 1.4

### clutter_table_layout_get_column_count ()

    gint                clutter_table_layout_get_column_count
                                                            (ClutterTableLayout *layout);

Retrieve the current number of columns in `layout`

`layout` : | A ClutterTableLayout
Returns : | the number of columns

Since 1.4

### clutter_table_layout_pack ()

    void                clutter_table_layout_pack           (ClutterTableLayout *layout,
                                                             ClutterActor *actor,
                                                             gint column,
                                                             gint row);

Packs `actor` inside the ClutterContainer associated to `layout` at the given row and column.

`layout` : | a ClutterTableLayout
`actor` : | a ClutterActor
`column` : | the column the `actor` should be put, or -1 to append
`row` : | the row the `actor` should be put, or -1 to append

Since 1.4

### clutter_table_layout_set_alignment ()

    void                clutter_table_layout_set_alignment  (ClutterTableLayout *layout,
                                                             ClutterActor *actor,
                                                             ClutterTableAlignment x_align,
                                                             ClutterTableAlignment y_align);

### Warning

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

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

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

Since 1.4

### clutter_table_layout_get_alignment ()

    void                clutter_table_layout_get_alignment  (ClutterTableLayout *layout,
                                                             ClutterActor *actor,
                                                             ClutterTableAlignment *x_align,
                                                             ClutterTableAlignment *y_align);

### Warning

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

Retrieves the horizontal and vertical alignment policies for `actor` as set using `clutter_table_layout_pack()` or `clutter_table_layout_set_alignment()`.

`layout` : | a ClutterTableLayout
`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.4

### clutter_table_layout_set_expand ()

    void                clutter_table_layout_set_expand     (ClutterTableLayout *layout,
                                                             ClutterActor *actor,
                                                             gboolean x_expand,
                                                             gboolean y_expand);

### Warning

`clutter_table_layout_set_expand` has been deprecated since version 1.12 and should not be used in newly-written code. Use `clutter_actor_set_x_expand()` or `clutter_actor_set_y_expand()` instead.

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

`layout` : | a ClutterTableLayout
`actor` : | a ClutterActor child of `layout`
`x_expand` : | whether `actor` should allocate extra space horizontally
`y_expand` : | whether `actor` should allocate extra space vertically

Since 1.4

### clutter_table_layout_get_expand ()

    void                clutter_table_layout_get_expand     (ClutterTableLayout *layout,
                                                             ClutterActor *actor,
                                                             gboolean *x_expand,
                                                             gboolean *y_expand);

### Warning

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

Retrieves the horizontal and vertical expand policies for `actor` as set using `clutter_table_layout_pack()` or `clutter_table_layout_set_expand()`

`layout` : | a ClutterTableLayout
`actor` : | a ClutterActor child of `layout`
`x_expand` : | return location for the horizontal expand policy. [out]
`y_expand` : | return location for the vertical expand policy. [out]

Since 1.4

### clutter_table_layout_set_fill ()

    void                clutter_table_layout_set_fill       (ClutterTableLayout *layout,
                                                             ClutterActor *actor,
                                                             gboolean x_fill,
                                                             gboolean y_fill);

### Warning

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

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

`layout` : | a ClutterTableLayout
`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.4

### clutter_table_layout_get_fill ()

    void                clutter_table_layout_get_fill       (ClutterTableLayout *layout,
                                                             ClutterActor *actor,
                                                             gboolean *x_fill,
                                                             gboolean *y_fill);

### Warning

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

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

`layout` : | a ClutterTableLayout
`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.4

### clutter_table_layout_get_span ()

    void                clutter_table_layout_get_span       (ClutterTableLayout *layout,
                                                             ClutterActor *actor,
                                                             gint *column_span,
                                                             gint *row_span);

Retrieves the row and column span for `actor` as set using `clutter_table_layout_pack()` or `clutter_table_layout_set_span()`

`layout` : | a ClutterTableLayout
`actor` : | a ClutterActor child of `layout`
`column_span` : | return location for the col span. [out]
`row_span` : | return location for the row span. [out]

Since 1.4

### clutter_table_layout_set_span ()

    void                clutter_table_layout_set_span       (ClutterTableLayout *layout,
                                                             ClutterActor *actor,
                                                             gint column_span,
                                                             gint row_span);

Sets the row and column span for `actor` inside `layout`

`layout` : | a ClutterTableLayout
`actor` : | a ClutterActor child of `layout`
`column_span` : | Column span for `actor`
`row_span` : | Row span for `actor`

Since 1.4

### clutter_table_layout_set_use_animations ()

    void                clutter_table_layout_set_use_animations
                                                            (ClutterTableLayout *layout,
                                                             gboolean animate);

### Warning

`clutter_table_layout_set_use_animations` has been deprecated since version 1.12 and should not be used in newly-written code. ClutterTableLayout 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_table_layout_set_easing_duration()`; the easing mode to be used by the animations is controlled by `clutter_table_layout_set_easing_mode()`

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

Since 1.4

### clutter_table_layout_get_use_animations ()

    gboolean            clutter_table_layout_get_use_animations
                                                            (ClutterTableLayout *layout);

### Warning

`clutter_table_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

Since `clutter_table_layout_set_use_animations()`

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

Since 1.4

### clutter_table_layout_set_easing_duration ()

    void                clutter_table_layout_set_easing_duration
                                                            (ClutterTableLayout *layout,
                                                             guint msecs);

### Warning

`clutter_table_layout_set_easing_duration` has been deprecated since version 1.12 and should not be used in newly-written code. ClutterTableLayout 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

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

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

Since 1.4

### clutter_table_layout_get_easing_duration ()

    guint               clutter_table_layout_get_easing_duration
                                                            (ClutterTableLayout *layout);

### Warning

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

Retrieves the duration set using `clutter_table_layout_set_easing_duration()`

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

Since 1.4

### clutter_table_layout_set_easing_mode ()

    void                clutter_table_layout_set_easing_mode
                                                            (ClutterTableLayout *layout,
                                                             gulong mode);

### Warning

`clutter_table_layout_set_easing_mode` has been deprecated since version 1.12 and should not be used in newly-written code. ClutterTableLayout 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

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

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

Since 1.4

### clutter_table_layout_get_easing_mode ()

    gulong              clutter_table_layout_get_easing_mode
                                                            (ClutterTableLayout *layout);

### Warning

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

Retrieves the easing mode set using `clutter_table_layout_set_easing_mode()`

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

Since 1.4

## Property Details

### The `"column-spacing"` property

      "column-spacing"           guint                 : Read / Write

The spacing between columns of the ClutterTableLayout, in pixels

Default value: 0

Since 1.4

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

      "easing-duration"          guint                 : Read / Write

### Warning

`ClutterTableLayout:easing-duration` has been deprecated since version 1.12 and should not be used in newly-written code. ClutterTableLayout 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.4

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

      "easing-mode"              gulong                : Read / Write

### Warning

`ClutterTableLayout:easing-mode` has been deprecated since version 1.12 and should not be used in newly-written code. ClutterTableLayout 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.4

### The `"row-spacing"` property

      "row-spacing"              guint                 : Read / Write

The spacing between rows of the ClutterTableLayout, in pixels

Default value: 0

Since 1.4

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

      "use-animations"           gboolean              : Read / Write

### Warning

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

Whether the ClutterTableLayout should animate changes in the layout properties.

By default, ClutterTableLayout will honour the easing state of the children when allocating them. Setting this property to `TRUE` will override the easing state with the layout manager's "easing-mode" and "easing-duration" properties.

Default value: FALSE

Since 1.4