[gtk+] widget: Add docs for ::measure

[Timm Bäder <baedert src gnome org>]

commit ab467317a10da2f1b2b71b72e506ab1cd18dee81
Author: Timm Bäder <mail baedert org>
Date:   Sat Oct 22 21:40:04 2016 +0200

    widget: Add docs for ::measure

 docs/reference/gtk/gtk4-sections.txt  |    1 +
 docs/reference/gtk/migrating-3to4.xml |   11 +++++++++++
 gtk/gtksizerequest.c                  |   25 +++++++++++++++++++++++++
 gtk/gtkwidget.h                       |   28 ++++------------------------
 4 files changed, 41 insertions(+), 24 deletions(-)
---
diff --git a/docs/reference/gtk/gtk4-sections.txt b/docs/reference/gtk/gtk4-sections.txt
index 7a36a2d..fcd5ebd 100644
--- a/docs/reference/gtk/gtk4-sections.txt
+++ b/docs/reference/gtk/gtk4-sections.txt
@@ -4920,6 +4920,7 @@ gtk_widget_get_opacity
 gtk_widget_set_opacity
 gtk_widget_list_action_prefixes
 gtk_widget_get_action_group
+gtk_widget_measure
 
 <SUBSECTION>
 gtk_widget_get_path
diff --git a/docs/reference/gtk/migrating-3to4.xml b/docs/reference/gtk/migrating-3to4.xml
index d45b688..e8ce306 100644
--- a/docs/reference/gtk/migrating-3to4.xml
+++ b/docs/reference/gtk/migrating-3to4.xml
@@ -130,6 +130,17 @@
       </para>
     </section>
 
+    <section>
+      <title>Adapt to GtkWidget's size request changes</title>
+      <para>
+        GTK+3 used five different virtual functions in GtkWidget to
+        implement size requisition, namely the gtk_widget_get_preferred_width()
+        family of functions. To simplify widget implementations, GTK+4 uses
+        only one virtual function, GtkWidgetClass::measure() that widgets
+        have to implement.
+      </para>
+    </section>
+
   </section>
 
 </chapter>
diff --git a/gtk/gtksizerequest.c b/gtk/gtksizerequest.c
index d80e47f..c030d0c 100644
--- a/gtk/gtksizerequest.c
+++ b/gtk/gtksizerequest.c
@@ -808,6 +808,29 @@ gtk_distribute_natural_allocation (gint              extra_space,
   return extra_space;
 }
 
+/**
+ * gtk_widget_measure:
+ * @widget: A #GtkWidget instance
+ * @orientation: the orientation to measure
+ * @for_size: Size for the opposite of @orientation, i.e.
+ *   if @orientation is %GTK_ORIENTATION_HORIZONTAL, this is
+ *   the height the widget should be measured with. The %GTK_ORIENTATION_VERTICAL
+ *   case is analogous. This way, both height-for-width and width-for-height
+ *   requests can be implemented. If no size is known, -1 can be passed.
+ * @minimum: (out) (optional): location to store the minimum size, or %NULL
+ * @natural: (out) (optional): location to store the natural size, or %NULL
+ * @minimum_baseline: (out) (optional): location to store the baseline
+ *   position for the minimum size, or %NULL
+ * @natural_baseline: (out) (optional): location to store the baseline
+ *   position for the natural size, or %NULL
+ *
+ * Measures @widget in the orientation @orientation and for the given @for_size.
+ * As an example, if @orientation is GTK_ORIENTATION_HORIZONTAL and @for_size is 300,
+ * this functions will compute the minimum and natural width of @widget if
+ * it is allocated at a height of 300 pixels.
+ *
+ * Since: 3.90
+ */
 void
 gtk_widget_measure (GtkWidget      *widget,
                     GtkOrientation  orientation,
@@ -819,6 +842,8 @@ gtk_widget_measure (GtkWidget      *widget,
 {
   g_return_if_fail (GTK_IS_WIDGET (widget));
   g_return_if_fail (for_size >= -1);
+  g_return_if_fail (orientation == GTK_ORIENTATION_HORIZONTAL ||
+                    orientation == GTK_ORIENTATION_VERTICAL);
 
   if (orientation == GTK_ORIENTATION_HORIZONTAL)
     {
diff --git a/gtk/gtkwidget.h b/gtk/gtkwidget.h
index d032582..bb09211 100644
--- a/gtk/gtkwidget.h
+++ b/gtk/gtkwidget.h
@@ -199,30 +199,10 @@ struct _GtkWidget
  *   to both of the virtual methods #GtkWidgetClass.get_preferred_height_for_width()
  *   and #GtkWidgetClass.get_preferred_width_for_height() since it might be 
  *   queried in either #GtkSizeRequestMode by its parent container.
- * @get_preferred_height: This is called by containers to obtain the minimum
- *   and natural height of a widget. A widget that does not actually trade
- *   any height for width or width for height only has to implement these
- *   two virtual methods (#GtkWidgetClass.get_preferred_width() and
- *   #GtkWidgetClass.get_preferred_height()).
- * @get_preferred_width_for_height: This is analogous to
- *   #GtkWidgetClass.get_preferred_height_for_width() except that it
- *   operates in the oposite orientation. It’s rare that a widget actually
- *   does %GTK_SIZE_REQUEST_WIDTH_FOR_HEIGHT requests but this can happen
- *   when, for example, a widget or container gets additional columns to
- *   compensate for a smaller allocated height.
- * @get_preferred_width: This is called by containers to obtain the minimum
- *   and natural width of a widget. A widget will never be allocated a width
- *   less than its minimum and will only ever be allocated a width greater
- *   than the natural width once all of the said widget’s siblings have
- *   received their natural widths.
- *   Furthermore, a widget will only ever be allocated a width greater than
- *   its natural width if it was configured to receive extra expand space
- *   from its parent container.
- * @get_preferred_height_for_width: This is similar to
- *   #GtkWidgetClass.get_preferred_height() except that it is passed a
- *   contextual width to request height for. By implementing this virtual
- *   method it is possible for a #GtkLabel to tell its parent how much height
- *   would be required if the label were to be allocated a said width.
+ * @measure: This is called by containers to obtain the minimum and natural
+ *   size of the widget. Depending on the orientation parameter, the passed
+ *   for_size can be interpreted as width or height. A widget will never be
+ *   allocated less than its minimum size.
  * @mnemonic_activate: Activates the @widget if @group_cycling is
  *   %FALSE, and just grabs the focus if @group_cycling is %TRUE.
  * @grab_focus: Causes @widget to have the keyboard focus for the