[gtk+] Migrated old GtkSizeRequestIface documentation to GtkWidget and added notes to gtk_widget_get_prefer

[Tristan Van Berkom <tvb src gnome org>]

commit 5a7cfa7fb96464bc7d6ed06815d305b01c6cc77d
Author: Tristan Van Berkom <tristan van berkom gmail com>
Date:   Fri Oct 8 23:10:42 2010 +0900

    Migrated old GtkSizeRequestIface documentation to GtkWidget and added notes to gtk_widget_get_preferred_size().

 gtk/gtksizerequest.c |  107 ++++----------------------------------------------
 gtk/gtkwidget.c      |   88 +++++++++++++++++++++++++++++++++++++++++
 2 files changed, 96 insertions(+), 99 deletions(-)
---
diff --git a/gtk/gtksizerequest.c b/gtk/gtksizerequest.c
index f24140b..a30b241 100644
--- a/gtk/gtksizerequest.c
+++ b/gtk/gtksizerequest.c
@@ -21,104 +21,6 @@
  * Boston, MA 02111-1307, USA.
  */
 
-
-/**
- * SECTION:gtksizerequest
- * @Short_Description: Height-for-width geometry management
- * @Title: GtkWidget
- *
- * The GtkWidget interface is GTK+'s 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 #GtkWidget interface for existing widgets,
- * which always requests the same height, regardless of the available width.
- *
- * <refsect2>
- * <title>Implementing GtkWidget</title>
- * <para>
- * Some important things to keep in mind when implementing
- * the GtkWidget interface 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>
- */
-
-
 #include <config.h>
 #include "gtksizerequest.h"
 #include "gtksizegroup.h"
@@ -579,7 +481,14 @@ gtk_widget_get_preferred_height_for_width (GtkWidget *widget,
  * into account the widget's preference for height-for-width management.
  *
  * This is used to retrieve a suitable size by container widgets which do
- * not impose any restrictions on the child placement.
+ * not impose any restrictions on the child placement. It can be used
+ * to deduce toplevel window and menu sizes as well as child widgets in
+ * free form containers such as GtkLayout.
+ *
+ * <note><para>Handle with care, note that the natural height of a height-for-width
+ * widget will generally be a smaller size than the minimum height, since the required
+ * height for the natural width is generally smaller than the required height for
+ * the minimum width.</para></note>
  *
  * Since: 3.0
  */
diff --git a/gtk/gtkwidget.c b/gtk/gtkwidget.c
index 0acf8ea..dc3c1a3 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