Re: padding cleanup

[Havoc Pennington <hp pobox com>]

Hi,

I merged the main patch to master. I wrote docs (see attached) but did
not push them yet because I can't figure out how to actually document
a non-signal virtual function in a non-interface.
What I have here puts the text of the docs in the HTML but it doesn't
look nice. Does gtk-doc just not do this?

Havoc

From 218ab01aa87e9344f6708ae32d74503014508905 Mon Sep 17 00:00:00 2001
From: Havoc Pennington <hp pobox com>
Date: Sun, 12 Sep 2010 21:43:39 -0400
Subject: [PATCH] Add documentation on adjust_size_request adjust_size_allocation

Also note in the docs for various other functions, whether they
use adjusted or "parent container" size allocation.
---
 gtk/gtksizerequest.c |   59 ++++++++++++++++++++++++++++++++++++++++++++++++++
 gtk/gtkwidget.c      |   28 ++++++++++++++++++++++-
 gtk/gtkwidget.h      |   36 ++++++++++++++++++++++++++++++
 3 files changed, 121 insertions(+), 2 deletions(-)

diff --git a/gtk/gtksizerequest.c b/gtk/gtksizerequest.c
index 543bbc1..8ae2662 100644
--- a/gtk/gtksizerequest.c
+++ b/gtk/gtksizerequest.c
@@ -87,6 +87,34 @@
  * 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_SIZE_REQUEST_GET_IFACE(widget)-&gt;get_width(GTK_SIZE_REQUEST(widget), &min, &natural);
+ * </programlisting>
+ * </example>
+ *
+ * It will not work to use the wrapper functions, such as
+ * gtk_size_request_get_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>
  */
@@ -423,6 +451,12 @@ gtk_size_request_get_request_mode (GtkSizeRequest *widget)
  * <note><para>This call is specific to height-for-width
  * requests.</para></note>
  *
+ * The returned request will be modified by the
+ * GtkWidgetClass::adjust_size_request virtual method and by any
+ * #GtkSizeGroup that have been applied. That is, the returned request
+ * is the one that should be used for layout, not necessarily the one
+ * returned by the widget itself.
+ *
  * Since: 3.0
  */
 void
