pygtk-docs r802 - in trunk/2.0: . tut

[esr svn gnome org]

Author: esr
Date: Tue Oct 21 23:09:22 2008
New Revision: 802
URL: http://svn.gnome.org/viewvc/pygtk-docs?rev=802&view=rev

Log:
Significant new content for the Theory of Packing Boxes;
see the Changelog.


Added:
   trunk/2.0/tut/singlewidget.pic
   trunk/2.0/tut/twowidget.pic
Modified:
   trunk/2.0/ChangeLog
   trunk/2.0/Makefile
   trunk/2.0/README
   trunk/2.0/tut/Credits.xml
   trunk/2.0/tut/PackingWidgets.xml

Modified: trunk/2.0/Makefile
==============================================================================
--- trunk/2.0/Makefile	(original)
+++ trunk/2.0/Makefile	Tue Oct 21 23:09:22 2008
@@ -43,6 +43,10 @@
 tut/WidgetOverview.xml \
 tut/ChangeLog.xml
 
+PICSTEMS= \
+singlewidget \
+twowidget
+
 TUTORIALLINKS = \
 pygtk2tutorial/images \
 pygtk2tutorial/examples \
@@ -126,7 +130,7 @@
 
 tut-srcdist:
 	tar zcf pygtk2-tut.docbook.tgz ${TUTORIALXMLFILES} ${XSLFILES} \
-		tut/ChangeLog Makefile examples figures images
+		$(PICFILES) tut/ChangeLog Makefile examples figures images
 
 tut-dist:
 	tar zhcf pygtk2tutorial.tgz pygtk2tutorial
