mirror of
https://gitlab.gnome.org/GNOME/gtk.git
synced 2024-12-27 22:20:24 +00:00
Add an initial migration chapter for GtkGrid
This commit is contained in:
Matthias Clasen
parent
7b6e3be4a7
commit
3ace68ee6f
@ -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 \
|
||||
|
||||
@ -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>
|
||||
|
||||
BIN
docs/reference/gtk/images/box-expand.png
Normal file
BIN
docs/reference/gtk/images/box-expand.png
Normal file
Binary file not shown.
|
After Width: | Height: | Size: 2.3 KiB |
BIN
docs/reference/gtk/images/box-packing.png
Normal file
BIN
docs/reference/gtk/images/box-packing.png
Normal file
Binary file not shown.
|
After Width: | Height: | Size: 3.5 KiB |
BIN
docs/reference/gtk/images/widget-hvalign.png
Normal file
BIN
docs/reference/gtk/images/widget-hvalign.png
Normal file
Binary file not shown.
|
After Width: | Height: | Size: 7.2 KiB |
185
docs/reference/gtk/migrating-GtkGrid.xml
Normal file
185
docs/reference/gtk/migrating-GtkGrid.xml
Normal file
@ -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 — 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>
|
||||
Loading…
Reference in New Issue
Block a user