scrollable: Clarify when to set adjustment props

Instead of populating the properties right away (when the widget might
not have been allocated yet, and hence cannot know the right values),
the widget should queue an allocation, where it will populate the
values.

diff --git a/gtk/gtkscrollable.c b/gtk/gtkscrollable.c
index 041f09ac04eade410cf958412806114ce77f4549..4df0c170f61c09c7ea105f2f4af0f25054670c68 100644 (file)
--- a/gtk/gtkscrollable.c
+++ b/gtk/gtkscrollable.c
@@ -29,13 +29,11 @@
  * All scrollable widgets should do the following.
  *
  * - When a parent widget sets the scrollable child widget’s adjustments,
- *   the widget should populate the adjustments’
- *   [property@Gtk.Adjustment:lower],
- *   [property@Gtk.Adjustment:upper],
- *   [property@Gtk.Adjustment:step-increment],
- *   [property@Gtk.Adjustment:page-increment] and
- *   [property@Gtk.Adjustment:page-size] properties and connect to the
- *   [signal@Gtk.Adjustment::value-changed] signal.
+ *   the widget should connect to the [signal@Gtk.Adjustment::value-changed]
+ *   signal. The child widget should then populate the adjustments’ properties
+ *   as soon as possible, which usually means queueing an allocation right away
+ *   and populating the properties in the [vfunc@Gtk.Widget.size_allocate]
+ *   implementation.
  *
  * - Because its preferred size is the size for a fully expanded widget,
  *   the scrollable widget must be able to cope with underallocations.
@@ -43,7 +41,8 @@
  *   [vfunc@Gtk.Widget.size_allocate] implementation.
  *
  * - When the parent allocates space to the scrollable child widget,
- *   the widget should update the adjustments’ properties with new values.
+ *   the widget must ensure the adjustments’ property values are correct and up
+ *   to date, for example using [method@Gtk.Adjustment.configure].
  *
  * - When any of the adjustments emits the [signal@Gtk.Adjustment::value-changed]
  *   signal, the scrollable widget should scroll its contents.