ClutterBox

ClutterBox — Base class for layout containers

Synopsis




                    ClutterBoxClass;
enum                ClutterPackType;
void                clutter_box_set_color               (ClutterBox *box,
                                                         const ClutterColor *color);
void                clutter_box_get_color               (ClutterBox *box,
                                                         ClutterColor *color);
                    ClutterPadding;
void                clutter_box_pack                    (ClutterBox *box,
                                                         ClutterActor *actor,
                                                         ClutterPackType pack_type,
                                                         const ClutterPadding *padding);
void                clutter_box_set_default_padding     (ClutterBox *box,
                                                         gint padding_top,
                                                         gint padding_right,
                                                         gint padding_bottom,
                                                         gint padding_left);
void                clutter_box_get_default_padding     (ClutterBox *box,
                                                         gint *padding_top,
                                                         gint *padding_right,
                                                         gint *padding_bottom,
                                                         gint *padding_left);
void                clutter_box_pack_defaults           (ClutterBox *box,
                                                         ClutterActor *actor);
void                clutter_box_remove_all              (ClutterBox *box);
                    ClutterMargin;
void                clutter_box_set_margin              (ClutterBox *box,
                                                         const ClutterMargin *margin);
void                clutter_box_get_margin              (ClutterBox *box,
                                                         ClutterMargin *margin);
                    ClutterBoxChild;
gboolean            clutter_box_query_child             (ClutterBox *box,
                                                         ClutterActor *actor,
                                                         ClutterBoxChild *child);
gboolean            clutter_box_query_nth_child         (ClutterBox *box,
                                                         gint index_,
                                                         ClutterBoxChild *child);


Description

ClutterBox is a base class for containers which impose a specific layout on their children, unlike ClutterGroup which is a free-form container.

Layout containers are expected to move and size their children depending on a layout contract they establish per-class. For instance, a ClutterHBox (a subclass of ClutterBox) lays out its children along an imaginary horizontal line.

All ClutterBoxes have a margin, which is decomposed in four components (top, right, bottom left) and a background color. Each child of a ClutterBox has a packing type and a padding, decomposed like the margin. Actors can be packed using clutter_box_pack() and providing the packing type and the padding, or using clutter_box_pack_defaults() and setting a default padding with clutter_box_set_default_padding(). A ClutterBox implements the ClutterContainer interface: calling clutter_container_add_actor() on a ClutterBox will automatically invoke clutter_box_pack_defaults().

Each child of a ClutterBox has its packing information wrapped into the ClutterBoxChild structure, which can be retrieved either using the clutter_box_query_child() or the clutter_box_query_nth_child() function.

Subclasses of ClutterBox must implement the ClutterBox::pack_child and ClutterBox::unpack_child virtual functions; these functions will be called when adding a child and when removing one, respectively.

ClutterBox is available since Clutter 0.4

Details

ClutterBoxClass

typedef struct {
  /* vfuncs, not signals */
  void (* pack_child)   (ClutterBox      *box,
                         ClutterBoxChild *child);
  void (* unpack_child) (ClutterBox      *box,
                         ClutterBoxChild *child);
} ClutterBoxClass;

Base class for layout containers

pack_child () virtual function, called when packing a new child. All ClutterBox subclasses must implement this function
unpack_child () virtual function, called when unpacking a child. All ClutterBox subclasses must implement this function

Since 0.4


enum ClutterPackType

typedef enum {
  CLUTTER_PACK_START,
  CLUTTER_PACK_END
} ClutterPackType;

Pack order for a ClutterBox child.

CLUTTER_PACK_START append child from the start
CLUTTER_PACK_END append child from the end

Since 0.4


clutter_box_set_color ()

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

Sets the background color of the box.

box : a ClutterBox
color : the background color of the box

Since 0.4


clutter_box_get_color ()

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

Gets the background color of the box set with clutter_box_set_color().

box : a ClutterBox
color : return location for the color

Since 0.4


ClutterPadding

typedef struct {
  ClutterUnit top;
  ClutterUnit right;
  ClutterUnit bottom;
  ClutterUnit left;
} ClutterPadding;

Padding of the children of a container

