ClutterBox: Clutter Reference Manual

## ClutterBox ClutterBox — A Generic layout container |

## Functions

ClutterActor * | clutter_box_new ()
void | clutter_box_set_layout_manager ()
ClutterLayoutManager * | clutter_box_get_layout_manager ()
void | clutter_box_set_color ()
void | clutter_box_get_color ()
void | clutter_box_pack ()
void | clutter_box_packv ()
void | clutter_box_pack_after ()
void | clutter_box_pack_before ()
void | clutter_box_pack_at ()

## Properties

ClutterColor * | color | Read / Write
gboolean | color-set | Read / Write

## Types and Values

struct | ClutterBox
struct | ClutterBoxClass

## Object Hierarchy

        GObject
        ╰── GInitiallyUnowned
            ╰── ClutterActor
                ╰── ClutterBox

## Implemented Interfaces

ClutterBox implements ClutterContainer, ClutterScriptable, ClutterAnimatable and AtkImplementorIface.

## Description

ClutterBox is a ClutterActor sub-class implementing the ClutterContainer interface. A Box delegates the whole size requisition and size allocation to a ClutterLayoutManager instance.

ClutterBox is available since Clutter 1.2

ClutterBox is deprecated since Clutter 1.10; all its relevant API is provided by ClutterActor, via the “layout-manager” property.

#### Using ClutterBox

The following code shows how to create a ClutterBox with a ClutterLayoutManager sub-class, and how to add children to it via `clutter_box_pack()`.

    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11
    12
    13
    14
    15
    16
    17
    18
    19
    20
    ClutterActor *box;
    ClutterLayoutManager *layout;

    // Create the layout manager first
    layout = clutter_box_layout_new ();
    clutter_box_layout_set_homogeneous (CLUTTER_BOX_LAYOUT (layout), TRUE);
    clutter_box_layout_set_spacing (CLUTTER_BOX_LAYOUT (layout), 12);

    // Then create the ClutterBox actor. The Box will take
    // ownership of the ClutterLayoutManager instance by sinking
    // its floating reference
    box = clutter_box_new (layout);

    // Now add children to the Box using the variadic arguments
    // function clutter_box_pack() to set layout properties
    clutter_box_pack (CLUTTER_BOX (box), actor,
                      "x-align", CLUTTER_BOX_ALIGNMENT_CENTER,
                      "y-align", CLUTTER_BOX_ALIGNMENT_END,
                      "expand", TRUE,
                      NULL);

ClutterBox's `clutter_box_pack()` wraps the generic `clutter_container_add_actor()` function, but it also allows setting layout properties while adding the new child to the box.

## Functions

### clutter_box_new ()

    ClutterActor *
    clutter_box_new (ClutterLayoutManager *manager);

`clutter_box_new` has been deprecated since version 1.10 and should not be used in newly-written code.

Use `clutter_actor_new()` instead.

Creates a new ClutterBox. The children of the box will be layed out by the passed `manager`

#### Parameters

manager | a ClutterLayoutManager |

#### Returns

the newly created ClutterBox actor

Since: 1.2

### clutter_box_set_layout_manager ()

    void
    clutter_box_set_layout_manager (ClutterBox *box,
                                    ClutterLayoutManager *manager);

`clutter_box_set_layout_manager` has been deprecated since version 1.10 and should not be used in newly-written code.

Use `clutter_actor_set_layout_manager()` instead.

Sets the ClutterLayoutManager for `box`

A ClutterLayoutManager is a delegate object that controls the layout of the children of `box`

#### Parameters

box | a ClutterBox |
manager | a ClutterLayoutManager |

Since: 1.2

### clutter_box_get_layout_manager ()

    ClutterLayoutManager *
    clutter_box_get_layout_manager (ClutterBox *box);

`clutter_box_get_layout_manager` has been deprecated since version 1.10 and should not be used in newly-written code.

Use `clutter_actor_get_layout_manager()` instead.

Retrieves the ClutterLayoutManager instance used by `box`

#### Parameters

box | a ClutterBox |

#### Returns

a ClutterLayoutManager. The returned ClutterLayoutManager is owned by the ClutterBox and it should not be unreferenced.

[transfer none]

Since: 1.2

### clutter_box_set_color ()

    void
    clutter_box_set_color (ClutterBox *box,
                           const ClutterColor *color);

`clutter_box_set_color` has been deprecated since version 1.10 and should not be used in newly-written code.

Use `clutter_actor_set_background_color()` instead.

Sets (or unsets) the background color for `box`

#### Parameters

box | a ClutterBox |
color | the background color, or `NULL` to unset. | [allow-none]

Since: 1.2

### clutter_box_get_color ()

    void
    clutter_box_get_color (ClutterBox *box,
                           ClutterColor *color);

`clutter_box_get_color` has been deprecated since version 1.10 and should not be used in newly-written code.

Use `clutter_actor_get_background_color()` instead.

Retrieves the background color of `box`

If the “color-set” property is set to `FALSE` the returned ClutterColor is undefined

#### Parameters

box | a ClutterBox |
color | return location for a ClutterColor. | [out caller-allocates]

Since: 1.2

### clutter_box_pack ()

    void
    clutter_box_pack (ClutterBox *box,
                      ClutterActor *actor,
                      const gchar *first_property,
                      ...);

`clutter_box_pack` has been deprecated since version 1.10 and should not be used in newly-written code.

