diff --git a/docs/reference/gtk/Makefile.am b/docs/reference/gtk/Makefile.am index a9bdd747c5..7c643b55a1 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 a2bd08298d..11d14ab2d1 100644 --- a/docs/reference/gtk/gtk-docs.sgml +++ b/docs/reference/gtk/gtk-docs.sgml @@ -355,6 +355,7 @@ + diff --git a/docs/reference/gtk/images/box-expand.png b/docs/reference/gtk/images/box-expand.png new file mode 100644 index 0000000000..e5af4f285a 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 0000000000..1ee108c5fa 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 0000000000..60a6cb3d9b 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 0000000000..5d5a9f99f8 --- /dev/null +++ b/docs/reference/gtk/migrating-GtkGrid.xml @@ -0,0 +1,185 @@ + + + + + Migrating from other containers to GtkGrid + + + #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. + + + + 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. + + +
+ + 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(). + + + + + + 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. + + + + + 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. + +
+ +
+ GtkBox versus GtkGrid: sizing + + + 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. + + + + + + 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. + + + 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. + + + 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. + + + + + + Expansion and alignment + + 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); + + This can be done with #GtkGrid as follows: + + 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); + + + + 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. + + + 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. + + + + 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. + +
+ + +