Containers And Widget Layout

Requisition

A widget's requisition consists of a width and a height---the size the widget would like to be. This is represented by a GtkRequisition struct:

typedef struct _GtkRequisition    GtkRequisition;

struct _GtkRequisition
{
  gint16 width;
  gint16 height;
};

Different widgets choose what size to request in different ways. GtkLabel, for example, requests enough size to display all the text in the label. Most container widgets base their size request on the size requests of their children. For example, if you place several buttons in a box, the box will ask to be large enough to hold all the buttons.

The first phase of layout starts with a toplevel widget such as GtkWindow. Since it's a container, GtkWindow asks its child widget for a size request; that child might ask its own children; and so on recursively. When all child widgets have been queried, GtkWindow will finally get a GtkRequisition back from its child. Depending on how it was configured, GtkWindow may or may not be able to expand to accomodate the size request.

Allocation

Phase two of layout begins at this point. GtkWindow makes a decision about how much space is actually available for its child, and communicates its decision to the child. This is known as the child's allocation, represented by the following struct:

typedef struct _GtkAllocation     GtkAllocation;

struct _GtkAllocation
{
  gint16 x;
  gint16 y;
  guint16 width;
  guint16 height;
};

The width and height elements are identical to GtkRequisition; they represent the size of the widget. A GtkAllocation also includes the coordinates of the child with respect to its parent. GtkAllocations are assigned to children by their parent container.

Widgets are required to honor the GtkAllocation given to them. GtkRequisition is only a request; widgets must be able to cope with any size.

Given the layout process, it's easy to see what role containers play. Their job is to assemble each child's requisition into a single requisition to be passed up the widget tree; then to divide the allocation they receive between their children. Exactly how this happens depends on the particular container.

GtkBox Layout Details

Packing is affected by three parameters, which are the same for both start and end packing; the meaning of these parameters is somewhat complicated, because they interact with the homogeneous setting of the box and with each other.

Here's how a GtkBox computes its size request for the "interesting" direction (width for GtkHBox, height for GtkVBox):