@@ -445,6 +479,13 @@ gtk_size_request_get_width (GtkSizeRequest *widget,
  *
  * <note><para>This call is specific to width-for-height requests.</para></note>
  *
+ * The returned request will be modified by the
+ * GtkWidgetClass::adjust_size_request virtual method and by any
+ * #GtkSizeGroup that have been applied. That is, the returned request
+ * is the one that should be used for layout, not necessarily the one
+ * returned by the widget itself.
+ *
+ *
  * Since: 3.0
  */
 void
@@ -468,6 +509,12 @@ gtk_size_request_get_height (GtkSizeRequest *widget,
  * Retrieves a widget's minimum and natural width if it would be given
  * the specified @height.
  *
+ * The returned request will be modified by the
+ * GtkWidgetClass::adjust_size_request virtual method and by any
+ * #GtkSizeGroup that have been applied. That is, the returned request
+ * is the one that should be used for layout, not necessarily the one
+ * returned by the widget itself.
+ *
  * Since: 3.0
  */
 void
@@ -490,6 +537,12 @@ gtk_size_request_get_width_for_height (GtkSizeRequest *widget,
  * Retrieves a widget's minimum and natural height if it would be given
  * the specified @width.
  *
+ * The returned request will be modified by the
+ * GtkWidgetClass::adjust_size_request virtual method and by any
+ * #GtkSizeGroup that have been applied. That is, the returned request
+ * is the one that should be used for layout, not necessarily the one
+ * returned by the widget itself.
+ *
  * Since: 3.0
  */
 void
@@ -514,6 +567,12 @@ gtk_size_request_get_height_for_width (GtkSizeRequest *widget,
  * This is used to retrieve a suitable size by container widgets which do
  * not impose any restrictions on the child placement.
  *
+ * The returned request will be modified by the
+ * GtkWidgetClass::adjust_size_request virtual method and by any
+ * #GtkSizeGroup that have been applied. That is, the returned request
+ * is the one that should be used for layout, not necessarily the one
+ * returned by the widget itself.
+ *
  * Since: 3.0
  */
 void
diff --git a/gtk/gtkwidget.c b/gtk/gtkwidget.c
index fa383f3..92e5771 100644
--- a/gtk/gtkwidget.c
+++ b/gtk/gtkwidget.c
@@ -4185,8 +4185,10 @@ gtk_widget_queue_shallow_draw (GtkWidget *widget)
  * and position to their child widgets.
  *
  * In this function, the allocation may be adjusted. It will be forced
- * to a 1x1 minimum size, and the adjust_size_allocation virtual method
- * on the child will be used to adjust the allocation.
+ * to a 1x1 minimum size, and the adjust_size_allocation virtual
+ * method on the child will be used to adjust the allocation. Standard
+ * adjustments include removing the widget's margins, and applying the
+ * widget's GtkWidget:h-align and GtkWidget:v-align properties.
  **/
 void
 gtk_widget_size_allocate (GtkWidget	*widget,
@@ -12106,6 +12108,21 @@ gtk_widget_get_has_tooltip (GtkWidget *widget)
  *
  * Retrieves the widget's allocation.
  *
+ * Note, when implementing a #GtkContainer: a widget's allocation will
+ * be its "adjusted" allocation, that is, the widget's parent
+ * container typically calls gtk_widget_size_allocate() with an
+ * allocation, and that allocation is then adjusted (to handle margin
+ * and alignment for example) before assignment to the widget.
+ * gtk_widget_get_allocation() returns the adjusted allocation that
+ * was actually assigned to the widget. The adjusted allocation is
+ * guaranteed to be completely contained within the
+ * gtk_widget_size_allocate() allocation, however. So a #GtkContainer
+ * is guaranteed that its children stay inside the assigned bounds,
+ * but not that they have exactly the bounds the container assigned.
+ * There is no way to get the original allocation assigned by
+ * gtk_widget_size_allocate(), since it isn't stored; if a container
+ * implementation needs that information it will have to track it itself.
+ *
  * Since: 2.18
  */
 void
@@ -12130,6 +12147,13 @@ gtk_widget_get_allocation (GtkWidget     *widget,
  * Sets the widget's allocation.  This should not be used
  * directly, but from within a widget's size_allocate method.
  *
+ * The allocation set should be the "adjusted" or actual
+ * allocation. If you're implementing a #GtkContainer, you want to use
+ * gtk_widget_size_allocate() instead of gtk_widget_set_allocation().
+ * The GtkWidgetClass::adjust_size_allocation virtual method adjusts the
+ * allocation inside gtk_widget_size_allocate() to create an adjusted
+ * allocation.
+ *
  * Since: 2.18
  */
 void
diff --git a/gtk/gtkwidget.h b/gtk/gtkwidget.h
index 8efdcd6..f717c54 100644
--- a/gtk/gtkwidget.h
+++ b/gtk/gtkwidget.h
@@ -269,6 +269,8 @@ struct _GtkWidget
  * @parent_class:
  * @activate_signal:
  * @set_scroll_adjustments_signal:
+ * @adjust_size_request:
+ * @adjust_size_allocation:
  *
  * <structfield>activate_signal</structfield>
  * The signal to emit when a widget of this class is activated,
@@ -281,6 +283,40 @@ struct _GtkWidget
  * to a scrolling aware parent, gtk_widget_set_scroll_adjustments()
  * handles the emission.
  * Implementation of this signal is optional.
+ *
+ * <structfield>adjust_size_request</structfield>
+ *
+ * Convert an initial size request from a widget's #GtkSizeRequest
+ * virtual method implementations into a size request to be used by
+ * parent containers in laying out the widget.  adjust_size_request
+ * adjusts <emphasis>from</emphasis> a child widget's original request
+ * <emphasis>to</emphasis> what a parent container should use for
+ * layout.  The for_size argument will be -1 if the request should not
+ * be for a particular size in the opposing orientation, i.e. if the
+ * request is not height-for-width or width-for-height. If for_size is
+ * greater than -1, it is the proposed allocation in the opposing
+ * orientation that we need the request for. Implementations of
+ * adjust_size_request should chain up to the default implementation,
+ * which applies #GtkWidget's margin properties and imposes any values
+ * from gtk_widget_set_size_request(). Chaining up should be last,
+ * <emphasis>after</emphasis> your subclass adjusts the request, so
+ * #GtkWidget can apply constraints and add the margin properly.
+ *
+ *
+ * <structfield>adjust_size_allocation</structfield>
+ *
+ * Convert an initial size allocation assigned by a #GtkContainer
+ * using gtk_widget_size_allocate(), into an actual size allocation to
+ * be used by the widget. adjust_size_allocation adjusts
+ * <emphasis>to</emphasis> a child widget's actual allocation
+ * <emphasis>from</emphasis> what a parent container computed for the
+ * child. The adjusted allocation must be entirely within the original
+ * allocation. In any custom implementation, chain up to the default
+ * #GtkWidget implementation of this method, which applies the margin
+ * and alignment properties of #GtkWidget. Chain up
+ * <emphasis>before</emphasis> performing your own adjustments so your
+ * own adjustments remove more allocation after the #GtkWidget base
+ * class has already removed margin and alignment.
  */
 struct _GtkWidgetClass
 {
-- 
1.7.0.4