X-Git-Url: http://pileus.org/git/?a=blobdiff_plain;f=gtk%2Fgtkwidget.c;h=dc3c1a382867e356d5a08e62fb180822a2f4d202;hb=5a7cfa7fb96464bc7d6ed06815d305b01c6cc77d;hp=0acf8eae4b02c6bb9e18c76d7c5e5cf3c3464fb5;hpb=e9a7a2104be326ca96b49b5a583e1ff89f69f9d6;p=~andy%2Fgtk

diff --git a/gtk/gtkwidget.c b/gtk/gtkwidget.c
index 0acf8eae4..dc3c1a382 100644
--- a/gtk/gtkwidget.c
+++ b/gtk/gtkwidget.c
@@ -68,6 +68,94 @@
  * GtkWidget is the base class all widgets in GTK+ derive from. It manages the
  * widget lifecycle, states and style.
  *
+ * <refsect2>
+ * <title>Height-for-width Geometry Management</title>
+ * <para>
+ * GTK+ uses a height-for-width (and width-for-height) geometry management system. 
+ * Height-for-width means that a widget can change how much vertical space it needs, 
+ * depending on the amount of horizontal space that it is given (and similar for 
+ * width-for-height). The most common example is a label that reflows to fill up the 
+ * available width, wraps to fewer lines, and therefore needs less height.
+ *
+ * GTK+'s traditional two-pass <link linkend="size-allocation">size-allocation</link>
+ * algorithm does not allow this flexibility. #GtkWidget provides a default
+ * implementation of the height-for-width methods for existing widgets,
+ * which always requests the same height, regardless of the available width.
+ *
+ * Some important things to keep in mind when implementing
+ * height-for-width and when using it in container
+ * implementations.
+ *
+ * The geometry management system will query a logical hierarchy in
+ * only one orientation at a time. When widgets are initially queried
+ * for their minimum sizes it is generally done in a dual pass
+ * in the direction chosen by the toplevel.
+ *
+ * For instance when queried in the normal height-for-width mode:
+ * First the default minimum and natural width for each widget
+ * in the interface will computed and collectively returned to
+ * the toplevel by way of gtk_widget_get_preferred_width().
+ * Next, the toplevel will use the minimum width to query for the
+ * minimum height contextual to that width using
+ * gtk_widget_get_preferred_height_for_width(), which will also
+ * be a highly recursive operation. This minimum-for-minimum size can
+ * be used to set the minimum size constraint on the toplevel.
+ *
+ * When allocating, each container can use the minimum and natural
+ * sizes reported by their children to allocate natural sizes and
+ * expose as much content as possible with the given allocation.
+ *
+ * That means that the request operation at allocation time will
+ * usually fire again in contexts of different allocated sizes than
+ * the ones originally queried for. #GtkWidget caches a
+ * small number of results to avoid re-querying for the same
+ * allocated size in one allocation cycle.
+ *
+ * A widget that does not actually do height-for-width
+ * or width-for-height size negotiations only has to implement
+ * get_preferred_width() and get_preferred_height().
+ *
+ * If a widget does move content around to smartly use up the
+ * allocated size, then it must support the request properly in
+ * both orientations; even if the request only makes sense in
+ * one orientation.
+ *
+ * For instance, a GtkLabel that does height-for-width word wrapping
+ * will not expect to have get_preferred_height() called because that
+ * call is specific to a width-for-height request. In this case the
+ * label must return the heights contextual to its minimum possible
+ * width. By following this rule any widget that handles height-for-width
+ * or width-for-height requests will always be allocated at least
+ * enough space to fit its own content.
+ *
+ * Often a widget needs to get its own request during size request or
+ * allocation, for example when computing height it may need to also
+ * compute width, or when deciding how to use an allocation the widget may
+ * need to know its natural size. In these cases, the widget should be
+ * careful to call its virtual methods directly, like this:
+ * <example>
+ *   <title>Widget calling its own size request method.</title>
+ *   <programlisting>
+ * GTK_WIDGET_GET_CLASS(widget)-&gt;get_preferred_width (widget), &min, &natural);
+ *   </programlisting>
+ * </example>
+ *
+ * It will not work to use the wrapper functions, such as
+ * gtk_widget_get_preferred_width(), inside your own size request
+ * implementation. These return a request adjusted by #GtkSizeGroup
+ * and by the GtkWidgetClass::adjust_size_request virtual method. If a
+ * widget used the wrappers inside its virtual method implementations,
+ * then the adjustments (such as widget margins) would be applied
+ * twice. GTK+ therefore does not allow this and will warn if you try
+ * to do it.
+ *
+ * Of course if you are getting the size request for
+ * <emphasis>another</emphasis> widget, such as a child of a
+ * container, you <emphasis>must</emphasis> use the wrapper APIs;
+ * otherwise, you would not properly consider widget margins,
+ * #GtkSizeGroup, and so forth.
+ * </para>
+ * </refsect2>
  * <refsect2 id="style-properties">
  * <para>
  * <structname>GtkWidget</structname> introduces <firstterm>style