GtkBox

## GtkBox GtkBox — Base class for box containers |

## Synopsis

    #include <gtk/gtk.h>

                        GtkBox;
                        GtkBoxChild;
    void                gtk_box_pack_start                  (GtkBox *box,
                                                             GtkWidget *child,
                                                             gboolean expand,
                                                             gboolean fill,
                                                             guint padding);
    void                gtk_box_pack_end                    (GtkBox *box,
                                                             GtkWidget *child,
                                                             gboolean expand,
                                                             gboolean fill,
                                                             guint padding);
    void                gtk_box_pack_start_defaults         (GtkBox *box,
                                                             GtkWidget *widget);
    void                gtk_box_pack_end_defaults           (GtkBox *box,
                                                             GtkWidget *widget);
    gboolean            gtk_box_get_homogeneous             (GtkBox *box);
    void                gtk_box_set_homogeneous             (GtkBox *box,
                                                             gboolean homogeneous);
    gint                gtk_box_get_spacing                 (GtkBox *box);
    void                gtk_box_set_spacing                 (GtkBox *box,
                                                             gint spacing);
    void                gtk_box_reorder_child               (GtkBox *box,
                                                             GtkWidget *child,
                                                             gint position);
    void                gtk_box_query_child_packing         (GtkBox *box,
                                                             GtkWidget *child,
                                                             gboolean *expand,
                                                             gboolean *fill,
                                                             guint *padding,
                                                             GtkPackType *pack_type);
    void                gtk_box_set_child_packing           (GtkBox *box,
                                                             GtkWidget *child,
                                                             gboolean expand,
                                                             gboolean fill,
                                                             guint padding,
                                                             GtkPackType pack_type);

## Object Hierarchy

      GObject
       +----GInitiallyUnowned
             +----GtkObject
                   +----GtkWidget
                         +----GtkContainer
                               +----GtkBox
                                     +----GtkButtonBox
                                     +----GtkVBox
                                     +----GtkHBox

## Implemented Interfaces

GtkBox implements AtkImplementorIface, GtkBuildable and GtkOrientable.

## Properties

      "homogeneous"              gboolean              : Read / Write
      "spacing"                  gint                  : Read / Write

## Child Properties

      "expand"                   gboolean              : Read / Write
      "fill"                     gboolean              : Read / Write
      "pack-type"                GtkPackType           : Read / Write
      "padding"                  guint                 : Read / Write
      "position"                 gint                  : Read / Write

## Description

GtkBox is an abstract widget which encapsulates functionality for a particular kind of container, one that organizes a variable number of widgets into a rectangular area. GtkBox has a number of derived classes, e.g. GtkHBox and GtkVBox.

The rectangular area of a GtkBox is organized into either a single row or a single column of child widgets depending upon whether the box is of type GtkHBox or GtkVBox, respectively. Thus, all children of a GtkBox are allocated one dimension in common, which is the height of a row, or the width of a column.

GtkBox uses a notion of packing. Packing refers to adding widgets with reference to a particular position in a GtkContainer. For a GtkBox, there are two reference positions: the start and the end of the box. For a GtkVBox, the start is defined as the top of the box and the end is defined as the bottom. For a GtkHBox the start is defined as the left side and the end is defined as the right side.

Use repeated calls to `gtk_box_pack_start()` to pack widgets into a GtkBox from start to end. Use `gtk_box_pack_end()` to add widgets from end to start. You may intersperse these calls and add widgets from both ends of the same GtkBox.

Use `gtk_box_pack_start_defaults()` or `gtk_box_pack_end_defaults()` to pack widgets into a GtkBox if you do not need to specify the "expand", "fill", or "padding" child properties for the child to be added.

Because GtkBox is a GtkContainer, you may also use `gtk_container_add()` to insert widgets into the box, and they will be packed as if with `gtk_box_pack_start_defaults()`. Use `gtk_container_remove()` to remove widgets from the GtkBox.

Use `gtk_box_set_homogeneous()` to specify whether or not all children of the GtkBox are forced to get the same amount of space.

Use `gtk_box_set_spacing()` to determine how much space will be minimally placed between all children in the GtkBox.

Use `gtk_box_reorder_child()` to move a GtkBox child to a different place in the box.

Use `gtk_box_set_child_packing()` to reset the "expand", "fill" and "padding" child properties. Use `gtk_box_query_child_packing()` to query these fields.

## Details

### GtkBox

    typedef struct {
      GList *GSEAL (children);
      gint16 GSEAL (spacing);
      guint GSEAL (homogeneous) : 1;
    } GtkBox;

The GtkBox describes an instance of GtkBox and contains the following fields. (These fields should be considered read-only. They should never be set by an application.)