1. The total requested size of each child is considered to be the child's size request, plus two times the padding value used to pack the child. A child's padding is the amount of blank space on either side of it. In short, Child Size = (Child Widget's Size Request) + 2*(Child Padding).

2. If the box is homogeneous, the base size request for the entire box is equal to the size (request + padding) of the largest child, times the number of children. In a homogeneous box, all children are as large as the largest child.

3. If the box is not homogeneous, the base size request for the entire box is the sum of the size (request + padding) of each child.

4. The box-wide spacing setting determines how much blank space to leave between children; so this value is multiplied by the number of chilren minus one, and added to the base size request. Note that spacing does not belong to a child; it is blank space between children and is unaffected by the expand and fill parameters. Padding, on the other hand, is the space around each child and is affected by the child's packing parameters.

5. All containers have a "border width" setting; two times the border width is added to the request, representing a border on either side. Thus, the total size requested by a GtkBox is: (Sum of Child Sizes) + Spacing*(Number of Children - 1) + 2*(Border Width).

After computing its size request and delivering it to its parent container, GtkBox will receive its size allocation and distribute it among its children as follows:

1. Enough space for the border width and inter-child spacing is subtracted from the allocation; the remainder is the available space for children themselves. This space is divided into two chunks: the amount actually requested by the children (child requisitions and padding), and the "extra." Extra = (Allocation Size) - (Sum of Child Sizes).

2. If the box is not homogeneous, the "extra" space is divided among those children with the expand parameter set to TRUE. These children can expand to fit available space. If no child can expand, the extra is used to add more space in the center of the box, between the start-packed widgets and the end-packed widgets.

3. If the box is homogeneous, the extra is distributed according to need; those children who requested more space get less extra, so that everyone ends up with the same amount of space. The expand parameter is ignored for homogeneous boxes---extra is distributed to all children, not just the expandable ones.

4. When a child gets some extra space, there are two possibilities. More padding can be added around the child, or the child widget itself can be expanded. The fill parameter determines which will happen. If TRUE, the child widget expands to fill the space---that is, the entire space becomes the child's allocation; if fill is FALSE, the child's padding is increased to fill the space, and the child is allocated only the space it requested. Note that fill has no effect if expand is set to FALSE and the box is not homogeneous, because the child will never receive any extra space to fill.

Whew! Who wants to think about all that? Fortunately, there are some common patterns of usage, so you don't need to solve a multivariate equation to figure out how to use the widget. The authors of the GTK+ Tutorial boil things down nicely to five cases that occur in practice; we'll follow in their footsteps here.

Non-Homogeneous Box Packing Patterns

There are three interesting ways to pack a non-homogeneous box. First, you can pack all the widgets into the end of the box, with their natural size. This means setting the expand parameter to FALSE:

  gtk_box_pack_start(GTK_BOX(box),
                     child, 
                     FALSE, FALSE, 0);

The result is shown in Figure 6. The expand parameter is the only one that matters in this case; no children are receiving extra space, so they wouldn't be able to fill it even if fill were TRUE.

Second, you can spread widgets throughout the box, letting them keep their natural size as in Figure 7; this means setting the expand parameter to TRUE:

  gtk_box_pack_start(GTK_BOX(box),
                     child, 
                     TRUE, FALSE, 0);

Finally, you can fill the box with widgets (letting larger children have more space) by setting the fill parameter to TRUE as well:

  gtk_box_pack_start(GTK_BOX(box),
                     child, 
                     TRUE, TRUE, 0);

This configuration is shown in Figure 8

Homogeneous Box Packing Patterns

There are only two interesting ways to pack a homogeneous box. Recall that the expand parameter is irrelevant for homogeneous boxes; so the two cases correspond to the fill parameter's setting.

If fill is FALSE, you get Figure 9. Notice that the box is logically divided into three equal parts, but only the largest child widget occupies its entire space. The others are padded to fill their third of the area. If fill is TRUE, you get Figure 10; all the widgets are the same size.

Box Packing Summary

Figure Figure 11 shows all five box-packing techniques together. (They are packed into a homogeneous GtkVBox with fill set to TRUE and an interchild spacing of two pixels.) This should give you a sense of their relative effects. Keep in mind that you can also tweak the padding and spacing parameters, to increase or decrease the amount of blank space between widgets. However, you can easily create an ugly layout by using inconsistent spacing---it's a good idea to try to keep widgets "lined up" and consistently spaced.

A final point: notice that the expand and fill parameters are only relevant when a box's size allocation is larger than its size request. That is, these parameters determine how extra space is distributed. Typically, extra space appears when a user resizes a window to make it larger than its default size. Thus, you should always try resizing your windows to be sure your boxes are packed correctly.

GtkTable Example

The following code creates a table with four cells and three children; one child covers two cells. The children are packed using different parameters:

  GtkWidget* window;
  GtkWidget* button;
  GtkWidget* container;

  window = gtk_window_new(GTK_WINDOW_TOPLEVEL);

  container = gtk_table_new(2, 2, FALSE);

  gtk_container_add(GTK_CONTAINER(window), container);

  gtk_window_set_title(GTK_WINDOW(window), "Table Attaching");

  gtk_container_set_border_width(GTK_CONTAINER(container), 10);

  /* This would be a bad idea in real code; but it lets us 
   * experiment with window resizing. 
   */
  gtk_window_set_policy(GTK_WINDOW(window), TRUE, TRUE, TRUE);

  gtk_signal_connect(GTK_OBJECT(window),
                     "delete_event",
                     GTK_SIGNAL_FUNC(delete_event_cb),
                     NULL);

  button = gtk_button_new_with_label("1. Doesn't shrink\nor expand");
  gtk_table_attach(GTK_TABLE(container),
                   button,
                   0, 1,
                   0, 1,
                   GTK_FILL,
                   GTK_FILL,
                   0, 
                   0);

  button = gtk_button_new_with_label("2. Expands and shrinks\nvertically");
  gtk_table_attach(GTK_TABLE(container),
                   button,
                   0, 1,
                   1, 2,
                   GTK_FILL,
                   GTK_FILL | GTK_EXPAND | GTK_SHRINK,
                   0, 
                   0);

  button = gtk_button_new_with_label("3. Expands and shrinks\nin both directions");
  gtk_table_attach(GTK_TABLE(container),
                   button,
                   1, 2,
                   0, 2,
                   GTK_FILL | GTK_EXPAND | GTK_SHRINK,
                   GTK_FILL | GTK_EXPAND | GTK_SHRINK,
                   0, 
                   0);

It's instructive to observe the resulting table as the window is resized. First, a quick summary of how the children are attached:

1. The first child will always receive its requested size; it neither expands nor shrinks.

2. The second child can expand and shrink only in the Y direction.

3. The third child can expand and shrink in either direction.

The window's natural size is shown in Figure 13; notice that some cells are given more space than the widgets inside them requested because table cells have to remain aligned. (Recall that a button with a label will request only enough space to display the entire label.) The GTK_FILL flag causes GtkTable to allocate extra space to the widgets themselves, instead of leaving blank padding around them.

Now imagine the user expands the window vertically; notice that extra space is given to the widgets with GTK_EXPAND turned on in the Y direction---namely widgets two and three---while the widget in the top-left corner remains unchanged. Figure 14 shows this state of affairs.

Next, imagine the user expanding the window horizontally; only child widget number three can expand horizontally. Figure 15 shows this.

Figure 16 shows the result if the user shrinks the table vertically, so that there isn't enough vertical space to give all the widgets their size requests. Child number two gets shortchanged, while child number one gets all the vertical space it needs.

Finally, Figure 17 shows the result if the user shrinks the table horizontally. Child number three gets the short end of the stick in this situation.

It's not a bad idea to try resizing your window like this whenever you're designing a layout, just to be sure something sane happens. The definition of "sane" varies with the exact widgets you've placed in the layout.

Using gtk_table_attach_defaults()

Since gtk_table_attach() is somewhat cumbersome, there's a simpler version called gtk_table_attach_defaults(), shown in Figure 18. This version attaches the child with the options GTK_EXPAND and GTK_FILL, and no padding.

It's tempting to use gtk_table_attach_defaults() all the time to save typing, but really you shouldn't; in fact, it's probably fair to say that it's rarely used. The function is only useful if the defaults happen to be exactly the settings you want. Most of the time, you need to carefully tweak your table attachment parameters to get really nice behavior when your window is resized. Always try resizing your window to be sure you've designed your layout well.

#include <gtk/gtktable.h>