Use `clutter_actor_add_child()` instead. To set specific layout properties, use `clutter_layout_manager_child_set()`

Adds `actor` to `box` and sets layout properties at the same time, if the ClutterLayoutManager used by `box` has them

This function is a wrapper around `clutter_container_add_actor()` and `clutter_layout_manager_child_set()`

Language bindings should use the vector-based `clutter_box_packv()` variant instead

#### Parameters

box | a ClutterBox |
actor | a ClutterActor |
first_property | the name of the first property to set, or `NULL` |
... | a list of property name and value pairs, terminated by `NULL` |

Since: 1.2

### clutter_box_packv ()

    void
    clutter_box_packv (ClutterBox *box,
                       ClutterActor *actor,
                       guint n_properties,
                       const gchar * const properties[],
                       const GValue *values);

`clutter_box_packv` has been deprecated since version 1.10 and should not be used in newly-written code.

Use `clutter_actor_add_child()` instead. To set specific layout properties, use `clutter_layout_manager_child_set()`

Vector-based variant of `clutter_box_pack()`, intended for language bindings to use

#### Parameters

box | a ClutterBox |
actor | a ClutterActor |
n_properties | the number of properties to set |
properties | a vector containing the property names to set. | [array length=n_properties][element-type utf8]
values | a vector containing the property values to set. | [array length=n_properties]

Since: 1.2

### clutter_box_pack_after ()

    void
    clutter_box_pack_after (ClutterBox *box,
                            ClutterActor *actor,
                            ClutterActor *sibling,
                            const gchar *first_property,
                            ...);

`clutter_box_pack_after` has been deprecated since version 1.10 and should not be used in newly-written code.

Use `clutter_actor_insert_child_above()` instead. To set specific layout properties, use `clutter_layout_manager_child_set()`

Adds `actor` to `box` , placing it after `sibling` , and sets layout properties at the same time, if the ClutterLayoutManager used by `box` supports them

If `sibling` is `NULL` then `actor` is placed at the end of the list of children, to be allocated and painted after every other child

This function is a wrapper around `clutter_container_add_actor()`, `clutter_container_raise_child()` and `clutter_layout_manager_child_set()`

#### Parameters

box | a ClutterBox |
actor | a ClutterActor |
sibling | a ClutterActor or `NULL`. | [allow-none]
first_property | the name of the first property to set, or `NULL` |
... | a list of property name and value pairs, terminated by `NULL` |

Since: 1.2

### clutter_box_pack_before ()

    void
    clutter_box_pack_before (ClutterBox *box,
                             ClutterActor *actor,
                             ClutterActor *sibling,
                             const gchar *first_property,
                             ...);

`clutter_box_pack_before` has been deprecated since version 1.10 and should not be used in newly-written code.

Use `clutter_actor_insert_child_below()` instead. To set specific layout properties, use `clutter_layout_manager_child_set()`

Adds `actor` to `box` , placing it before `sibling` , and sets layout properties at the same time, if the ClutterLayoutManager used by `box` supports them

If `sibling` is `NULL` then `actor` is placed at the beginning of the list of children, to be allocated and painted below every other child

This function is a wrapper around `clutter_container_add_actor()`, `clutter_container_lower_child()` and `clutter_layout_manager_child_set()`

#### Parameters

box | a ClutterBox |
actor | a ClutterActor |
sibling | a ClutterActor or `NULL`. | [allow-none]
first_property | the name of the first property to set, or `NULL` |
... | a list of property name and value pairs, terminated by `NULL` |

Since: 1.2

### clutter_box_pack_at ()

    void
    clutter_box_pack_at (ClutterBox *box,
                         ClutterActor *actor,
                         gint position,
                         const gchar *first_property,
                         ...);

`clutter_box_pack_at` has been deprecated since version 1.10 and should not be used in newly-written code.

Use `clutter_actor_insert_child_at_index()` instead. To set specific layout properties, use `clutter_layout_manager_child_set()`

Adds `actor` to `box` , placing it at `position` , and sets layout properties at the same time, if the ClutterLayoutManager used by `box` supports them

If `position` is a negative number, or is larger than the number of children of `box` , the new child is added at the end of the list of children

#### Parameters

box | a ClutterBox |
actor | a ClutterActor |
position | the position to insert the `actor` at |
first_property | the name of the first property to set, or `NULL` |
... | a list of property name and value pairs, terminated by `NULL` |

Since: 1.2

## Types and Values

### struct ClutterBox

    struct ClutterBox;

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

Since: 1.2

### struct ClutterBoxClass

    struct ClutterBoxClass {
    };

The ClutterBoxClass structure contains only private data

Since: 1.2

## Property Details

### The `“color”` property

      “color”                    ClutterColor *

The color to be used to paint the background of the ClutterBox. Setting this property will set the “color-set” property as a side effect

This property sets the “background-color” property internally.

`ClutterBox:color` has been deprecated since version 1.10 and should not be used in newly-written code.

Use the “background-color” property

Owner: ClutterBox

Flags: Read / Write

Since: 1.2

### The `“color-set”` property

      “color-set”                gboolean

Whether the “color” property has been set.

This property reads the “background-color-set” property internally.

`ClutterBox:color-set` has been deprecated since version 1.10 and should not be used in newly-written code.

Use the “background-color-set” property

Owner: ClutterBox

Flags: Read / Write

Default value: FALSE

Since: 1.2