### GtkBoxChild

    typedef struct {
      GtkWidget *widget;
      guint16 padding;
      guint expand : 1;
      guint fill : 1;
      guint pack : 1;
      guint is_secondary : 1;
    } GtkBoxChild;

The GtkBoxChild holds a child widget of GtkBox and describes how the child is to be packed into the GtkBox. Use `gtk_box_query_child_packing()` and `gtk_box_set_child_packing()` to query and reset the `padding`, `expand`, `fill`, and `pack` fields.

GtkBoxChild contains the following fields. (These fields should be considered read-only. They should never be directly set by an application.)

GtkWidget *`widget`; | the child widget, packed into the GtkBox.
guint16 `padding`; | the number of extra pixels to put between this child and its neighbors, set when packed, zero by default.
guint `expand` : 1; | flag indicates whether extra space should be given to this child. Any extra space given to the parent GtkBox is divided up among all children with this attribute set to `TRUE`; set when packed, `TRUE` by default.
guint `fill` : 1; | flag indicates whether any extra space given to this child due to its `expand` attribute being set is actually allocated to the child, rather than being used as padding around the widget; set when packed, `TRUE` by default.
guint `pack` : 1; | one of GtkPackType indicating whether the child is packed with reference to the start (top/left) or end (bottom/right) of the GtkBox.
guint `is_secondary` : 1; | `TRUE` if the child is secondary

### gtk_box_pack_start ()

    void                gtk_box_pack_start                  (GtkBox *box,
                                                             GtkWidget *child,
                                                             gboolean expand,
                                                             gboolean fill,
                                                             guint padding);

Adds `child` to `box`, packed with reference to the start of `box`. The `child` is packed after any other child packed with reference to the start of `box`.

`box` : | a GtkBox
`child` : | the GtkWidget to be added to `box`
`expand` : | `TRUE` if the new child is to be given extra space allocated to `box`. The extra space will be divided evenly between all children of `box` that use this option
`fill` : | `TRUE` if space given to `child` by the `expand` option is actually allocated to `child`, rather than just padding it. This parameter has no effect if `expand` is set to `FALSE`. A child is always allocated the full height of a GtkHBox and the full width of a GtkVBox. This option affects the other dimension
`padding` : | extra space in pixels to put between this child and its neighbors, over and above the global amount specified by "spacing" property. If `child` is a widget at one of the reference ends of `box`, then `padding` pixels are also put between `child` and the reference edge of `box`

### gtk_box_pack_end ()

    void                gtk_box_pack_end                    (GtkBox *box,
                                                             GtkWidget *child,
                                                             gboolean expand,
                                                             gboolean fill,
                                                             guint padding);

Adds `child` to `box`, packed with reference to the end of `box`. The `child` is packed after (away from end of) any other child packed with reference to the end of `box`.

`box` : | a GtkBox
`child` : | the GtkWidget to be added to `box`
`expand` : | `TRUE` if the new child is to be given extra space allocated to `box`. The extra space will be divided evenly between all children of `box` that use this option
`fill` : | `TRUE` if space given to `child` by the `expand` option is actually allocated to `child`, rather than just padding it. This parameter has no effect if `expand` is set to `FALSE`. A child is always allocated the full height of a GtkHBox and the full width of a GtkVBox. This option affects the other dimension
`padding` : | extra space in pixels to put between this child and its neighbors, over and above the global amount specified by "spacing" property. If `child` is a widget at one of the reference ends of `box`, then `padding` pixels are also put between `child` and the reference edge of `box`

### gtk_box_pack_start_defaults ()

    void                gtk_box_pack_start_defaults         (GtkBox *box,
                                                             GtkWidget *widget);

### Warning

`gtk_box_pack_start_defaults` has been deprecated since version 2.14 and should not be used in newly-written code. Use `gtk_box_pack_start()`

Adds `widget` to `box`, packed with reference to the start of `box`. The child is packed after any other child packed with reference to the start of `box`.

Parameters for how to pack the child `widget`, "expand", "fill" and "padding", are given their default values, `TRUE`, `TRUE`, and 0, respectively.

`box` : | a GtkBox
`widget` : | the GtkWidget to be added to `box`

### gtk_box_pack_end_defaults ()

    void                gtk_box_pack_end_defaults           (GtkBox *box,
                                                             GtkWidget *widget);

### Warning

`gtk_box_pack_end_defaults` has been deprecated since version 2.14 and should not be used in newly-written code. Use `gtk_box_pack_end()`

Adds `widget` to `box`, packed with reference to the end of `box`. The child is packed after any other child packed with reference to the start of `box`.

Parameters for how to pack the child `widget`, "expand", "fill" and "padding", are given their default values, `TRUE`, `TRUE`, and 0, respectively.

