6.5 The box widget

6.5.1 Description

The box widget is a container (see section 6.13 The container widget) derived from the container widget. It is an abstract base class used by the horizontal box (see section 6.25 The horizontal box widget), the vertical box (see section 6.65 The vertical box widget) and the (see section 6.6 The button box widget) widgets to provide a base of common functionality.

A box provides an abstraction for organizing the position and size of widgets. Widgets in a box are laid out horizontally or vertically. By using a box widget appropriately, a programmer can control how widgets are positioned and how they will be allocated space when a window gets resized.

The key attribute of boxes is that they position their children in a single row (horizontal boxes) or column (vertical boxes). In the case of horizontal boxes, all children are stretched vertically. The vertical size of the box is determined by the largest vertical requisition of all of its children. Similarly, a vertical box stretches all of its children horizontally. The horizontal size (of the vertical box) is determined by the largest horizontal requisition of all of its children. An alignment widget (see section 6.1 The alignment widget) can be used to control child allocation more precisely on a per child basis.

The second attribute of boxes is how they expand children. In the case of a horizontal box, the main control is over how children are expanded horizontally to fill the allocated area. (The rest of this discussion will focus on horizontal boxes but it applies to vertical boxes as well).

There are two flags which can be set controlling how a widget is expanded horizontally in a horizontal box. These are the expand and fill. There operation is fairly simple. If expand is set, the child's potentially allocated area will expand to fill available space. If fill is set, the child's actual allocated area will be its potentially allocated area. There is a difference between the potentially area (which is the area the box widget sets aside for the child) and the actual allocated area (which is the area the box widget actual allocates for the widget via gtk_widget_size_allocate).

The allocation of space to children occurs as follows (for horizontal boxes):

1. All children are allocated at least their requested size horizontally and the maximum requested child size vertically.
2. Any child with the expand flag set is allocated extra_width / nexpand_children extra pixels horizontally. If the homogeneous flag was set, all children are considered to have the expand flag set. That is, all children will be allocated the same area.The horizontal box is a fair widget and, as such, divides up any extra allocated space evenly among the "expand" children. (Those children which have the expand flag set). The exception occurs when extra_width / nexpand_children does not divide cleanly. The extra space is given to the last widget.
3. spacing number of pixels separate each child. Note: The separation is between the potentially allocated area for each child and not the actual allocated area. The padding value associated with each child causes that many pixels to be left empty to each side of the child.
4. If a child has the fill flag set it is allocated its potentially allocated area. If it does not, it is allocated its requested size horizontally and centered within its potentially allocated area. Its vertical allocation is still the maximum requested size of any child.
5. Children placed at the start of the box are placed in order of addition to the box from left to right in the boxes allocated area.. Children placed at the end of the box are placed in order of addition from right to left in the boxes allocated area.

See section 6.25 The horizontal box widget, and section 6.65 The vertical box widget, for code examples of using horizontal and vertical boxes.

6.5.2 Options

User Option: expand

User Option: fill

User Option: padding

User Option: expand

6.5.3 Signals

6.5.4 Functions

Function: guint gtk_box_get_type (void)

Returns the GtkBox type identifier.

Function: void gtk_box_pack_start (GtkBox *box, GtkWidget *child, gint expand, gint fill, gint padding)

Add child to the front of box. The flags expand and fill and the padding value of padding are associated with child.

Function: void gtk_box_pack_end (GtkBox *box, GtkWidget *child, gint expand, gint fill, gint padding)

Add child to the end of box. The flags expand and fill and the padding value of padding are associated with child.

Function: void gtk_box_pack_start_defaults (GtkBox *box, GtkWidget *widget)

A convenience function which is equivalent to the following:

  gtk_box_pack_start (box, widget, TRUE, TRUE, 0);

Function: void gtk_box_pack_end_defaults (GtkBox *box, GtkWidget *widget)

A convenience function which is equivalent to the following:

  gtk_box_pack_start (box, widget, TRUE, TRUE, 0);

Function: void gtk_box_set_homogeneous (GtkBox *box, gint homogeneous)

Set the homogeneous setting of this box to homogeneous.

Function: void gtk_box_set_spacing (GtkBox *box, gint spacing)

Function: void gtk_box_reorder_child (GtkBox *box, GtkWidget *child, guint pos)

Function: void gtk_box_query_child_packing (GtkBox *box, GtkWidget *child, gint *expand, gint *fill, gint *padding, GtkPackType *pack_type)

Function: void gtk_box_set_child_packing (GtkBox *box, GtkWidget *child, gint expand, gint fill, gint padding, GtkPackType *pack_type)

@gtkstdmacros{Box, BOX}

Go to the first, previous, next, last section, table of contents.