GtkBox: GTK+ 2 Reference Manual

## GtkBox GtkBox — Base class for box containers |

## Functions

void | gtk_box_pack_start ()
void | gtk_box_pack_end ()
void | gtk_box_pack_start_defaults ()
void | gtk_box_pack_end_defaults ()
gboolean | gtk_box_get_homogeneous ()
void | gtk_box_set_homogeneous ()
gint | gtk_box_get_spacing ()
void | gtk_box_set_spacing ()
void | gtk_box_reorder_child ()
void | gtk_box_query_child_packing ()
void | gtk_box_set_child_packing ()

## Properties

gboolean | homogeneous | Read / Write
gint | spacing | Read / Write

## Child Properties

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

## Types and Values

struct | GtkBox
struct | GtkBoxChild

## Object Hierarchy

        GObject
        ╰── GInitiallyUnowned
            ╰── GtkObject
                ╰── GtkWidget
                    ╰── GtkContainer
                        ╰── GtkBox
                            ├── GtkButtonBox
                            ├── GtkVBox
                            ╰── GtkHBox

## Implemented Interfaces

GtkBox implements AtkImplementorIface, GtkBuildable and GtkOrientable.

## Includes

    #include <gtk/gtk.h>

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

## Functions

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

#### Parameters

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

#### Parameters

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

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

#### Parameters

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

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

#### Parameters

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

#### Parameters

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.

#### Parameters

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

#### Parameters

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

#### Parameters

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.

#### Parameters

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

#### Parameters

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

#### Parameters

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 |

## Types and Values

### struct GtkBox

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

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

### struct GtkBoxChild

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

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

Use `gtk_container_get_children()` instead.

The GtkBoxChild holds a child widget of GtkBox and describes how the child is to be packed into the GtkBox. All fields of this GtkBoxChild should be considered read-only and they should never be set directly by an application. Use `gtk_box_query_child_packing()` and `gtk_box_set_child_packing()` to query and set the GtkBoxChild.padding, GtkBoxChild.expand, GtkBoxChild.fill and GtkBoxChild.pack fields.

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

#### Members

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 |

## Property Details

### The `“homogeneous”` property

      “homogeneous”              gboolean

Whether the children should all be the same size.

Flags: Read / Write

Default value: FALSE

### The `“spacing”` property

      “spacing”                  gint

The amount of space between children.

Flags: Read / Write

Allowed values: >= 0

Default value: 0

## Child Property Details

### The `“expand”` child property

      “expand”                   gboolean

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

Flags: Read / Write

Default value: TRUE

### The `“fill”` child property

      “fill”                     gboolean

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

Flags: Read / Write

Default value: TRUE

### The `“pack-type”` child property

      “pack-type”                GtkPackType

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

Flags: Read / Write

Default value: GTK_PACK_START

### The `“padding”` child property

      “padding”                  guint

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

Flags: Read / Write

Allowed values: <= G_MAXINT

Default value: 0

### The `“position”` child property

      “position”                 gint

The index of the child in the parent.

Flags: Read / Write

Allowed values: >= -1

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.