`box` : | a GtkBox
`widget` : | the GtkWidget to be added to `box`

### gtk_box_get_homogeneous ()

    gboolean            gtk_box_get_homogeneous             (GtkBox *box);

Returns whether the box is homogeneous (all children are the same size). See `gtk_box_set_homogeneous()`.

`box` : | a GtkBox
Returns : | `TRUE` if the box is homogeneous.

### gtk_box_set_homogeneous ()

    void                gtk_box_set_homogeneous             (GtkBox *box,
                                                             gboolean homogeneous);

Sets the "homogeneous" property of `box`, controlling whether or not all children of `box` are given equal space in the box.

`box` : | a GtkBox
`homogeneous` : | a boolean value, `TRUE` to create equal allotments, `FALSE` for variable allotments

### gtk_box_get_spacing ()

    gint                gtk_box_get_spacing                 (GtkBox *box);

Gets the value set by `gtk_box_set_spacing()`.

`box` : | a GtkBox
Returns : | spacing between children

### gtk_box_set_spacing ()

    void                gtk_box_set_spacing                 (GtkBox *box,
                                                             gint spacing);

Sets the "spacing" property of `box`, which is the number of pixels to place between children of `box`.

`box` : | a GtkBox
`spacing` : | the number of pixels to put between children

### gtk_box_reorder_child ()

    void                gtk_box_reorder_child               (GtkBox *box,
                                                             GtkWidget *child,
                                                             gint position);

Moves `child` to a new `position` in the list of `box` children. The list is the `children` field of GtkBox, and contains both widgets packed GTK_PACK_START as well as widgets packed GTK_PACK_END, in the order that these widgets were added to `box`.

A widget's position in the `box` children list determines where the widget is packed into `box`. A child widget at some position in the list will be packed just after all other widgets of the same packing type that appear earlier in the list.

`box` : | a GtkBox
`child` : | the GtkWidget to move
`position` : | the new position for `child` in the list of children of `box`, starting from 0. If negative, indicates the end of the list

### gtk_box_query_child_packing ()

    void                gtk_box_query_child_packing         (GtkBox *box,
                                                             GtkWidget *child,
                                                             gboolean *expand,
                                                             gboolean *fill,
                                                             guint *padding,
                                                             GtkPackType *pack_type);

Obtains information about how `child` is packed into `box`.

`box` : | a GtkBox
`child` : | the GtkWidget of the child to query
`expand` : | pointer to return location for "expand" child property
`fill` : | pointer to return location for "fill" child property
`padding` : | pointer to return location for "padding" child property
`pack_type` : | pointer to return location for "pack-type" child property

### gtk_box_set_child_packing ()

    void                gtk_box_set_child_packing           (GtkBox *box,
                                                             GtkWidget *child,
                                                             gboolean expand,
                                                             gboolean fill,
                                                             guint padding,
                                                             GtkPackType pack_type);

Sets the way `child` is packed into `box`.

`box` : | a GtkBox
`child` : | the GtkWidget of the child to set
`expand` : | the new value of the "expand" child property
`fill` : | the new value of the "fill" child property
`padding` : | the new value of the "padding" child property
`pack_type` : | the new value of the "pack-type" child property

## Property Details

### The `"homogeneous"` property

      "homogeneous"              gboolean              : Read / Write

Whether the children should all be the same size.

Default value: FALSE

### The `"spacing"` property

      "spacing"                  gint                  : Read / Write

The amount of space between children.

Allowed values: >= 0

Default value: 0

## Child Property Details

### The `"expand"` child property

      "expand"                   gboolean              : Read / Write

Whether the child should receive extra space when the parent grows.

Default value: TRUE

### The `"fill"` child property

      "fill"                     gboolean              : Read / Write

Whether extra space given to the child should be allocated to the child or used as padding.

Default value: TRUE

### The `"pack-type"` child property

      "pack-type"                GtkPackType           : Read / Write

A GtkPackType indicating whether the child is packed with reference to the start or end of the parent.

Default value: GTK_PACK_START

### The `"padding"` child property

      "padding"                  guint                 : Read / Write

Extra space to put between the child and its neighbors, in pixels.

Allowed values: <= G_MAXINT

Default value: 0

### The `"position"` child property

      "position"                 gint                  : Read / Write

The index of the child in the parent.

Allowed values: >= G_MAXULONG

Default value: 0

## See Also

GtkHBox | a derived class that organizes widgets into a row.
GtkVBox | a derived class that organizes widgets into a column.
GtkFrame | a GtkWidget useful for drawing a border around a GtkBox.
GtkTable | a GtkContainer for organizing widgets into a grid, rather than independent rows or columns.
GtkLayout | a GtkContainer for organizing widgets into arbitrary layouts.