--- /dev/null
+<?xml version="1.0"?>
+<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.3//EN"
+ "http://www.oasis-open.org/docbook/xml/4.3/docbookx.dtd" [
+]>
+<chapter id="gtk-migrating-GtkGrid">
+
+ <title>Migrating from other containers to GtkGrid</title>
+
+ <para>
+ #GtkGrid is an attempt to write a comprehensive, legacy-free,
+ box-layout container that is flexible enough to replace #GtkBox,
+ #GtkTable, #GtkAlignment and the like.
+ </para>
+
+ <para>
+ The layout model of GtkGrid is to arrange its children in rows and
+ columns (children can span multiple rows or columns, too). This is
+ done by assigning positions (and sizes) on a two-dimentions grid that
+ stretches arbitrarily far in all directions.
+ </para>
+
+ <section>
+
+ <title>GtkBox versus GtkGrid: packing</title>
+
+ <para>
+ 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().
+ </para>
+
+ <inlinegraphic fileref="box-packing.png" format="PNG"></inlinegraphic>
+
+ <example>
+ <title>A simple box</title>
+ <programlisting>
+ 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);
+ </programlisting>
+ <para>This can be done with #GtkGrid as follows:</para>
+ <programlisting>
+ 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);
+ </programlisting>
+ <para>
+ 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.
+ </para>
+ </example>
+
+ <para>
+ 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.
+ </para>
+ <para>
+ 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.
+ </para>
+ </section>
+
+ <section>
+ <title>GtkBox versus GtkGrid: sizing</title>
+
+ <para>
+ When adding a child to a GtkBox, there are two hard-to-remember
+ parameters (child properties, more exactly) named expand and fill
+ that determine how the child size behaves in the main direction
+ of the box. If expand is set, the box allows the position occupied
+ by the child to grow when extra space is available. If fill is
+ also set, the extra space is allocated to the child widget itself.
+ Otherwise it is left 'free'.
+ There is no control about the 'minor' direction; children
+ are always given the full size in the minor direction.
+ </para>
+
+ <inlinegraphic fileref="box-expand.png" format="PNG"></inlinegraphic>
+
+ <para>
+ GtkGrid does not have any custom child properties for controlling
+ size allocation to children. Instead, it fully supports the newly
+ introduced #GtkWidget:hexpand, #GtkWidget:vexpand, #GtkWidget:halign
+ and #GtkWidget:valign properties.
+ </para>
+ <para>
+ The #GtkWidget:hexpand and #GtkWidget:vexpand properties operate
+ in a similar way to the expand child properties of #GtkBox. As soon
+ as a column contains a hexpanding child, GtkGrid allows the column
+ to grow when extra space is available (similar for rows and vexpand).
+ In contrast to GtkBox, all the extra space is always allocated
+ to the child widget, there are no 'free' areas.
+ </para>
+ <para>
+ To replace the functionality of the fill child properties, you can
+ set the #GtkWidget:halign and #GtkWidget:valign properties. An
+ align value of #GTK_ALIGN_FILL has the same effect as setting fill
+ to %TRUE, a value of #GTK_ALIGN_CENTER has the same effect as setting
+ fill to %FALSE. The image below shows the effect of various combinations
+ of halign and valign.
+ </para>
+
+ <inlinegraphic fileref="widget-hvalign.png" format="PNG"></inlinegraphic>
+
+ <example>
+ <title>Expansion and alignment</title>
+ <programlisting>
+ box = gtk_box_new (GTK_ORIENTATION_HORIZONTAL, 0);
+
+ gtk_box_pack_start (GTK_BOX (box), gtk_label_new ("One"), TRUE, FALSE, 0);
+ gtk_box_pack_start (GTK_BOX (box), gtk_label_new ("Two"), TRUE, TRUE, 0);
+ </programlisting>
+ <para>This can be done with #GtkGrid as follows:</para>
+ <programlisting>
+ grid = gtk_grid_new ();
+
+ child1 = gtk_label_new ("One");
+ gtk_widget_set_hexpand (child1, TRUE);
+ gtk_widget_set_halign (child1, GTK_ALIGN_CENTER);
+ gtk_grid_attach (GTK_GRID (grid), child1, 0, 0, 1, 1);
+ child2 = gtk_label_new ("Two");
+ gtk_widget_set_hexpand (child2, TRUE);
+ gtk_widget_set_halign (child1, GTK_ALIGN_FILL);
+ gtk_grid_attach_next_to (GTK_GRID (grid), child2, child1, GTK_POS_RIGHT, 1, 1);
+ </programlisting>
+ </example>
+ <para>
+ One difference between the new GtkWidget expand properties and
+ the GtkBox child property of the same name is that widget expandability
+ is 'inherited' from children. What this means is that a container
+ will become itself expanding as soon as it has
+ an expanding child. This is typically what you want, it lets
+ you e.g. mark the content pane of your application window as
+ expanding, and all the intermediate containers between the
+ content pane and the toplevel window will automatically do
+ the right thing. This automatism can be overridden at any
+ point by setting the expand flags on a container explicitly.
+ </para>
+ <para>
+ Another difference between GtkBox and GtkGrid with respect to
+ expandability is when there are no expanding children at all.
+ In this case, GtkBox will forcibly expand all children whereas
+ GtkGrid will not. In practice, the effect of this is typically
+ that a grid will 'stick to the corner' when the toplevel
+ containing it is grown, instead of spreading out its children
+ over the entire area. The problem can be fixed by setting some
+ or all of the children to expand.
+ </para>
+
+ <para>
+ When you set the #GtkBox:homogeneous property on a GtkBox,
+ it reserves the same space for all its children. GtkGrid does
+ this in a very similar way, with #GtkGrid:row-homogeneous and
+ #GtkGrid:column-homogeneous properties which control whether
+ all rows have the same height and whether all columns have
+ the same width.
+ </para>
+ </section>
+
+<!--
+ <section>
+ <title>GtkBox versus GtkGrid: spacing</title>
+ cover here: spacing, padding, margins
+ </section>
+
+ <section>
+ <title>GtkTable versus GtkGrid</title>
+ cover here: spanning, attachment points, grid size, attach options vs expand/align
+
+ </section>
+-->
+</chapter>
projects / ~andy / gtk / commitdiff
