GNOME.org
 

[gtk+] Add an initial migration chapter for GtkGrid

commit 3ace68ee6f143abbcd1cc2f38f6595557dc2eaa5
Author: Matthias Clasen <mclasen redhat com>
Date:   Wed May 11 23:55:54 2011 -0400

    Add an initial migration chapter for GtkGrid

 docs/reference/gtk/Makefile.am               |    6 +
 docs/reference/gtk/gtk-docs.sgml             |    1 +
 docs/reference/gtk/images/box-expand.png     |  Bin 0 -> 2372 bytes
 docs/reference/gtk/images/box-packing.png    |  Bin 0 -> 3561 bytes
 docs/reference/gtk/images/widget-hvalign.png |  Bin 0 -> 7323 bytes
 docs/reference/gtk/migrating-GtkGrid.xml     |  185 ++++++++++++++++++++++++++
 6 files changed, 192 insertions(+), 0 deletions(-)
---
diff --git a/docs/reference/gtk/Makefile.am b/docs/reference/gtk/Makefile.am
index a9bdd74..7c643b5 100644
--- a/docs/reference/gtk/Makefile.am
+++ b/docs/reference/gtk/Makefile.am
@@ -124,6 +124,7 @@ content_files =					\
 	migrating-2to3.xml			\
 	migrating-checklist.sgml		\
 	migrating-GtkApplication.xml		\
+	migrating-GtkGrid.xml			\
 	migrating-GtkStyleContext.xml		\
 	objects_grouped.sgml			\
 	osx.sgml				\
@@ -146,6 +147,7 @@ expand_content_files = 				\
 	migrating-2to3.xml			\
 	migrating-checklist.sgml		\
 	migrating-GtkApplication.xml		\
+	migrating-GtkGrid.xml			\
 	migrating-GtkStyleContext.xml		\
 	question_index.sgml			\
 	text_widget.sgml			\
@@ -277,6 +279,8 @@ HTML_IMAGES = \
 	$(srcdir)/images/appchooserbutton.png				\
 	$(srcdir)/images/appchooserdialog.png				\
 	$(srcdir)/images/assistant.png					\
+	$(srcdir)/images/box-packing.png				\
+	$(srcdir)/images/box-expand.png				\
 	$(srcdir)/images/button.png					\
 	$(srcdir)/images/check-button.png				\
 	$(srcdir)/images/color-button.png				\
@@ -296,6 +300,7 @@ HTML_IMAGES = \
 	$(srcdir)/images/label.png					\
 	$(srcdir)/images/link-button.png				\
 	$(srcdir)/images/list-and-tree.png				\
+	$(srcdir)/images/lockbutton.png				\
 	$(srcdir)/images/lockbutton-locked.png				\
 	$(srcdir)/images/lockbutton-unlocked.png			\
 	$(srcdir)/images/lockbutton-sorry.png				\
@@ -329,6 +334,7 @@ HTML_IMAGES = \
 	$(srcdir)/images/layout-rltb.png				\
 	$(srcdir)/images/layout-tblr.png				\
 	$(srcdir)/images/layout-tbrl.png				\
+	$(srcdir)/images/widget-hvalign.png				\
 	$(srcdir)/images/window-default.png				\
 	$(srcdir)/images/hello-world.png				\
 	$(srcdir)/images/grid-packing.png				\
diff --git a/docs/reference/gtk/gtk-docs.sgml b/docs/reference/gtk/gtk-docs.sgml
index a2bd082..11d14ab 100644
--- a/docs/reference/gtk/gtk-docs.sgml
+++ b/docs/reference/gtk/gtk-docs.sgml
@@ -355,6 +355,7 @@
     <xi:include href="xml/migrating-2to3.xml" />
     <xi:include href="xml/migrating-GtkApplication.xml" />
     <xi:include href="xml/migrating-GtkStyleContext.xml" />
+    <xi:include href="xml/migrating-GtkGrid.xml" />
   </part>
 
   <part>
diff --git a/docs/reference/gtk/images/box-expand.png b/docs/reference/gtk/images/box-expand.png
new file mode 100644
index 0000000..e5af4f2
Binary files /dev/null and b/docs/reference/gtk/images/box-expand.png differ
diff --git a/docs/reference/gtk/images/box-packing.png b/docs/reference/gtk/images/box-packing.png
new file mode 100644
index 0000000..1ee108c
Binary files /dev/null and b/docs/reference/gtk/images/box-packing.png differ
diff --git a/docs/reference/gtk/images/widget-hvalign.png b/docs/reference/gtk/images/widget-hvalign.png
new file mode 100644
index 0000000..60a6cb3
Binary files /dev/null and b/docs/reference/gtk/images/widget-hvalign.png differ
diff --git a/docs/reference/gtk/migrating-GtkGrid.xml b/docs/reference/gtk/migrating-GtkGrid.xml
new file mode 100644
index 0000000..5d5a9f9
--- /dev/null
+++ b/docs/reference/gtk/migrating-GtkGrid.xml
@@ -0,0 +1,185 @@
+<?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 &mdash; 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>
[Date Prev][Date Next]   [Thread Prev][Thread Next]   [Thread Index] [Date Index] [Author Index]