@@ -145,6 +149,7 @@
 pygtk2tutorial/figures:
 	-mkdir pygtk2tutorial/figures
 	-(cd pygtk2tutorial/figures; ln -s ../../figures/* .)
+	for x in $(PICSTEMS); do pic2graph <tut/$$x.pic >pygtk2tutorial/figures/$$x.png; done
 
 tut-es-html: ${ESOUTPUTDIR} ${ESTUTORIALLINKS} ${ESTUTORIALXMLFILES} ${XSLFILES}
 	xsltproc --nonet --xinclude -o ${ESOUTPUTDIR}/ \

Modified: trunk/2.0/README
==============================================================================
--- trunk/2.0/README	(original)
+++ trunk/2.0/README	Tue Oct 21 23:09:22 2008
@@ -12,3 +12,8 @@
 
 The numbering on the in-line displays of the examples is done with nl(1),
 no options.
+
+The environment required to make HTML includes xsltproc, the DocBook 
+stylesheets, and the GNU program pic2graph (part of the groff distribution)
+which is used for making box-and-arrow diagrams.
+ 

Modified: trunk/2.0/tut/Credits.xml
==============================================================================
--- trunk/2.0/tut/Credits.xml	(original)
+++ trunk/2.0/tut/Credits.xml	Tue Oct 21 23:09:22 2008
@@ -129,4 +129,19 @@
 
     <para>Thanks.</para>
   </sect1>
+
+  <sect1 id="sec-PyGTKTutorialCredits">
+    <title>PyGTK Tutorial Credits</title>
+
+     <para>This tutorial was originally adapted from the GTK+
+     documentation by John Finlay.</para>
+
+     <para>Much of <xref
+     linkend="sec-TheoryOfPackingBoxes"/> was adapted from the PyGTK
+     FAQ item 12.2 <citetitle>How does packing work (or how do I get
+     my widget to stay the size I want)</citetitle> as it existed on
+     21 October 2008, And had been originally written by Christian
+     Reis.</para>
+
+  </sect1>
   </chapter>

Modified: trunk/2.0/tut/PackingWidgets.xml
==============================================================================
--- trunk/2.0/tut/PackingWidgets.xml	(original)
+++ trunk/2.0/tut/PackingWidgets.xml	Tue Oct 21 23:09:22 2008
@@ -40,12 +40,81 @@
 themselves, including the button, but we usually only use a label inside a
 button.</para>
 
-    <para>By using these calls, GTK knows where you want to place your
-widgets so it can do automatic resizing and other nifty things. There are
-also a number of options as to how your widgets should be packed. As you can
-imagine, this method gives us a quite a bit of flexibility when placing and
-creating widgets.</para>
+<para>You may find when working with containers that the size (and
+aspect ratio) of your widget isn't quite what you would expect. That's
+an intentional consequence of the GTK+ box model.  The size of any
+given widget is determined both by by how it packs among the widgets
+around it and whether or not its container offers it the possibility
+to expand and fill space available to it.</para>
 
+<para>if you have a container a single child, this child will take up
+all its space minus its border:</para>
+
+      <figure id="singlewidget">
+	<title>Packing: A Single Widget in a Container</title>
+	<mediaobject>
+	  <imageobject>
+	    <imagedata fileref="figures/singlewidget.png" format="png" align="center"/>
+	  </imageobject>
+	</mediaobject>
+      </figure>
+
+<para>If you have a container (say a VBox or HBox) with two (or
+more) children, they will fight<footnote><para>A cute analogy; in reality
+fill, expansion, requested sizes, widget expansion semantics,
+container packing semantics, electron spins and lunar cycles are
+computed to determine how much space each widget wins.</para></footnote> to
+determine who takes up more space:</para>
+
+      <figure id="twowidget">
+	<title>Packing: Two Widgets in a Container</title>
+	<mediaobject>
+	  <imageobject>
+	    <imagedata fileref="figures/twowidget.png" format="png" align="center"/>
+	  </imageobject>
+	</mediaobject>
+      </figure>
+
+<para>How much each one actually gets is determined by:</para>
+
+<itemizedlist>
+<listitem><para>the default and requested sizes of the widgets, which
+normally depends on their contents (for labels, in
+particular).</para></listitem>
+
+<listitem><para>the expand and fill arguments supplied to
+<methodname>add()</methodname> or
+<methodname>pack_start</methodname>/<methodname>pack_end()</methodname>,
+all three of which we will describe in more detail later in this
+chapter:</para>
+
+<itemizedlist>
+<listitem><para>
+<parameter>expand</parameter>=<constant>True</constant> means "I will
+fight for space"
+</para></listitem>
+<listitem><para>
+<parameter>expand</parameter>=<constant>False</constant> means "I don't want more space"</para></listitem>
+<listitem><para>
+<parameter>fill</parameter>=<constant>True</constant> means "If I got
+more space, I will occupy it with my content"
+</para></listitem>
+<listitem><para>
+<parameter>fill</parameter>=<constant>False</constant> means "If I got
+more space, leave it blank"
+</para></listitem>
+</itemizedlist>
+</listitem>
+</itemizedlist>
+
+<para>This is important to understand when assembling your interfaces,
+and is the most peculiar thing about GTK+ programming to a newbie;
+although the packing-based widget geometry is more complex to
+understand initially than fixed-width layouts, it is superior
+because GTK+ windows actually resize properly.</para>
+
+<para>To get an intuitive grasp of the box model, spend some time
+experimenting with the "packing" tab in Glade.</para>
     </sect1>
 
 <!-- ===================================================================== -->

Added: trunk/2.0/tut/singlewidget.pic
==============================================================================
--- (empty file)
+++ trunk/2.0/tut/singlewidget.pic	Tue Oct 21 23:09:22 2008
@@ -0,0 +1,13 @@
+# This is an image description in pic.
+# To render it into something useful for the Web, 
+# use the GNU program pic2graph
+
+.ps 16
+OUTER: box ht 1.0 wid 3.0
+INNER: box ht 0.75 wid 2.75 with .c at OUTER.c
+BARROW: arrow down left with .end at OUTER.ne + (-0.75,-0.07)
+OARROW: arrow down right with .end at OUTER.nw + (0.75,0)
+"Border" with .s at BARROW.start + (0, 0.1)
+"Inner Widget" ljust at INNER.w + (0.1, 0)
+"Outer Widget" with .s at OARROW.start + (0, 0.1)
+

Added: trunk/2.0/tut/twowidget.pic
==============================================================================
--- (empty file)
+++ trunk/2.0/tut/twowidget.pic	Tue Oct 21 23:09:22 2008
@@ -0,0 +1,15 @@
+# This is an image description in pic.
+# To render it into something useful for the Web, 
+# use the GNU program pic2graph
+
+.ps 16
+OUTER: box ht 1.0 wid 6.0
+CHILD1: box ht 0.75 wid 2.15 with .nw at OUTER.nw + (0.125, -0.125)
+CHILD2: box ht 0.75 wid 3.475 with .w at CHILD1.e + (0.125, -0)
+BARROW: arrow down left with .end at OUTER.ne + (-0.75,-0.07)
+OARROW: arrow down right with .end at OUTER.nw + (0.75,0)
+"Border" with .s at BARROW.start + (0, 0.1)
+"Child 1, expand=False" at CHILD1.c
+"Child 2, expand=True" at CHILD2.c
+"Outer Widget" with .s at OARROW.start + (0, 0.1)
+