Migrating from other containers to GtkGrid

GtkBox versus GtkGrid: packing
GtkBox versus GtkGrid: sizing
GtkBox versus GtkGrid: spacing

GtkGrid is an attempt to write a comprehensive, legacy-free, box-layout container that is flexible enough to replace GtkBox, GtkTable and the like.

The layout model of GtkGrid is to arrange its children in rows and columns. This is done by assigning positions on a two-dimentions grid that stretches arbitrarily far in all directions. Children can span multiple rows or columns, too.

GtkBox versus GtkGrid: packing

GtkBox works by arranging child widgets in a single line, either horizontally or vertically. It allows packing children from the beginning or end, using gtk_box_pack_start() and gtk_box_pack_end().

Example 128. A simple box

  box = gtk_box_new (GTK_ORIENTATION_HORIZONTAL, 0);

  gtk_box_pack_start (GTK_BOX (box), gtk_label_new ("One"), FALSE, FALSE, 0);
  gtk_box_pack_start (GTK_BOX (box), gtk_label_new ("Two"), FALSE, FALSE, 0);

This can be done with GtkGrid as follows:

  grid = gtk_grid_new ();

  child1 = gtk_label_new ("One");
  gtk_grid_attach (GTK_GRID (grid), child1, 0, 0, 1, 1);
  child2 = gtk_label_new ("Two");
  gtk_grid_attach_next_to (GTK_GRID (grid), child2, child1, GTK_POS_RIGHT, 1, 1);

And similarly for gtk_box_pack_end(). In that case, you would use GTK_POS_LEFT to place the grid children from left to right.

If you only need to pack children from the start, using gtk_container_add() is an even simpler alternative. GtkGrid places children added with gtk_container_add() in a single row or column according to its "orientation".

One difference to keep in mind is that the gtk_box_pack_start/pack_end functions allow you to place an arbitrary number of children from either end without ever 'colliding in the middle'. With GtkGrid, you have to leave enough space between the two ends, if you want to combine packing from both ends towards the middle. In practice, this should be easy to avoid; and GtkGrid simply ignores entirely empty rows or columns for layout and spacing.

On the other hand, GtkGrid is more flexible in that its grid extends indefinitively in both directions — there is no problem with using negative numbers for the grid positions. So, if you discover that you need to place a widget before your existing arrangement, you always can.