## ClutterBox

ClutterBox — A Generic layout container

## Synopsis

    struct              ClutterBox;
    struct              ClutterBoxClass;
    ClutterActor *      clutter_box_new                     (ClutterLayoutManager *manager);
    void                clutter_box_set_layout_manager      (ClutterBox *box,
                                                             ClutterLayoutManager *manager);
    ClutterLayoutManager * clutter_box_get_layout_manager   (ClutterBox *box);
    void                clutter_box_set_color               (ClutterBox *box,
                                                             const ClutterColor *color);
    void                clutter_box_get_color               (ClutterBox *box,
                                                             ClutterColor *color);

    void                clutter_box_pack                    (ClutterBox *box,
                                                             ClutterActor *actor,
                                                             const gchar *first_property,
                                                             ...);
    void                clutter_box_packv                   (ClutterBox *box,
                                                             ClutterActor *actor,
                                                             guint n_properties,
                                                             const gchar * const properties[],
                                                             const GValue *values);
    void                clutter_box_pack_after              (ClutterBox *box,
                                                             ClutterActor *actor,
                                                             ClutterActor *sibling,
                                                             const gchar *first_property,
                                                             ...);
    void                clutter_box_pack_before             (ClutterBox *box,
                                                             ClutterActor *actor,
                                                             ClutterActor *sibling,
                                                             const gchar *first_property,
                                                             ...);
    void                clutter_box_pack_at                 (ClutterBox *box,
                                                             ClutterActor *actor,
                                                             gint position,
                                                             const gchar *first_property,
                                                             ...);

## Object Hierarchy

      GObject
       +----GInitiallyUnowned
             +----ClutterActor
                   +----ClutterBox

## Implemented Interfaces

ClutterBox implements ClutterScriptable, ClutterAnimatable, AtkImplementorIface and ClutterContainer.

## Properties

      "color"                    ClutterColor*         : Read / Write
      "color-set"                gboolean              : Read / Write
      "layout-manager"           ClutterLayoutManager*  : Read / Write / Construct

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

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

     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.

ClutterBox is available since Clutter 1.2

## Details

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

### clutter_box_new ()

    ClutterActor *      clutter_box_new                     (ClutterLayoutManager *manager);

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

`manager` : | a ClutterLayoutManager
Returns : | the newly created ClutterBox actor

Since 1.0

### clutter_box_set_layout_manager ()

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

Sets the ClutterLayoutManager for `box`

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

`box` : | a ClutterBox
`manager` : | a ClutterLayoutManager

Since 1.2

### clutter_box_get_layout_manager ()

    ClutterLayoutManager * clutter_box_get_layout_manager   (ClutterBox *box);

Retrieves the ClutterLayoutManager instance used by `box`

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

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

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

Retrieves the background color of `box`

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

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

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

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

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

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

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

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

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

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

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

`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

## Property Details

### The `"color"` property

      "color"                    ClutterColor*         : Read / Write

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

Since 1.2

### The `"color-set"` property

      "color-set"                gboolean              : Read / Write

Whether the "color" property has been set

Default value: FALSE

Since 1.2

### The `"layout-manager"` property

      "layout-manager"           ClutterLayoutManager*  : Read / Write / Construct

The ClutterLayoutManager used by the ClutterBox

Since 1.2