ClutterUnit top; top padding
ClutterUnit right; right padding
ClutterUnit bottom; bottom padding
ClutterUnit left; left padding

Since 0.4


clutter_box_pack ()

void                clutter_box_pack                    (ClutterBox *box,
                                                         ClutterActor *actor,
                                                         ClutterPackType pack_type,
                                                         const ClutterPadding *padding);

Packs actor into box.

box : a ClutterBox
actor : a ClutterActor to pack into the box
pack_type : Type of packing to use
padding : padding to use on the actor

Since 0.4


clutter_box_set_default_padding ()

void                clutter_box_set_default_padding     (ClutterBox *box,
                                                         gint padding_top,
                                                         gint padding_right,
                                                         gint padding_bottom,
                                                         gint padding_left);

Sets the default padding for children, which will be used when packing actors with clutter_box_pack_defaults(). The padding is given in pixels.

box : a ClutterBox
padding_top : top padding, in pixels
padding_right : right padding, in pixels
padding_bottom : bottom padding, in pixels
padding_left : left padding, in pixels

Since 0.4


clutter_box_get_default_padding ()

void                clutter_box_get_default_padding     (ClutterBox *box,
                                                         gint *padding_top,
                                                         gint *padding_right,
                                                         gint *padding_bottom,
                                                         gint *padding_left);

Gets the default padding set with clutter_box_set_default_padding().

box : a ClutterBox
padding_top : return location for the top padding, or NULL
padding_right : return location for the right padding, or NULL
padding_bottom : return location for the bottom padding, or NULL
padding_left : return location for the left padding, or NULL

Since 0.4


clutter_box_pack_defaults ()

void                clutter_box_pack_defaults           (ClutterBox *box,
                                                         ClutterActor *actor);

Packs actor into box, using the default settings for the pack type and padding.

box : a ClutterBox
actor : a ClutterActor

Since 0.4


clutter_box_remove_all ()

void                clutter_box_remove_all              (ClutterBox *box);

Removes all children actors from the ClutterBox

box : a ClutterBox

Since 0.4


ClutterMargin

typedef struct {
  ClutterUnit top;
  ClutterUnit right;
  ClutterUnit bottom;
  ClutterUnit left;
} ClutterMargin;

Margins from the inner borders of a container

ClutterUnit top; top margin
ClutterUnit right; right margin
ClutterUnit bottom; bottom margin
ClutterUnit left; left margin

Since 0.4


clutter_box_set_margin ()

void                clutter_box_set_margin              (ClutterBox *box,
                                                         const ClutterMargin *margin);

Sets the margin, in ClutterUnits, between the inner border of the box and the children of the box.

box : a ClutterBox
margin : a ClutterMargin, or NULL to unset the margin

Since 0.4


clutter_box_get_margin ()

void                clutter_box_get_margin              (ClutterBox *box,
                                                         ClutterMargin *margin);

Gets the value set using clutter_box_set_margin().

box : a ClutterBox
margin : return location for a ClutterMargin

Since 0.4


ClutterBoxChild

typedef struct {
  ClutterActor *actor;
  ClutterActorBox child_coords;
  ClutterPackType pack_type;
  ClutterPadding padding;
} ClutterBoxChild;

Packing data for children of a ClutterBox.

ClutterActor *actor; the child ClutterActor
ClutterActorBox child_coords; the original coordinates of the child
ClutterPackType pack_type; the type of packing used by the child
ClutterPadding padding; the padding around the child

Since 0.4


clutter_box_query_child ()

gboolean            clutter_box_query_child             (ClutterBox *box,
                                                         ClutterActor *actor,
                                                         ClutterBoxChild *child);

Queries box for the packing data of actor.

box : a ClutterBox
actor : child to query
child : return location for a ClutterBoxChild or NULL
Returns : TRUE if actor is a child of box

Since 0.4


clutter_box_query_nth_child ()

gboolean            clutter_box_query_nth_child         (ClutterBox *box,
                                                         gint index_,
                                                         ClutterBoxChild *child);

Queries the child of box at index_ and puts the packing informations inside child.

box : a ClutterBox
index_ : position of the child
child : return value for a ClutterBoxChild, or NULL
Returns : TRUE if an actor was found at index_

Since 0.4