GTK+ Reference Manual
<<< Previous Page | Home | Up | Next Page >>>

# GtkBox

## Name

GtkBox -- a base class for box containers

## Synopsis

    #include <gtk/gtk.h>

    struct      GtkBox;
    struct      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
       +----GtkObject
             +----GtkWidget
                   +----GtkContainer
                         +----GtkBox

## Properties

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

## Child Properties

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

## Description

GtkBox is an abstract widget which encapsulates functionallity for a particular kind of container, one that organizes a variable number of widgets into a rectangular area. GtkBox currently has two derived classes, 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` attributes of 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` attributes of any GtkBox child. Use gtk_box_query_child_packing() to query these fields.

## Details

### struct GtkBox

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

GList * `children`; | a list of children belonging the GtkBox. The data is a list of structures of type GtkBoxChild.
gint16 `spacing`; | the number of pixels to put between children of the GtkBox, zero by default. Use gtk_box_set_spacing() to set this field.
guint `homogeneous`; | a flag that if `TRUE` forces all children to get equal space in the GtkBox; `FALSE` by default. Use gtk_box_set_homogeneous() to set this field.

### struct GtkBoxChild

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

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`; | 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`; | 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`; | one of GtkPackType indicating whether the child is packed with reference to the start (top/left) or end (bottom/right) of the GtkBox.

### 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` in GtkBox. 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` in GtkBox. 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);

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

Adds `widget` 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 for how to pack the child `widget`, `expand`, `fill`, and `padding` in GtkBoxChild, 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` field of GtkBox, 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` field of GtkBox, 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 `children` list of GtkBox, 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);

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

`box` : | a GtkBox.
`child` : | the GtkWidget of the child to query.
`expand` : | the returned value of the `expand` field in GtkBoxChild.
`fill` : | the returned value of the `fill` field in GtkBoxChild.
`padding` : | the returned value of the `padding` field in GtkBoxChild.
`pack_type` : | the returned value of the `pack` field in GtkBoxChild.

### 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` field in GtkBoxChild.
`fill` : | the new value of the `fill` field in GtkBoxChild.
`padding` : | the new value of the `padding` field in GtkBoxChild.
`pack_type` : | the new value of the `pack` field in GtkBoxChild.

## Properties

"`spacing`" (gint : Read / Write)

  The amount of space between children.

"`homogeneous`" (gboolean : Read / Write)

  Whether the children should all be the same size.

## Child Properties

"`expand`" (gboolean : Read / Write)

  Whether the child should receive extra space when the parent grows

"`fill`" (gboolean : Read / Write)

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

"`padding`" (guint : Read / Write)

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

"`pack-type`" (GtkPackType : Read / Write)

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

"`position`" (gint : Read / Write)

  The index of the child in the parent

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

<<< Previous Page | Home | Up | Next Page >>>
GtkBin | GtkButtonBox