More documentation reshuffling

gtk/gtkcssprovider.c

@@ -492,6 +492,33 @@
  * <literallayout>url("gradient1.png") 10 10 10 10 stretch</literallayout></para>
  * </example>
  * </refsect2>
+ * <refsect2 id="gtkcssprovider-transitions">
+ * <para>Styles can specify transitions that will be used to create a gradual
+ * change in the appearance when a widget state changes. The following
+ * syntax is used to specify transitions:
+ * <literallayout>@duration [s|ms] [linear|ease|ease-in|ease-out|ease-in-out] [loop]?</literallayout>
+ * The @duration is the amount of time that the animation will take for
+ * a complete cycle from start to end. If the loop option is given, the
+ * animation will be repated until the state changes again.
+ * The option after the duration determines the transition function from a
+ * small set of predefined functions.
+ * <figure><title>Linear transition</title>
+ * <graphic fileref="linear.png" format="PNG"/>
+ * </figure>
+ * <figure><title>Ease transition</title>
+ * <graphic fileref="ease.png" format="PNG"/>
+ * </figure>
+ * <figure><title>Ease-in-out transition</title>
+ * <graphic fileref="ease-in-out.png" format="PNG"/>
+ * </figure>
+ * <figure><title>Ease-in transition</title>
+ * <graphic fileref="ease-in.png" format="PNG"/>
+ * </figure>
+ * <figure><title>Ease-out transition</title>
+ * <graphic fileref="ease-out.png" format="PNG"/>
+ * </figure>
+ * </para>
+ * </refsect2>
  * <refsect2 id="gtkcssprovider-properties">
  * <title>Supported properties</title>
  * <para>
@@ -612,7 +639,7 @@
  *       </row>
  *       <row>
  *         <entry>transition</entry>
- *         <entry><literallayout>duration [s|ms] [linear|ease|ease-in|ease-out|ease-in-out] [loop]?</literallayout></entry>
+ *         <entry>transition (see above)</entry>
  *         <entry></entry>
  *         <entry><literallayout>transition: 150ms ease-in-out;
  * transition: 1s linear loop;</literallayout>

gtk/gtkstylecontext.c

@@ -66,6 +66,8 @@
  * <title>Transition animations</title>
  * <para>
  * #GtkStyleContext has built-in support for state change transitions.
+ * Note that these animations respect the #GtkSettings:gtk-enable-animations
+ * setting.
  * </para>
  * <para>
  * For simple widgets where state changes affect the whole widget area,
@@ -164,25 +166,7 @@
  * by the animation.
  * </para>
  * <para>
- * Transition animations can use several pre-defined transition functions:
- * <figure><title>Linear transition</title>
- * <graphic fileref="linear.png" format="PNG"/>
- * </figure>
- * <figure><title>Ease transition</title>
- * <graphic fileref="ease.png" format="PNG"/>
- * </figure>
- * <figure><title>Ease-in-out transition</title>
- * <graphic fileref="ease-in-out.png" format="PNG"/>
- * </figure>
- * <figure><title>Ease-in transition</title>
- * <graphic fileref="ease-in.png" format="PNG"/>
- * </figure>
- * <figure><title>Ease-out transition</title>
- * <graphic fileref="ease-out.png" format="PNG"/>
- * </figure>
- * </para>
  * </refsect2>
- *
  * <refsect2 id="gtkstylecontext-custom-styling">
  * <title>Custom styling in UI libraries and applications</title>
  * <para>
@@ -2487,7 +2471,8 @@ gtk_style_context_lookup_color (GtkStyleContext *context,
  * @region_id: (allow-none): animatable region to notify on, or %NULL.
  *             See gtk_style_context_push_animatable_region()
  * @state: state to trigger transition for
- * @state_value: target value of @state
+ * @state_value: %TRUE if @state is the state we are changing to, %FALSE if
+ *   we are changing away from it
  *
  * Notifies a state change on @context, so if the current style makes use
  * of transition animations, one will be started so all rendered elements
@@ -2527,6 +2512,9 @@ gtk_style_context_lookup_color (GtkStyleContext *context,
  * if a pointer enters the button, and back to red if the pointer leaves
  * the button.
  *
+ * Note that @state is used when finding the transition parameters, which
+ * is why the style places the transition under the :hover pseudo-class.
+ *
  * Since: 3.0
  **/
 void