[clutter/clutter-1.18] docs: Move to markdown
- From: Emmanuele Bassi <ebassi src gnome org>
- To: commits-list gnome org
- Cc:
- Subject: [clutter/clutter-1.18] docs: Move to markdown
- Date: Tue, 18 Mar 2014 14:27:57 +0000 (UTC)
commit 12370bd4f8246f72abe75fae90fdee452c7a8f58
Author: Emmanuele Bassi <ebassi gnome org>
Date: Mon Mar 17 23:07:58 2014 +0000
docs: Move to markdown
We're removing docbook tags in favour of the markdown syntax.
clutter/clutter-actor.c | 904 ++++++++++++++++++------------------
clutter/clutter-backend.c | 8 +-
clutter/clutter-bin-layout.c | 34 +-
clutter/clutter-bind-constraint.c | 31 +-
clutter/clutter-binding-pool.c | 19 +-
clutter/clutter-box-layout.c | 32 +-
clutter/clutter-canvas.c | 9 +-
clutter/clutter-child-meta.h | 9 +-
clutter/clutter-clone.c | 6 +-
clutter/clutter-color.c | 28 +-
clutter/clutter-constraint.c | 207 ++++-----
clutter/clutter-deform-effect.c | 19 +-
clutter/clutter-drag-action.c | 20 +-
clutter/clutter-drop-action.c | 14 +-
clutter/clutter-effect.c | 158 +++----
clutter/clutter-flow-layout.c | 35 +-
clutter/clutter-gesture-action.c | 64 ++--
clutter/clutter-image.c | 9 +-
clutter/clutter-input-device.c | 20 +-
clutter/clutter-layout-manager.c | 285 ++----------
clutter/clutter-main.c | 140 ++----
clutter/clutter-model.c | 70 ++--
clutter/clutter-offscreen-effect.c | 41 +-
clutter/clutter-paint-volume.c | 64 ++--
clutter/clutter-path.c | 67 +--
clutter/clutter-script.c | 10 +-
clutter/clutter-scroll-actor.c | 9 +-
clutter/clutter-settings.c | 24 +-
clutter/clutter-shader-effect.c | 100 ++--
clutter/clutter-stage.c | 50 +-
clutter/clutter-test-utils.c | 2 +-
clutter/clutter-test-utils.h | 2 +-
clutter/clutter-text.c | 4 +-
clutter/clutter-timeline.c | 47 +-
clutter/clutter-types.h | 4 +-
clutter/clutter-units.c | 6 +-
36 files changed, 1061 insertions(+), 1490 deletions(-)
---
diff --git a/clutter/clutter-actor.c b/clutter/clutter-actor.c
index 2274c3e..fad7b0e 100644
--- a/clutter/clutter-actor.c
+++ b/clutter/clutter-actor.c
@@ -30,131 +30,121 @@
* and it encapsulates the position, size, and transformations of a node in
* the graph.
*
- * <refsect2 id="ClutterActor-transformations">
- * <title>Actor transformations</title>
- * <para>Each actor can be transformed using methods like
- * clutter_actor_set_scale() or clutter_actor_set_rotation(). The order
- * in which the transformations are applied is decided by Clutter and it is
- * the following:</para>
- * <orderedlist>
- * <listitem><para>translation by the origin of the #ClutterActor:allocation;</para></listitem>
- * <listitem><para>translation by the actor's #ClutterActor:depth;</para></listitem>
- * <listitem><para>scaling by the #ClutterActor:scale-x and #ClutterActor:scale-y
factors;</para></listitem>
- * <listitem><para>rotation around the #ClutterActor:rotation-angle-x and
#ClutterActor:rotation-center-x;</para></listitem>
- * <listitem><para>rotation around the #ClutterActor:rotation-angle-y and
#ClutterActor:rotation-center-y;</para></listitem>
- * <listitem><para>rotation around the #ClutterActor:rotation-angle-z and
#ClutterActor:rotation-center-z;</para></listitem>
- * <listitem><para>negative translation by the #ClutterActor:anchor-x and #ClutterActor:anchor-y
point.</para></listitem>
- * </orderedlist>
- * </refsect2>
- *
- * <refsect2 id="ClutterActor-geometry">
- * <title>Modifying an actor's geometry</title>
- * <para>Each actor has a bounding box, called #ClutterActor:allocation
- * which is either set by its parent or explicitly through the
- * clutter_actor_set_position() and clutter_actor_set_size() methods.
- * Each actor also has an implicit preferred size.</para>
- * <para>An actor’s preferred size can be defined by any subclass by
- * overriding the #ClutterActorClass.get_preferred_width() and the
- * #ClutterActorClass.get_preferred_height() virtual functions, or it can
- * be explicitly set by using clutter_actor_set_width() and
- * clutter_actor_set_height().</para>
- * <para>An actor’s position can be set explicitly by using
- * clutter_actor_set_x() and clutter_actor_set_y(); the coordinates are
- * relative to the origin of the actor’s parent.</para>
- * </refsect2>
- *
- * <refsect2 id="ClutterActor-children">
- * <title>Managing actor children</title>
- * <para>Each actor can have multiple children, by calling
- * clutter_actor_add_child() to add a new child actor, and
- * clutter_actor_remove_child() to remove an existing child. #ClutterActor
- * will hold a reference on each child actor, which will be released when
- * the child is removed from its parent, or destroyed using
- * clutter_actor_destroy().</para>
- * <informalexample><programlisting>
+ * ## Actor transformations
+ *
+ * Each actor can be transformed using methods like clutter_actor_set_scale()
+ * or clutter_actor_set_rotation(). The order in which the transformations are
+ * applied is decided by Clutter and it is the following:
+ *
+ * 1. translation by the origin of the #ClutterActor:allocation property
+ * 2. translation by the actor's #ClutterActor:z-position property
+ * 3. translation by the actor's #ClutterActor:pivot-point property
+ * 4. scaling by the #ClutterActor:scale-x and #ClutterActor:scale-y factors
+ * 5. rotation around the #ClutterActor:rotation-angle-x and #ClutterActor:rotation-center-x
+ * 6. rotation around the #ClutterActor:rotation-angle-y and #ClutterActor:rotation-center-y
+ * 7. rotation around the #ClutterActor:rotation-angle-z and #ClutterActor:rotation-center-z
+ * 8. negative translation by the #ClutterActor:anchor-x and #ClutterActor:anchor-y point.
+ * 9. negative translation by the actor's #ClutterActor:pivot-point
+ *
+ * ## Modifying an actor's geometry
+ *
+ * Each actor has a bounding box, called #ClutterActor:allocation
+ * which is either set by its parent or explicitly through the
+ * clutter_actor_set_position() and clutter_actor_set_size() methods.
+ * Each actor also has an implicit preferred size.
+ *
+ * An actor’s preferred size can be defined by any subclass by
+ * overriding the #ClutterActorClass.get_preferred_width() and the
+ * #ClutterActorClass.get_preferred_height() virtual functions, or it can
+ * be explicitly set by using clutter_actor_set_width() and
+ * clutter_actor_set_height().
+ *
+ * An actor’s position can be set explicitly by using
+ * clutter_actor_set_x() and clutter_actor_set_y(); the coordinates are
+ * relative to the origin of the actor’s parent.
+ *
+ * ## Managing actor children
+ *
+ * Each actor can have multiple children, by calling
+ * clutter_actor_add_child() to add a new child actor, and
+ * clutter_actor_remove_child() to remove an existing child. #ClutterActor
+ * will hold a reference on each child actor, which will be released when
+ * the child is removed from its parent, or destroyed using
+ * clutter_actor_destroy().
+ *
+ * |[<!-- language="C" -->
* ClutterActor *actor = clutter_actor_new ();
*
- * /* set the bounding box of the actor */
+ * // set the bounding box of the actor
* clutter_actor_set_position (actor, 0, 0);
* clutter_actor_set_size (actor, 480, 640);
*
- * /* set the background color of the actor */
+ * // set the background color of the actor
* clutter_actor_set_background_color (actor, CLUTTER_COLOR_Orange);
*
- * /* set the bounding box of the child, relative to the parent */
+ * // set the bounding box of the child, relative to the parent
* ClutterActor *child = clutter_actor_new ();
* clutter_actor_set_position (child, 20, 20);
* clutter_actor_set_size (child, 80, 240);
*
- * /* set the background color of the child */
+ * // set the background color of the child
* clutter_actor_set_background_color (child, CLUTTER_COLOR_Blue);
*
- * /* add the child to the actor */
+ * // add the child to the actor
* clutter_actor_add_child (actor, child);
- * </programlisting></informalexample>
- * <para>Children can be inserted at a given index, or above and below
- * another child actor. The order of insertion determines the order of the
- * children when iterating over them. Iterating over children is performed
- * by using clutter_actor_get_first_child(), clutter_actor_get_previous_sibling(),
- * clutter_actor_get_next_sibling(), and clutter_actor_get_last_child(). It is
- * also possible to retrieve a list of children by using
- * clutter_actor_get_children(), as well as retrieving a specific child at a
- * given index by using clutter_actor_get_child_at_index().</para>
- * <para>If you need to track additions of children to a #ClutterActor, use
- * the #ClutterContainer::actor-added signal; similarly, to track removals
- * of children from a ClutterActor, use the #ClutterContainer::actor-removed
- * signal.</para>
- * <informalexample><programlisting>
- * <xi:include xmlns:xi="http://www.w3.org/2001/XInclude"; parse="text"
href="../../../../examples/basic-actor.c">
- * <xi:fallback>FIXME: MISSING XINCLUDE CONTENT</xi:fallback>
- * </xi:include>
- * </programlisting></informalexample>
- * <figure id="actor-example-image">
- * <title>Actors</title>
- * <graphic fileref="actor-example.png" format="PNG"/>
- * </figure>
- * </refsect2>
- *
- * <refsect2 id="ClutterActor-painting">
- * <title>Painting an actor</title>
- * <para>There are three ways to paint an actor:</para>
- * <itemizedlist>
- * <listitem><para>set a delegate #ClutterContent as the value for the
- * #ClutterActor:content property of the actor;</para></listitem>
- * <listitem><para>subclass #ClutterActor and override the
- * #ClutterActorClass.paint_node() virtual function;</para></listitem>
- * <listitem><para>subclass #ClutterActor and override the
- * #ClutterActorClass.paint() virtual function.</para></listitem>
- * </itemizedlist>
- * <formalpara>
- * <title>Setting the Content property</title>
- * <para>A #ClutterContent is a delegate object that takes over the
- * painting operation of one, or more actors. The #ClutterContent
- * painting will be performed on top of the #ClutterActor:background-color
- * of the actor, and before calling the #ClutterActorClass.paint_node()
- * virtual function.</para>
- * <informalexample><programlisting>
+ * ]|
+ *
+ * Children can be inserted at a given index, or above and below
+ * another child actor. The order of insertion determines the order of the
+ * children when iterating over them. Iterating over children is performed
+ * by using clutter_actor_get_first_child(), clutter_actor_get_previous_sibling(),
+ * clutter_actor_get_next_sibling(), and clutter_actor_get_last_child(). It is
+ * also possible to retrieve a list of children by using
+ * clutter_actor_get_children(), as well as retrieving a specific child at a
+ * given index by using clutter_actor_get_child_at_index().
+ *
+ * If you need to track additions of children to a #ClutterActor, use
+ * the #ClutterContainer::actor-added signal; similarly, to track removals
+ * of children from a ClutterActor, use the #ClutterContainer::actor-removed
+ * signal.
+ *
+ * See [basic-actor.c](https://git.gnome.org/browse/clutter/tree/examples/basic-actor.c?h=clutter-1.18).
+ *
+ * ## Painting an actor
+ *
+ * There are three ways to paint an actor:
+ *
+ * - set a delegate #ClutterContent as the value for the #ClutterActor:content property of the actor
+ * - subclass #ClutterActor and override the #ClutterActorClass.paint_node() virtual function
+ * - subclass #ClutterActor and override the #ClutterActorClass.paint() virtual function.
+ *
+ * A #ClutterContent is a delegate object that takes over the painting
+ * operations of one, or more actors. The #ClutterContent painting will
+ * be performed on top of the #ClutterActor:background-color of the actor,
+ * and before calling the actor's own implementation of the
+ * #ClutterActorClass.paint_node() virtual function.
+ *
+ * |[<!-- language="C" -->
* ClutterActor *actor = clutter_actor_new ();
*
- * /* set the bounding box */
+ * // set the bounding box
* clutter_actor_set_position (actor, 50, 50);
* clutter_actor_set_size (actor, 100, 100);
*
- * /* set the content; the image_content variable is set elsewhere */
+ * // set the content; the image_content variable is set elsewhere
* clutter_actor_set_content (actor, image_content);
- * </programlisting></informalexample>
- * </formalpara>
- * <formalpara>
- * <title>Overriding the paint_node virtual function</title>
- * <para>The #ClutterActorClass.paint_node() virtual function is invoked
- * whenever an actor needs to be painted. The implementation of the
- * virtual function must only paint the contents of the actor itself,
- * and not the contents of its children, if the actor has any.</para>
- * <para>The #ClutterPaintNode passed to the virtual function is the
- * local root of the render tree; any node added to it will be
- * rendered at the correct position, as defined by the actor's
- * #ClutterActor:allocation.</para>
- * <informalexample><programlisting>
+ * ]|
+ *
+ * The #ClutterActorClass.paint_node() virtual function is invoked whenever
+ * an actor needs to be painted. The implementation of the virtual function
+ * must only paint the contents of the actor itself, and not the contents of
+ * its children, if the actor has any.
+ *
+ * The #ClutterPaintNode passed to the virtual function is the local root of
+ * the render tree; any node added to it will be rendered at the correct
+ * position, as defined by the actor's #ClutterActor:allocation.
+ *
+ * |[<!-- language="C" -->
* static void
* my_actor_paint_node (ClutterActor *actor,
* ClutterPaintNode *root)
@@ -162,112 +152,131 @@
* ClutterPaintNode *node;
* ClutterActorBox box;
*
- * /* where the content of the actor should be painted */
+ * // where the content of the actor should be painted
* clutter_actor_get_allocation_box (actor, &box);
*
- * /* the cogl_texture variable is set elsewhere */
+ * // the cogl_texture variable is set elsewhere
* node = clutter_texture_node_new (cogl_texture, CLUTTER_COLOR_White,
* CLUTTER_SCALING_FILTER_TRILINEAR,
* CLUTTER_SCALING_FILTER_LINEAR);
*
- * /* paint the content of the node using the allocation */
+ * // paint the content of the node using the allocation
* clutter_paint_node_add_rectangle (node, &box);
*
- * /* add the node, and transfer ownership */
+ * // add the node, and transfer ownership
* clutter_paint_node_add_child (root, node);
* clutter_paint_node_unref (node);
* }
- * </programlisting></informalexample>
- * </formalpara>
- * <formalpara>
- * <title>Overriding the paint virtual function</title>
- * <para>The #ClutterActorClass.paint() virtual function is invoked
- * when the #ClutterActor::paint signal is emitted, and after the other
- * signal handlers have been invoked. Overriding the paint virtual
- * function gives total control to the paint sequence of the actor
- * itself, including the children of the actor, if any.</para>
- * <warning><para>It is strongly discouraged to override the
- * #ClutterActorClass.paint() virtual function, as well as connecting
- * to the #ClutterActor::paint signal. These hooks into the paint
- * sequence are considered legacy, and will be removed when the Clutter
- * API changes.</para></warning>
- * </formalpara>
- * </refsect2>
- *
- * <refsect2 id="ClutterActor-events">
- * <title>Handling events on an actor</title>
- * <para>A #ClutterActor can receive and handle input device events, for
- * instance pointer events and key events, as long as its
- * #ClutterActor:reactive property is set to %TRUE.</para>
- * <para>Once an actor has been determined to be the source of an event,
- * Clutter will traverse the scene graph from the top-level actor towards the
- * event source, emitting the #ClutterActor::captured-event signal on each
- * ancestor until it reaches the source; this phase is also called
- * <emphasis>the capture phase</emphasis>. If the event propagation was not
- * stopped, the graph is walked backwards, from the source actor to the
- * top-level, and the #ClutterActor::event signal, along with other event
- * signals if needed, is emitted; this phase is also called <emphasis>the
- * bubble phase</emphasis>. At any point of the signal emission, signal
- * handlers can stop the propagation through the scene graph by returning
- * %CLUTTER_EVENT_STOP; otherwise, they can continue the propagation by
- * returning %CLUTTER_EVENT_PROPAGATE.</para>
- * </refsect2>
- *
- * <refsect2 id="ClutterActor-animation">
- * <title>Animation</title>
- * <para>Animation is a core concept of modern user interfaces; Clutter
- * provides a complete and powerful animation framework that automatically
- * tweens the actor's state without requiring direct, frame by frame
- * manipulation from your application code.</para>
- * <formalpara>
- * <title>Implicit animations</title>
- * <para>The implicit animation model of Clutter assumes that all the
- * changes in an actor state should be gradual and asynchronous; Clutter
- * will automatically transition an actor's property change between the
- * current state and the desired one without manual intervention, if the
- * property is defined to be animatable in its documentation.</para>
- * <note><para>By default, in the 1.0 API series, the transition happens
- * with a duration of zero milliseconds, and the implicit animation is an
- * opt in feature to retain backwards compatibility.</para></note>
- * <para>Implicit animations depend on the current easing state; in order
- * to use the default easing state for an actor you should call the
- * clutter_actor_save_easing_state() function:</para>
- * <informalexample><programlisting>
- * /* assume that the actor is currently positioned at (100, 100) */
+ *
+ * The #ClutterActorClass.paint() virtual function is invoked when the
+ * #ClutterActor::paint signal is emitted, and after the other signal
+ * handlers have been invoked. Overriding the paint virtual function
+ * gives total control to the paint sequence of the actor itself,
+ * including the children of the actor, if any.
+ *
+ * It is strongly discouraged to override the #ClutterActorClass.paint()
+ * virtual function, as well as connecting to the #ClutterActor::paint
+ * signal. These hooks into the paint sequence are considered legacy, and
+ * will be removed when the Clutter API changes.
+ *
+ * ## Handling events on an actor
+ *
+ * A #ClutterActor can receive and handle input device events, for
+ * instance pointer events and key events, as long as its
+ * #ClutterActor:reactive property is set to %TRUE.
+ *
+ * Once an actor has been determined to be the source of an event,
+ * Clutter will traverse the scene graph from the top-level actor towards the
+ * event source, emitting the #ClutterActor::captured-event signal on each
+ * ancestor until it reaches the source; this phase is also called
+ * the "capture" phase. If the event propagation was not stopped, the graph
+ * is walked backwards, from the source actor to the top-level, and the
+ * #ClutterActor::event signal is emitted, alongside eventual event-specific
+ * signals like #ClutterActor::button-press-event or #ClutterActor::motion-event;
+ * this phase is also called the "bubble" phase.
+ *
+ * At any point of the signal emission, signal handlers can stop the propagation
+ * through the scene graph by returning %CLUTTER_EVENT_STOP; otherwise, they can
+ * continue the propagation by returning %CLUTTER_EVENT_PROPAGATE.
+ *
+ * ## Animation
+ *
+ * Animation is a core concept of modern user interfaces; Clutter provides a
+ * complete and powerful animation framework that automatically tweens the
+ * actor's state without requiring direct, frame by frame manipulation from
+ * your application code. You have two models at your disposal:
+ *
+ * - an implicit animation model
+ * - an explicit animation model
+ *
+ * The implicit animation model of Clutter assumes that all the
+ * changes in an actor state should be gradual and asynchronous; Clutter
+ * will automatically transition an actor's property change between the
+ * current state and the desired one without manual intervention, if the
+ * property is defined to be animatable in its documentation.
+ *
+ * By default, in the 1.0 API series, the transition happens with a duration
+ * of zero milliseconds, and the implicit animation is an opt in feature to
+ * retain backwards compatibility.
+ *
+ * Implicit animations depend on the current easing state; in order to use
+ * the default easing state for an actor you should call the
+ * clutter_actor_save_easing_state() function:
+ *
+ * |[<!-- language="C" -->
+ * // assume that the actor is currently positioned at (100, 100)
+ *
+ * // store the current easing state and reset the new easing state to
+ * // its default values
* clutter_actor_save_easing_state (actor);
+ *
+ * // change the actor's position
* clutter_actor_set_position (actor, 500, 500);
+ *
+ * // restore the previously saved easing state
* clutter_actor_restore_easing_state (actor);
- * </programlisting></informalexample>
- * <para>The example above will trigger an implicit animation of the
- * actor between its current position to a new position.</para>
- * <para>It is possible to animate multiple properties of an actor
- * at the same time, and you can animate multiple actors at the same
- * time as well, for instance:</para>
- * <informalexample><programlisting>
- * /* animate the actor's opacity and depth */
+ * ]|
+ *
+ * The example above will trigger an implicit animation of the
+ * actor between its current position to a new position.
+ *
+ * Implicit animations use a default duration of 250 milliseconds,
+ * and a default easing mode of %CLUTTER_EASE_OUT_CUBIC, unless you call
+ * clutter_actor_set_easing_mode() and clutter_actor_set_easing_duration()
+ * after changing the easing state of the actor.
+ *
+ * It is possible to animate multiple properties of an actor
+ * at the same time, and you can animate multiple actors at the same
+ * time as well, for instance:
+ *
+ * |[<!-- language="C" -->
* clutter_actor_save_easing_state (actor);
+ *
+ * // animate the actor's opacity and depth
* clutter_actor_set_opacity (actor, 0);
* clutter_actor_set_depth (actor, -100);
+ *
* clutter_actor_restore_easing_state (actor);
*
- * /* animate another actor's opacity */
* clutter_actor_save_easing_state (another_actor);
+ *
+ * // animate another actor's opacity
* clutter_actor_set_opacity (another_actor, 255);
* clutter_actor_set_depth (another_actor, 100);
+ *
* clutter_actor_restore_easing_state (another_actor);
- * </programlisting></informalexample>
- * <para>Implicit animations use a default duration of 250 milliseconds,
- * and a default easing mode of %CLUTTER_EASE_OUT_CUBIC, unless you call
- * clutter_actor_set_easing_mode() and clutter_actor_set_easing_duration()
- * after changing the easing state of the actor.</para>
- * <para>Changing the easing state will affect all the following property
- * transitions, but will not affect existing transitions.</para>
- * <para>It is important to note that if you modify the state on an
- * animatable property while a transition is in flight, the transition's
- * final value will be updated, as well as its duration and progress
- * mode by using the current easing state; for instance, in the following
- * example:</para>
- * <informalexample><programlisting>
+ * ]|
+ *
+ * Changing the easing state will affect all the following property
+ * transitions, but will not affect existing transitions.
+ *
+ * It is important to note that if you modify the state on an
+ * animatable property while a transition is in flight, the transition's
+ * final value will be updated, as well as its duration and progress
+ * mode by using the current easing state; for instance, in the following
+ * example:
+ *
+ * |[<!-- language="C" -->
* clutter_actor_save_easing_state (actor);
* clutter_actor_set_easing_duration (actor, 1000);
* clutter_actor_set_x (actor, 200);
@@ -277,23 +286,30 @@
* clutter_actor_set_easing_duration (actor, 500);
* clutter_actor_set_x (actor, 100);
* clutter_actor_restore_easing_state (actor);
- * </programlisting></informalexample>
- * <para>the first call to clutter_actor_set_x() will begin a transition
- * of the #ClutterActor:x property from the current value to the value of
- * 200 over a duration of one second; the second call to clutter_actor_set_x()
- * will change the transition's final value to 100 and the duration to 500
- * milliseconds.</para>
- * <para>It is possible to retrieve the #ClutterTransition used by the
- * animatable properties by using clutter_actor_get_transition() and using
- * the property name as the transition name.</para>
- * </formalpara>
- * <formalpara>
- * <title>Explicit animations</title>
- * <para>The explicit animation model supported by Clutter requires that
- * you create a #ClutterTransition object, and set the initial and
- * final values. The transition will not start unless you add it to the
- * #ClutterActor.</para>
- * <informalexample><programlisting>
+ * ]|
+ *
+ * the first call to clutter_actor_set_x() will begin a transition
+ * of the #ClutterActor:x property from the current value to the value of
+ * 200 over a duration of one second; the second call to clutter_actor_set_x()
+ * will change the transition's final value to 100 and the duration to 500
+ * milliseconds.
+ *
+ * It is possible to receive a notification of the completion of an
+ * implicit transition by using the #ClutterActor::transition-stopped
+ * signal, decorated with the name of the property. In case you want to
+ * know when all the currently in flight transitions are complete, use
+ * the #ClutterActor::transitions-completed signal instead.
+ *
+ * It is possible to retrieve the #ClutterTransition used by the
+ * animatable properties by using clutter_actor_get_transition() and using
+ * the property name as the transition name.
+ *
+ * The explicit animation model supported by Clutter requires that
+ * you create a #ClutterTransition object, and optionally set the initial
+ * and final values. The transition will not start unless you add it to the
+ * #ClutterActor.
+ *
+ * |[<!-- language="C" -->
* ClutterTransition *transition;
*
* transition = clutter_property_transition_new ("opacity");
@@ -304,144 +320,144 @@
* clutter_transition_set_to (transition, G_TYPE_UINT, 0);
*
* clutter_actor_add_transition (actor, "animate-opacity", transition);
- * </programlisting></informalexample>
- * <para>The example above will animate the #ClutterActor:opacity property
- * of an actor between fully opaque and fully transparent, and back, over
- * a span of 3 seconds. The animation does not begin until it is added to
- * the actor.</para>
- * <para>The explicit animation API applies to all #GObject properties,
- * as well as the custom properties defined through the #ClutterAnimatable
- * interface, regardless of whether they are defined as implicitly
- * animatable or not.</para>
- * <para>The explicit animation API should also be used when using custom
- * animatable properties for #ClutterAction, #ClutterConstraint, and
- * #ClutterEffect instances associated to an actor; see the section on
- * <ulink linkend="ClutterActor-custom-animatable-properties">custom
- * animatable properties below</ulink> for an example.</para>
- * <para>Finally, explicit animations are useful for creating animations
- * that run continuously, for instance:</para>
- * <informalexample><programlisting>
- * /* this animation will pulse the actor's opacity continuously */
+ * ]|
+ *
+ * The example above will animate the #ClutterActor:opacity property
+ * of an actor between fully opaque and fully transparent, and back, over
+ * a span of 3 seconds. The animation does not begin until it is added to
+ * the actor.
+ *
+ * The explicit animation API applies to all #GObject properties,
+ * as well as the custom properties defined through the #ClutterAnimatable
+ * interface, regardless of whether they are defined as implicitly
+ * animatable or not.
+ *
+ * The explicit animation API should also be used when using custom
+ * animatable properties for #ClutterAction, #ClutterConstraint, and
+ * #ClutterEffect instances associated to an actor; see the section on
+ * custom animatable properties below for an example.
+ *
+ * Finally, explicit animations are useful for creating animations
+ * that run continuously, for instance:
+ *
+ * |[<!-- language="C" -->
+ * // this animation will pulse the actor's opacity continuously
* ClutterTransition *transition;
* ClutterInterval *interval;
*
* transition = clutter_property_transition_new ("opacity");
*
- * /* we want to animate the opacity between 0 and 255 */
+ * // we want to animate the opacity between 0 and 255
* clutter_transition_set_from (transition, G_TYPE_UINT, 0);
* clutter_transition_set_to (transition, G_TYPE_UINT, 255);
*
- * /* over a one second duration, running an infinite amount of times */
+ * // over a one second duration, running an infinite amount of times
* clutter_timeline_set_duration (CLUTTER_TIMELINE (transition), 1000);
* clutter_timeline_set_repeat_count (CLUTTER_TIMELINE (transition), -1);
*
- * /* we want to fade in and out, so we need to auto-reverse the transition */
+ * // we want to fade in and out, so we need to auto-reverse the transition
* clutter_timeline_set_auto_reverse (CLUTTER_TIMELINE (transition), TRUE);
*
- * /* and we want to use an easing function that eases both in and out */
+ * // and we want to use an easing function that eases both in and out
* clutter_timeline_set_progress_mode (CLUTTER_TIMELINE (transition),
* CLUTTER_EASE_IN_OUT_CUBIC);
*
- * /* add the transition to the desired actor; this will
- * * start the animation.
- * */
+ * // add the transition to the desired actor to start it
* clutter_actor_add_transition (actor, "opacityAnimation", transition);
- * </programlisting></informalexample>
- * </formalpara>
- * </refsect2>
- *
- * <refsect2 id="ClutterActor-subclassing">
- * <title>Implementing an actor</title>
- * <para>Careful consideration should be given when deciding to implement
- * a #ClutterActor sub-class. It is generally recommended to implement a
- * sub-class of #ClutterActor only for actors that should be used as leaf
- * nodes of a scene graph.</para>
- * <para>If your actor should be painted in a custom way, you should
- * override the #ClutterActor::paint signal class handler. You can either
- * opt to chain up to the parent class implementation or decide to fully
- * override the default paint implementation; Clutter will set up the
- * transformations and clip regions prior to emitting the #ClutterActor::paint
- * signal.</para>
- * <para>By overriding the #ClutterActorClass.get_preferred_width() and
- * #ClutterActorClass.get_preferred_height() virtual functions it is
- * possible to change or provide the preferred size of an actor; similarly,
- * by overriding the #ClutterActorClass.allocate() virtual function it is
- * possible to control the layout of the children of an actor. Make sure to
- * always chain up to the parent implementation of the
- * #ClutterActorClass.allocate() virtual function.</para>
- * <para>In general, it is strongly encouraged to use delegation and
- * composition instead of direct subclassing.</para>
- * </refsect2>
- *
- * <refsect2 id="ClutterActor-script">
- * <title>ClutterActor custom properties for #ClutterScript</title>
- * <para>#ClutterActor defines a custom "rotation" property which
- * allows a short-hand description of the rotations to be applied
- * to an actor.</para>
- * <para>The syntax of the "rotation" property is the following:</para>
- * <informalexample>
- * <programlisting>
- * "rotation" : [
- * { "<axis>" : [ <angle>, [ <center> ] ] }
- * ]
- * </programlisting>
- * </informalexample>
- * <para>where the <emphasis>axis</emphasis> is the name of an enumeration
- * value of type #ClutterRotateAxis and <emphasis>angle</emphasis> is a
- * floating point value representing the rotation angle on the given axis,
- * in degrees.</para>
- * <para>The <emphasis>center</emphasis> array is optional, and if present
- * it must contain the center of rotation as described by two coordinates:
- * Y and Z for "x-axis"; X and Z for "y-axis"; and X and Y for
- * "z-axis".</para>
- * <para>#ClutterActor also defines a scriptable "margin" property which
- * follows the CSS "margin" shorthand.
- * <informalexample>
- * <programlisting>
- * // 4 values
- * "margin" : [ <top>, <right>, <bottom> <left> ]
- * // 3 values
- * "margin" : [ <top>, <left/right>, <bottom> ]
- * // 2 values
- * "margin" : [ <top/bottom>, <left/right> ]
- * // 1 value
- * "margin" : [ <top/right/bottom/left> ]
- * </programlisting>
- * </informalexample>
- * </para>
- * <para>#ClutterActor will also parse every positional and dimensional
- * property defined as a string through clutter_units_from_string(); you
- * should read the documentation for the #ClutterUnits parser format for
- * the valid units and syntax.</para>
- * </refsect2>
- *
- * <refsect2 id="ClutterActor-custom-animatable-properties">
- * <title>Custom animatable properties</title>
- * <para>#ClutterActor allows accessing properties of #ClutterAction,
- * #ClutterEffect, and #ClutterConstraint instances associated to an actor
- * instance for animation purposes.</para>
- * <para>In order to access a specific #ClutterAction or a #ClutterConstraint
- * property it is necessary to set the #ClutterActorMeta:name property on the
- * given action or constraint.</para>
- * <para>The property can be accessed using the following syntax:</para>
- * <informalexample>
- * <programlisting>
- * @<section>.<meta-name>.<property-name>
- * </programlisting>
- * </informalexample>
- * <para>The initial <emphasis>@</emphasis> is mandatory.</para>
- * <para>The <emphasis>section</emphasis> fragment can be one between
- * "actions", "constraints" and "effects".</para>
- * <para>The <emphasis>meta-name</emphasis> fragment is the name of the
- * action or constraint, as specified by the #ClutterActorMeta:name
- * property.</para>
- * <para>The <emphasis>property-name</emphasis> fragment is the name of the
- * action or constraint property to be animated.</para>
- * <para>The example below animates a #ClutterBindConstraint applied to an
- * actor using clutter_actor_animate(). The <emphasis>rect</emphasis> has
- * a binding constraint for the <emphasis>origin</emphasis> actor, and in
- * its initial state is overlapping the actor to which is bound to.</para>
- * <informalexample><programlisting>
+ * ]|
+ *
+ * ## Implementing an actor
+ *
+ * Careful consideration should be given when deciding to implement
+ * a #ClutterActor sub-class. It is generally recommended to implement a
+ * sub-class of #ClutterActor only for actors that should be used as leaf
+ * nodes of a scene graph.
+ *
+ * If your actor should be painted in a custom way, you should
+ * override the #ClutterActor::paint signal class handler. You can either
+ * opt to chain up to the parent class implementation or decide to fully
+ * override the default paint implementation; Clutter will set up the
+ * transformations and clip regions prior to emitting the #ClutterActor::paint
+ * signal.
+ *
+ * By overriding the #ClutterActorClass.get_preferred_width() and
+ * #ClutterActorClass.get_preferred_height() virtual functions it is
+ * possible to change or provide the preferred size of an actor; similarly,
+ * by overriding the #ClutterActorClass.allocate() virtual function it is
+ * possible to control the layout of the children of an actor. Make sure to
+ * always chain up to the parent implementation of the
+ * #ClutterActorClass.allocate() virtual function.
+ *
+ * In general, it is strongly encouraged to use delegation and composition
+ * instead of direct subclassing.
+ *
+ * ## ClutterActor custom properties for ClutterScript
+ *
+ * #ClutterActor defines a custom "rotation" property which allows a short-hand
+ * description of the rotations to be applied to an actor.
+ *
+ * The syntax of the "rotation" property is the following:
+ *
+ * |[
+ * "rotation" : [ { "<axis>" : [ <angle>, [ <center-point> ] ] } ]
+ * ]|
+ *
+ * where:
+ *
+ * - axis is the name of an enumeration value of type #ClutterRotateAxis
+ * - angle is a floating point value representing the rotation angle on the given axis in degrees
+ * - center-point is an optional array, and if present it must contain the center of rotation as described
by two coordinates:
+ * - Y and Z for "x-axis"
+ * - X and Z for "y-axis"
+ * - X and Y for "z-axis".
+ *
+ * #ClutterActor also defines a scriptable "margin" property which follows the CSS "margin" shorthand.
+ *
+ * |[
+ * // 4 values
+ * "margin" : [ top, right, bottom, left ]
+ * // 3 values
+ * "margin" : [ top, left/right, bottom ]
+ * // 2 values
+ * "margin" : [ top/bottom, left/right ]
+ * // 1 value
+ * "margin" : [ top/right/bottom/left ]
+ * ]|
+ *
+ * #ClutterActor will also parse every positional and dimensional
+ * property defined as a string through clutter_units_from_string(); you
+ * should read the documentation for the #ClutterUnits parser format for
+ * the valid units and syntax.
+ *
+ * ## Custom animatable properties
+ *
+ * #ClutterActor allows accessing properties of #ClutterAction,
+ * #ClutterEffect, and #ClutterConstraint instances associated to an actor
+ * instance for animation purposes.
+ *
+ * In order to access a specific #ClutterAction or a #ClutterConstraint
+ * property it is necessary to set the #ClutterActorMeta:name property on the
+ * given action or constraint.
+ *
+ * The property can be accessed using the following syntax:
+ *
+ * |[
+ * @<section>.<meta-name>.<property-name>
+ * ]|
+ *
+ * - the initial ` ` is mandatory
+ * - the `section` fragment can be one between "actions", "constraints" and "effects"
+ * - the `meta-name` fragment is the name of the action, effect, or constraint, as
+ * specified by the #ClutterActorMeta:name property of #ClutterActorMeta
+ * - the `property-name` fragment is the name of the action, effect, or constraint
+ * property to be animated.
+ *
+ * The example below animates a #ClutterBindConstraint applied to an actor
+ * using an explicit transition. The `rect` actor has a binding constraint
+ * on the `origin` actor, and in its initial state is overlapping the actor
+ * to which is bound to.
+ *
+ * |[<!-- language="C" -->
* constraint = clutter_bind_constraint_new (origin, CLUTTER_BIND_X, 0.0);
* clutter_actor_meta_set_name (CLUTTER_ACTOR_META (constraint), "bind-x");
* clutter_actor_add_constraint (rect, constraint);
@@ -455,11 +471,13 @@
* g_signal_connect (origin, "button-press-event",
* G_CALLBACK (on_button_press),
* rect);
- * </programlisting></informalexample>
- * <para>On button press, the rectangle "slides" from behind the actor to
- * which is bound to, using the #ClutterBindConstraint:offset property to
- * achieve the effect:</para>
- * <informalexample><programlisting>
+ * ]|
+ *
+ * On button press, the rectangle "slides" from behind the actor to
+ * which is bound to, using the #ClutterBindConstraint:offset property to
+ * achieve the effect:
+ *
+ * |[<!-- language="C" -->
* gboolean
* on_button_press (ClutterActor *origin,
* ClutterEvent *event,
@@ -467,43 +485,39 @@
* {
* ClutterTransition *transition;
*
- * /* the offset that we want to apply; this will make the actor
- * * slide in from behind the origin and rest at the right of
- * * the origin, plus a padding value.
- * */
+ * // the offset that we want to apply; this will make the actor
+ * // slide in from behind the origin and rest at the right of
+ * // the origin, plus a padding value
* float new_offset = clutter_actor_get_width (origin) + h_padding;
*
- * /* the property we wish to animate; the "@constraints" section
- * * tells Clutter to check inside the constraints associated
- * * with the actor; the "bind-x" section is the name of the
- * * constraint; and the "offset" is the name of the property
- * * on the constraint.
- * */
+ * // the property we wish to animate; the "@constraints" section
+ * // tells Clutter to check inside the constraints associated
+ * // with the actor; the "bind-x" section is the name of the
+ * // constraint; and the "offset" is the name of the property
+ * // on the constraint
* const char *prop = "@constraints.bind-x.offset";
*
- * /* create a new transition for the given property */
+ * // create a new transition for the given property
* transition = clutter_property_transition_new (prop);
*
- * /* set the easing mode and duration */
+ * // set the easing mode and duration
* clutter_timeline_set_progress_mode (CLUTTER_TIMELINE (transition),
* CLUTTER_EASE_OUT_CUBIC);
* clutter_timeline_set_duration (CLUTTER_TIMELINE (transition), 500);
*
- * /* create the interval with the initial and final values */
+ * // create the interval with the initial and final values
* clutter_transition_set_from (transition, G_TYPE_FLOAT, 0.f);
* clutter_transition_set_to (transition, G_TYPE_FLOAT, new_offset);
*
- * /* add the transition to the actor; this causes the animation
- * * to start. the name "offsetAnimation" can be used to retrieve
- * * the transition later.
- * */
+ * // add the transition to the actor; this causes the animation
+ * // to start. the name "offsetAnimation" can be used to retrieve
+ * // the transition later
* clutter_actor_add_transition (rect, "offsetAnimation", transition);
*
- * /* we handled the event */
+ * // we handled the event
* return CLUTTER_EVENT_STOP;
* }
- * </programlisting></informalexample>
- * </refsect2>
+ * ]|
*/
/**
@@ -1595,11 +1609,11 @@ clutter_actor_real_unmap (ClutterActor *self)
* When overriding #ClutterActorClass.unmap(), it is mandatory to
* chain up to the parent implementation.
*
- * <note>It is important to note that the implementation of the
+ * It is important to note that the implementation of the
* #ClutterActorClass.unmap() virtual function may be called after
* the #ClutterActorClass.destroy() or the #GObjectClass.dispose()
* implementation, but it is guaranteed to be called before the
- * #GObjectClass.finalize() implementation.</note>
+ * #GObjectClass.finalize() implementation.
*
* Since: 1.0
*/
@@ -2791,10 +2805,10 @@ clutter_actor_apply_transform_to_point (ClutterActor *self,
* using cogl_set_modelview_matrix() for example then you would want a matrix
* that transforms into eye coordinates.
*
- * <note><para>This function explicitly initializes the given @matrix. If you just
+ * Note: This function explicitly initializes the given @matrix. If you just
* want clutter to multiply a relative transformation with an existing matrix
* you can use clutter_actor_apply_relative_transformation_matrix()
- * instead.</para></note>
+ * instead.
*
*/
/* XXX: We should consider caching the stage relative modelview along with
@@ -2846,12 +2860,11 @@ _clutter_actor_transform_and_project_box (ClutterActor *self,
* Calculates the transformed coordinates of the four corners of the
* actor in the plane of @ancestor. The returned vertices relate to
* the #ClutterActorBox coordinates as follows:
- * <itemizedlist>
- * <listitem><para>@verts[0] contains (x1, y1)</para></listitem>
- * <listitem><para>@verts[1] contains (x2, y1)</para></listitem>
- * <listitem><para>@verts[2] contains (x1, y2)</para></listitem>
- * <listitem><para>@verts[3] contains (x2, y2)</para></listitem>
- * </itemizedlist>
+ *
+ * - @verts[0] contains (x1, y1)
+ * - @verts[1] contains (x2, y1)
+ * - @verts[2] contains (x1, y2)
+ * - @verts[3] contains (x2, y2)
*
* If @ancestor is %NULL the ancestor will be the #ClutterStage. In
* this case, the coordinates returned will be the coordinates on
@@ -2935,12 +2948,11 @@ clutter_actor_get_allocation_vertices (ClutterActor *self,
* Calculates the transformed screen coordinates of the four corners of
* the actor; the returned vertices relate to the #ClutterActorBox
* coordinates as follows:
- * <itemizedlist>
- * <listitem><para>v[0] contains (x1, y1)</para></listitem>
- * <listitem><para>v[1] contains (x2, y1)</para></listitem>
- * <listitem><para>v[2] contains (x1, y2)</para></listitem>
- * <listitem><para>v[3] contains (x2, y2)</para></listitem>
- * </itemizedlist>
+ *
+ * - v[0] contains (x1, y1)
+ * - v[1] contains (x2, y1)
+ * - v[2] contains (x1, y2)
+ * - v[3] contains (x2, y2)
*
* Since: 0.4
*/
@@ -3150,11 +3162,11 @@ _clutter_actor_apply_modelview_transform (ClutterActor *self,
* using cogl_set_modelview_matrix() for example then you would want a matrix
* that transforms into eye coordinates.
*
- * <note>This function doesn't initialize the given @matrix, it simply
+ * This function doesn't initialize the given @matrix, it simply
* multiplies the requested transformation matrix with the existing contents of
* @matrix. You can use cogl_matrix_init_identity() to initialize the @matrix
* before calling this function, or you can use
- * clutter_actor_get_relative_transformation_matrix() instead.</note>
+ * clutter_actor_get_relative_transformation_matrix() instead.
*/
void
_clutter_actor_apply_relative_transformation_matrix (ClutterActor *self,
@@ -6539,7 +6551,7 @@ clutter_actor_class_init (ClutterActorClass *klass)
*
* For instance:
*
- * |[
+ * |[<!-- language="C" -->
* ClutterRequestMode mode;
* gfloat natural_width, min_width;
* gfloat natural_height, min_height;
@@ -6548,20 +6560,20 @@ clutter_actor_class_init (ClutterActorClass *klass)
* if (mode == CLUTTER_REQUEST_HEIGHT_FOR_WIDTH)
* {
* clutter_actor_get_preferred_width (child, -1,
- * &min_width,
- * &natural_width);
+ * &min_width,
+ * &natural_width);
* clutter_actor_get_preferred_height (child, natural_width,
- * &min_height,
- * &natural_height);
+ * &min_height,
+ * &natural_height);
* }
* else
* {
* clutter_actor_get_preferred_height (child, -1,
- * &min_height,
- * &natural_height);
+ * &min_height,
+ * &natural_height);
* clutter_actor_get_preferred_width (child, natural_height,
- * &min_width,
- * &natural_width);
+ * &min_width,
+ * &natural_width);
* }
* ]|
*
@@ -7087,14 +7099,14 @@ clutter_actor_class_init (ClutterActorClass *klass)
* The X coordinate of an actor's anchor point, relative to
* the actor coordinate space, in pixels.
*
- * <warning>It is highly recommended not to use #ClutterActor:anchor-x,
+ * It is highly recommended not to use #ClutterActor:anchor-x,
* #ClutterActor:anchor-y, and #ClutterActor:anchor-gravity in newly
* written code; the anchor point adds an additional translation that
* will affect the actor's relative position with regards to its
* parent, as well as the position of its children. This change needs
* to always be taken into account when positioning the actor. It is
* recommended to use the #ClutterActor:pivot-point property instead,
- * as it will affect only the transformations.</warning>
+ * as it will affect only the transformations.
*
* Since: 0.8
*
@@ -7116,14 +7128,14 @@ clutter_actor_class_init (ClutterActorClass *klass)
* The Y coordinate of an actor's anchor point, relative to
* the actor coordinate space, in pixels
*
- * <warning>It is highly recommended not to use #ClutterActor:anchor-x,
+ * It is highly recommended not to use #ClutterActor:anchor-x,
* #ClutterActor:anchor-y, and #ClutterActor:anchor-gravity in newly
* written code; the anchor point adds an additional translation that
* will affect the actor's relative position with regards to its
* parent, as well as the position of its children. This change needs
* to always be taken into account when positioning the actor. It is
* recommended to use the #ClutterActor:pivot-point property instead,
- * as it will affect only the transformations.</warning>
+ * as it will affect only the transformations.
*
* Since: 0.8
*
@@ -7144,14 +7156,14 @@ clutter_actor_class_init (ClutterActorClass *klass)
*
* The anchor point expressed as a #ClutterGravity
*
- * <warning>It is highly recommended not to use #ClutterActor:anchor-x,
+ * It is highly recommended not to use #ClutterActor:anchor-x,
* #ClutterActor:anchor-y, and #ClutterActor:anchor-gravity in newly
* written code; the anchor point adds an additional translation that
* will affect the actor's relative position with regards to its
* parent, as well as the position of its children. This change needs
* to always be taken into account when positioning the actor. It is
* recommended to use the #ClutterActor:pivot-point property instead,
- * as it will affect only the transformations.</warning>
+ * as it will affect only the transformations.
*
* Since: 1.0
*
@@ -7848,33 +7860,32 @@ clutter_actor_class_init (ClutterActorClass *klass)
* GSignal API, redraw the UI and then call clutter_stage_ensure_redraw()
* themselves, like:
*
- * |[
+ * |[<!-- language="C" -->
* static void
* on_redraw_complete (gpointer data)
* {
* ClutterStage *stage = data;
*
- * /* execute the Clutter drawing pipeline */
+ * // execute the Clutter drawing pipeline
* clutter_stage_ensure_redraw (stage);
* }
*
* static void
* on_stage_queue_redraw (ClutterStage *stage)
* {
- * /* this prevents the default handler to run */
+ * // this prevents the default handler to run
* g_signal_stop_emission_by_name (stage, "queue-redraw");
*
- * /* queue a redraw with the host toolkit and call
- * * a function when the redraw has been completed
- * */
+ * // queue a redraw with the host toolkit and call
+ * // a function when the redraw has been completed
* queue_a_redraw (G_CALLBACK (on_redraw_complete), stage);
* }
* ]|
*
- * <note><para>This signal is emitted before the Clutter paint
+ * Note: This signal is emitted before the Clutter paint
* pipeline is executed. If you want to know when the pipeline has
- * been completed you should connect to the ::paint signal on the
- * Stage with g_signal_connect_after().</para></note>
+ * been completed you should use clutter_threads_add_repaint_func()
+ * or clutter_threads_add_repaint_func_full().
*
* Since: 1.0
*/
@@ -8189,12 +8200,12 @@ clutter_actor_class_init (ClutterActorClass *klass)
* Subclasses of #ClutterActor should override the #ClutterActorClass.paint
* virtual function paint themselves in that function.
*
- * <warning>It is strongly discouraged to connect a signal handler to
+ * It is strongly discouraged to connect a signal handler to
* the #ClutterActor::paint signal; if you want to change the paint
* sequence of an existing #ClutterActor instance, either create a new
* #ClutterActor class and override the #ClutterActorClass.paint virtual
* function, or use a #ClutterEffect. The #ClutterActor::paint signal
- * will be removed in a future version of Clutter.</warning>
+ * will be removed in a future version of Clutter.
*
* Since: 0.8
*
@@ -9548,9 +9559,9 @@ clutter_actor_get_preferred_height (ClutterActor *self,
* An allocation does not incorporate the actor's scale or anchor point;
* those transformations do not affect layout, only rendering.
*
- * <note>Do not call any of the clutter_actor_get_allocation_*() family
+ * Do not call any of the clutter_actor_get_allocation_*() family
* of functions inside the implementation of the get_preferred_width()
- * or get_preferred_height() virtual functions.</note>
+ * or get_preferred_height() virtual functions.
*
* Since: 0.8
*/
@@ -9922,7 +9933,7 @@ clutter_actor_allocate (ClutterActor *self,
* expected that the subclass will call clutter_layout_manager_allocate()
* by itself. For instance, the following code:
*
- * |[
+ * |[<!-- language="C" -->
* static void
* my_actor_allocate (ClutterActor *actor,
* const ClutterActorBox *allocation,
@@ -9931,18 +9942,18 @@ clutter_actor_allocate (ClutterActor *self,
* ClutterActorBox new_alloc;
* ClutterAllocationFlags new_flags;
*
- * adjust_allocation (allocation, &new_alloc);
+ * adjust_allocation (allocation, &new_alloc);
*
* new_flags = flags | CLUTTER_DELEGATE_LAYOUT;
*
- * /* this will use the layout manager set on the actor */
- * clutter_actor_set_allocation (actor, &new_alloc, new_flags);
+ * // this will use the layout manager set on the actor
+ * clutter_actor_set_allocation (actor, &new_alloc, new_flags);
* }
* ]|
*
* is equivalent to this:
*
- * |[
+ * |[<!-- language="C" -->
* static void
* my_actor_allocate (ClutterActor *actor,
* const ClutterActorBox *allocation,
@@ -9951,14 +9962,14 @@ clutter_actor_allocate (ClutterActor *self,
* ClutterLayoutManager *layout;
* ClutterActorBox new_alloc;
*
- * adjust_allocation (allocation, &new_alloc);
+ * adjust_allocation (allocation, &new_alloc);
*
- * clutter_actor_set_allocation (actor, &new_alloc, flags);
+ * clutter_actor_set_allocation (actor, &new_alloc, flags);
*
* layout = clutter_actor_get_layout_manager (actor);
* clutter_layout_manager_allocate (layout,
* CLUTTER_CONTAINER (actor),
- * &new_alloc,
+ * &new_alloc,
* flags);
* }
* ]|
@@ -10650,7 +10661,7 @@ clutter_actor_get_transformed_position (ClutterActor *self,
* If you want the transformed allocation, see
* clutter_actor_get_abs_allocation_vertices() instead.
*
- * <note>When the actor (or one of its ancestors) is rotated around the
+ * When the actor (or one of its ancestors) is rotated around the
* X or Y axis, it no longer appears as on the stage as a rectangle, but
* as a generic quadrangle; in that case this function returns the size
* of the smallest rectangle that encapsulates the entire quad. Please
@@ -10658,7 +10669,7 @@ clutter_actor_get_transformed_position (ClutterActor *self,
* position of this envelope to the absolute position of the actor, as
* returned by clutter_actor_get_transformed_position(); if you need this
* information, you need to use clutter_actor_get_abs_allocation_vertices()
- * to get the coords of the actual quadrangle.</note>
+ * to get the coords of the actual quadrangle.
*
* Since: 0.8
*/
@@ -11945,11 +11956,10 @@ clutter_actor_get_depth (ClutterActor *self)
* Sets the rotation angle of @self around the given axis.
*
* The rotation center coordinates used depend on the value of @axis:
- * <itemizedlist>
- * <listitem><para>%CLUTTER_X_AXIS requires @y and @z</para></listitem>
- * <listitem><para>%CLUTTER_Y_AXIS requires @x and @z</para></listitem>
- * <listitem><para>%CLUTTER_Z_AXIS requires @x and @y</para></listitem>
- * </itemizedlist>
+ *
+ * - %CLUTTER_X_AXIS requires @y and @z
+ * - %CLUTTER_Y_AXIS requires @x and @z
+ * - %CLUTTER_Z_AXIS requires @x and @y
*
* The rotation coordinates are relative to the anchor point of the
* actor, set using clutter_actor_set_anchor_point(). If no anchor
@@ -14876,10 +14886,10 @@ clutter_animatable_iface_init (ClutterAnimatableIface *iface)
* nature of the operation. In general the error grows when the skewing
* of the actor rectangle on screen increases.
*
- * <note><para>This function can be computationally intensive.</para></note>
+ * This function can be computationally intensive.
*
- * <note><para>This function only works when the allocation is up-to-date,
- * i.e. inside of paint().</para></note>
+ * This function only works when the allocation is up-to-date, i.e. inside of
+ * the #ClutterActorClass.paint() implementation
*
* Return value: %TRUE if conversion was successful.
*
@@ -15130,7 +15140,7 @@ clutter_actor_get_stage (ClutterActor *actor)
* actor's natural height
* @flags: flags controlling the allocation
*
- * Allocates @self taking into account the #ClutterActor<!-- -->'s
+ * Allocates @self taking into account the #ClutterActor's
* preferred size, but limiting it to the maximum available width
* and height provided.
*
@@ -15139,36 +15149,36 @@ clutter_actor_get_stage (ClutterActor *actor)
*
* The implementation of this function is equivalent to:
*
- * |[
+ * |[<!-- language="C" -->
* if (request_mode == CLUTTER_REQUEST_HEIGHT_FOR_WIDTH)
* {
* clutter_actor_get_preferred_width (self, available_height,
- * &min_width,
- * &natural_width);
+ * &min_width,
+ * &natural_width);
* width = CLAMP (natural_width, min_width, available_width);
*
* clutter_actor_get_preferred_height (self, width,
- * &min_height,
- * &natural_height);
+ * &min_height,
+ * &natural_height);
* height = CLAMP (natural_height, min_height, available_height);
* }
* else
* {
* clutter_actor_get_preferred_height (self, available_width,
- * &min_height,
- * &natural_height);
+ * &min_height,
+ * &natural_height);
* height = CLAMP (natural_height, min_height, available_height);
*
* clutter_actor_get_preferred_width (self, height,
- * &min_width,
- * &natural_width);
+ * &min_width,
+ * &natural_width);
* width = CLAMP (natural_width, min_width, available_width);
* }
*
* box.x1 = x; box.y1 = y;
* box.x2 = box.x1 + available_width;
* box.y2 = box.y1 + available_height;
- * clutter_actor_allocate (self, &box, flags);
+ * clutter_actor_allocate (self, &box, flags);
* ]|
*
* This function can be used by fluid layout managers to allocate
@@ -16158,7 +16168,7 @@ clutter_actor_get_text_direction (ClutterActor *self)
* Should be used by actors implementing the #ClutterContainer and with
* internal children added through clutter_actor_set_parent(), for instance:
*
- * |[
+ * |[<!-- language="C" -->
* static void
* my_actor_init (MyActor *self)
* {
@@ -16166,25 +16176,23 @@ clutter_actor_get_text_direction (ClutterActor *self)
*
* clutter_actor_push_internal (CLUTTER_ACTOR (self));
*
- * /* calling clutter_actor_set_parent() now will result in
- * * the internal flag being set on a child of MyActor
- * */
+ * // calling clutter_actor_set_parent() now will result in
+ * // the internal flag being set on a child of MyActor
*
- * /* internal child - a background texture */
+ * // internal child - a background texture
* self->priv->background_tex = clutter_texture_new ();
* clutter_actor_set_parent (self->priv->background_tex,
* CLUTTER_ACTOR (self));
*
- * /* internal child - a label */
+ * // internal child - a label
* self->priv->label = clutter_text_new ();
* clutter_actor_set_parent (self->priv->label,
* CLUTTER_ACTOR (self));
*
* clutter_actor_pop_internal (CLUTTER_ACTOR (self));
*
- * /* calling clutter_actor_set_parent() now will not result in
- * * the internal flag being set on a child of MyActor
- * */
+ * // calling clutter_actor_set_parent() now will not result in
+ * // the internal flag being set on a child of MyActor
* }
* ]|
*
@@ -16368,7 +16376,7 @@ clutter_actor_add_action (ClutterActor *self,
*
* This function is the logical equivalent of:
*
- * |[
+ * |[<!-- language="C" -->
* clutter_actor_meta_set_name (CLUTTER_ACTOR_META (action), name);
* clutter_actor_add_action (self, action);
* ]|
@@ -16574,7 +16582,7 @@ clutter_actor_add_constraint (ClutterActor *self,
*
* This function is the logical equivalent of:
*
- * |[
+ * |[<!-- language="C" -->
* clutter_actor_meta_set_name (CLUTTER_ACTOR_META (constraint), name);
* clutter_actor_add_constraint (self, constraint);
* ]|
@@ -16824,7 +16832,7 @@ clutter_actor_add_effect (ClutterActor *self,
*
* This function is the logical equivalent of:
*
- * |[
+ * |[<!-- language="C" -->
* clutter_actor_meta_set_name (CLUTTER_ACTOR_META (effect), name);
* clutter_actor_add_effect (self, effect);
* ]|
@@ -17157,16 +17165,16 @@ _clutter_actor_get_paint_volume_mutable (ClutterActor *self)
* The paint volume is defined as the 3D space occupied by an actor
* when being painted.
*
- * This function will call the <function>get_paint_volume()</function>
+ * This function will call the #ClutterActorClass.get_paint_volume()
* virtual function of the #ClutterActor class. Sub-classes of #ClutterActor
* should not usually care about overriding the default implementation,
* unless they are, for instance: painting outside their allocation, or
* actors with a depth factor (not in terms of #ClutterActor:depth but real
* 3D depth).
*
- * <note>2D actors overriding <function>get_paint_volume()</function>
- * ensure their volume has a depth of 0. (This will be true so long as
- * you don't call clutter_paint_volume_set_depth().)</note>
+ * Note: 2D actors overriding #ClutterActorClass.get_paint_volume()
+ * should ensure that their volume has a depth of 0. (This will be true
+ * as long as you don't call clutter_paint_volume_set_depth().)
*
* Return value: (transfer none): a pointer to a #ClutterPaintVolume,
* or %NULL if no volume could be determined. The returned pointer
@@ -17296,7 +17304,7 @@ clutter_actor_get_paint_box (ClutterActor *self,
* the opacity property.
*
* Custom actors can override the default response by implementing the
- * #ClutterActor <function>has_overlaps</function> virtual function. See
+ * #ClutterActorClass.has_overlaps() virtual function. See
* clutter_actor_set_offscreen_redirect() for more information.
*
* Return value: %TRUE if the actor may have overlapping primitives, and
@@ -18337,14 +18345,14 @@ typedef struct _RealActorIter
* Modifying the scene graph section that contains @root will invalidate
* the iterator.
*
- * |[
+ * |[<!-- language="C" -->
* ClutterActorIter iter;
* ClutterActor *child;
*
* clutter_actor_iter_init (&iter, container);
* while (clutter_actor_iter_next (&iter, &child))
* {
- * /* do something with child */
+ * // do something with child
* }
* ]|
*
@@ -19294,7 +19302,7 @@ clutter_actor_get_easing_delay (ClutterActor *self)
* Transitions created for animatable properties use the name of the
* property itself, for instance the code below:
*
- * |[
+ * |[<!-- language="C" -->
* clutter_actor_set_easing_duration (actor, 1000);
* clutter_actor_set_rotation (actor, CLUTTER_Y_AXIS, 360.0, x, y, z);
*
@@ -19304,8 +19312,8 @@ clutter_actor_get_easing_delay (ClutterActor *self)
* actor);
* ]|
*
- * will call the <function>on_transition_stopped</function> callback when
- * the transition is finished.
+ * will call the `on_transition_stopped` callback when the transition
+ * is finished.
*
* If you just want to get notifications of the completion of a transition,
* you should use the #ClutterActor::transition-stopped signal, using the
diff --git a/clutter/clutter-backend.c b/clutter/clutter-backend.c
index 0ceb2e2..d255eee 100644
--- a/clutter/clutter-backend.c
+++ b/clutter/clutter-backend.c
@@ -1344,12 +1344,12 @@ _clutter_backend_remove_event_translator (ClutterBackend *backend,
* @backend. A #CoglContext is required when using some of the
* experimental 2.0 Cogl API.
*
- * <note>Since CoglContext is itself experimental API this API should
- * be considered experimental too.</note>
+ * Since CoglContext is itself experimental API this API should
+ * be considered experimental too.
*
- * <note>This API is not yet supported on OSX because OSX still
+ * This API is not yet supported on OSX because OSX still
* uses the stub Cogl winsys and the Clutter backend doesn't
- * explicitly create a CoglContext.</note>
+ * explicitly create a CoglContext.
*
* Return value: (transfer none): The #CoglContext associated with @backend.
*
diff --git a/clutter/clutter-bin-layout.c b/clutter/clutter-bin-layout.c
index adf235d..2ee8012 100644
--- a/clutter/clutter-bin-layout.c
+++ b/clutter/clutter-bin-layout.c
@@ -29,34 +29,16 @@
* #ClutterBinLayout is a layout manager which implements the following
* policy:
*
- * <itemizedlist>
- * <listitem><simpara>the preferred size is the maximum preferred size
+ * - the preferred size is the maximum preferred size
* between all the children of the container using the
- * layout;</simpara></listitem>
- * <listitem><simpara>each child is allocated in "layers", on on top
- * of the other;</simpara></listitem>
- * <listitem><simpara>for each layer there are horizontal and vertical
- * alignment policies.</simpara></listitem>
- * </itemizedlist>
+ * layout;
+ * - each child is allocated in "layers", on on top
+ * of the other;
+ * - for each layer there are horizontal and vertical
+ * alignment policies.
*
- * <figure id="bin-layout">
- * <title>Bin layout</title>
- * <para>The image shows a #ClutterBinLayout with three layers:
- * a background #ClutterCairoTexture, set to fill on both the X
- * and Y axis; a #ClutterTexture, set to center on both the X and
- * Y axis; and a #ClutterRectangle, set to %CLUTTER_BIN_ALIGNMENT_END
- * on both the X and Y axis.</para>
- * <graphic fileref="bin-layout.png" format="PNG"/>
- * </figure>
- *
- * <example id="example-clutter-bin-layout">
- * <title>How to pack actors inside a BinLayout</title>
- * <programlisting>
- * <xi:include xmlns:xi="http://www.w3.org/2001/XInclude"; parse="text"
href="../../../../examples/bin-layout.c">
- * <xi:fallback>FIXME: MISSING XINCLUDE CONTENT</xi:fallback>
- * </xi:include>
- * </programlisting>
- * </example>
+ * The [bin-layout example](https://git.gnome.org/browse/clutter/tree/examples/bin-layout.c?h=clutter-1.18)
+ * shows how to pack actors inside a #ClutterBinLayout.
*
* #ClutterBinLayout is available since Clutter 1.2
*/
diff --git a/clutter/clutter-bind-constraint.c b/clutter/clutter-bind-constraint.c
index fa94906..53cbbba 100644
--- a/clutter/clutter-bind-constraint.c
+++ b/clutter/clutter-bind-constraint.c
@@ -36,14 +36,14 @@
* can also be animated. For instance, the following code will set up three
* actors to be bound to the same origin:
*
- * |[
- * /* source */
- * rect[0] = clutter_rectangle_new_with_color (&red_color);
+ * |[<!-- language="C" -->
+ * // source
+ * rect[0] = clutter_rectangle_new_with_color (&red_color);
* clutter_actor_set_position (rect[0], x_pos, y_pos);
* clutter_actor_set_size (rect[0], 100, 100);
*
- * /* second rectangle */
- * rect[1] = clutter_rectangle_new_with_color (&green_color);
+ * // second rectangle
+ * rect[1] = clutter_rectangle_new_with_color (&green_color);
* clutter_actor_set_size (rect[1], 100, 100);
* clutter_actor_set_opacity (rect[1], 0);
*
@@ -52,8 +52,8 @@
* constraint = clutter_bind_constraint_new (rect[0], CLUTTER_BIND_Y, 0.0);
* clutter_actor_add_constraint_with_name (rect[1], "green-y", constraint);
*
- * /* third rectangle */
- * rect[2] = clutter_rectangle_new_with_color (&blue_color);
+ * // third rectangle
+ * rect[2] = clutter_rectangle_new_with_color (&blue_color);
* clutter_actor_set_size (rect[2], 100, 100);
* clutter_actor_set_opacity (rect[2], 0);
*
@@ -66,7 +66,7 @@
* The following code animates the second and third rectangles to "expand"
* them horizontally from underneath the first rectangle:
*
- * |[
+ * |[<!-- language="C" -->
* clutter_actor_animate (rect[1], CLUTTER_EASE_OUT_CUBIC, 250,
* "@constraints.green-x.offset", 100.0,
* "opacity", 255,
@@ -77,21 +77,6 @@
* NULL);
* ]|
*
- * <example id="bind-constraint-example">
- * <title>Animating the offset property of ClutterBindConstraint</title>
- * <programlisting>
- * <xi:include xmlns:xi="http://www.w3.org/2001/XInclude"; parse="text"
href="../../../../tests/interactive/test-bind-constraint.c">
- * <xi:fallback>FIXME: MISSING XINCLUDE CONTENT</xi:fallback>
- * </xi:include>
- * </programlisting>
- * <para>The example above creates eight rectangles and binds them to a
- * rectangle positioned in the center of the stage; when the user presses
- * the center rectangle, the #ClutterBindConstraint:offset property is
- * animated through the clutter_actor_animate() function to lay out the
- * eight rectangles around the center one. Pressing one of the outer
- * rectangles will animate the offset back to 0.</para>
- * </example>
- *
* #ClutterBindConstraint is available since Clutter 1.4
*/
diff --git a/clutter/clutter-binding-pool.c b/clutter/clutter-binding-pool.c
index 6bce923..66959c7 100644
--- a/clutter/clutter-binding-pool.c
+++ b/clutter/clutter-binding-pool.c
@@ -38,7 +38,7 @@
* inside their class initialization function and then install actions
* like this:
*
- * |[
+ * |[<!-- language="C" -->
* static void
* foo_class_init (FooClass *klass)
* {
@@ -59,7 +59,7 @@
*
* The callback has a signature of:
*
- * |[
+ * |[<!-- language="C" -->
* gboolean (* callback) (GObject *instance,
* const gchar *action_name,
* guint key_val,
@@ -71,19 +71,18 @@
* use clutter_binding_pool_activate() to match a #ClutterKeyEvent structure
* to one of the actions:
*
- * |[
+ * |[<!-- language="C" -->
* ClutterBindingPool *pool;
*
- * /* retrieve the binding pool for the type of the actor */
+ * // retrieve the binding pool for the type of the actor
* pool = clutter_binding_pool_find (G_OBJECT_TYPE_NAME (actor));
*
- * /* activate any callback matching the key symbol and modifiers
- * * mask of the key event. the returned value can be directly
- * * used to signal that the actor has handled the event.
- * */
+ * // activate any callback matching the key symbol and modifiers
+ * // mask of the key event. the returned value can be directly
+ * // used to signal that the actor has handled the event.
* return clutter_binding_pool_activate (pool,
- * key_event->keyval,
- * key_event->modifier_state,
+ * key_event->keyval,
+ * key_event->modifier_state,
* G_OBJECT (actor));
* ]|
*
diff --git a/clutter/clutter-box-layout.c b/clutter/clutter-box-layout.c
index 82ff6f0..20b2628 100644
--- a/clutter/clutter-box-layout.c
+++ b/clutter/clutter-box-layout.c
@@ -31,30 +31,16 @@
*
* The #ClutterBoxLayout is a #ClutterLayoutManager implementing the
* following layout policy:
- * <itemizedlist>
- * <listitem><para>all children are arranged on a single
- * line;</para></listitem>
- * <listitem><para>the axis used is controlled by the
- * #ClutterBoxLayout:orientation property;</para></listitem>
- * <listitem><para>the order of the packing is determined by the
- * #ClutterBoxLayout:pack-start boolean property;</para></listitem>
- * <listitem><para>each child will be allocated to its natural
- * size or, if #ClutterActor:x-expand/#ClutterActor:y-expand
- * is set, the available size;</para></listitem>
- * <listitem><para>honours the #ClutterActor's #ClutterActor:x-align
- * and #ClutterActor:y-align properties to fill the available
- * size;</para></listitem>
- * <listitem><para>if the #ClutterBoxLayout:homogeneous boolean property
- * is set, then all widgets will get the same size, ignoring expand
- * settings and the preferred sizes</para></listitem>
- * </itemizedlist>
- *
- * <figure id="box-layout">
- * <title>Box layout</title>
- * <para>The image shows a #ClutterBoxLayout with the
- * #ClutterBoxLayout:vertical property set to %FALSE.</para>
- * <graphic fileref="box-layout.png" format="PNG"/>
- * </figure>
+ *
+ * - all children are arranged on a single line
+ * - the axis used is controlled by the #ClutterBoxLayout:orientation property
+ * - the order of the packing is determined by the #ClutterBoxLayout:pack-start boolean property
+ * - each child will be allocated to its natural size or, if #ClutterActor:x-expand or
+ * #ClutterActor:y-expand are set, the available size
+ * - honours the #ClutterActor's #ClutterActor:x-align and #ClutterActor:y-align properties
+ * to fill the available size
+ * - if the #ClutterBoxLayout:homogeneous boolean propert is set, then all widgets will
+ * get the same size, ignoring expand settings and the preferred sizes
*
* It is possible to control the spacing between children of a
* #ClutterBoxLayout by using clutter_box_layout_set_spacing().
diff --git a/clutter/clutter-canvas.c b/clutter/clutter-canvas.c
index eb9eeb8..8291516 100644
--- a/clutter/clutter-canvas.c
+++ b/clutter/clutter-canvas.c
@@ -36,13 +36,8 @@
* that can be used to draw. #ClutterCanvas will emit the #ClutterCanvas::draw
* signal when invalidated using clutter_content_invalidate().
*
- * <informalexample id="canvas-example">
- * <programlisting>
- * <xi:include xmlns:xi="http://www.w3.org/2001/XInclude"; parse="text" href="../../../../examples/canvas.c">
- * <xi:fallback>FIXME: MISSING XINCLUDE CONTENT</xi:fallback>
- * </xi:include>
- * </programlisting>
- * </informalexample>
+ * See [canvas.c](https://git.gnome.org/browse/clutter/tree/examples/canvas.c?h=clutter-1.18)
+ * for an example of how to use #ClutterCanvas.
*
* #ClutterCanvas is available since Clutter 1.10.
*/
diff --git a/clutter/clutter-child-meta.h b/clutter/clutter-child-meta.h
index df6246c..7e785a9 100644
--- a/clutter/clutter-child-meta.h
+++ b/clutter/clutter-child-meta.h
@@ -63,14 +63,14 @@ typedef struct _ClutterChildMetaClass ClutterChildMetaClass;
* static void
* my_container_iface_init (ClutterContainerIface *iface)
* {
- * /* set the rest of the #ClutterContainer vtable */
+ * // set the rest of the #ClutterContainer vtable
*
* container_iface->child_meta_type = MY_TYPE_CHILD_META;
* }
* ]|
*
* This will automatically create a #ClutterChildMeta of type
- * MY_TYPE_CHILD_META for every actor that is added to the container.
+ * `MY_TYPE_CHILD_META` for every actor that is added to the container.
*
* The child data for an actor can be retrieved using the
* clutter_container_get_child_meta() function.
@@ -81,9 +81,8 @@ typedef struct _ClutterChildMetaClass ClutterChildMetaClass;
*
* You can provide hooks for your own storage as well as control the
* instantiation by overriding the #ClutterContainerIface virtual functions
- * <function>create_child_meta</function>,
- * <function>destroy_child_meta</function>,
- * and <function>get_child_meta</function>.
+ * #ClutterContainerIface.create_child_meta(), #ClutterContainerIface.destroy_child_meta(),
+ * and #ClutterContainerIface.get_child_meta().
*
* Since: 0.8
*/
diff --git a/clutter/clutter-clone.c b/clutter/clutter-clone.c
index 3de1c05..3bcd0c3 100644
--- a/clutter/clutter-clone.c
+++ b/clutter/clutter-clone.c
@@ -30,9 +30,9 @@
*
* #ClutterClone can be used to efficiently clone any other actor.
*
- * <note><para>This is different from clutter_texture_new_from_actor()
- * which requires support for FBOs in the underlying GL
- * implementation.</para></note>
+ * Unlike clutter_texture_new_from_actor(), #ClutterClone does not require
+ * the presence of support for FBOs in the underlying GL or GLES
+ * implementation.
*
* #ClutterClone is available since Clutter 1.0
*/
diff --git a/clutter/clutter-color.c b/clutter/clutter-color.c
index 04b1cfa..96dde94 100644
--- a/clutter/clutter-color.c
+++ b/clutter/clutter-color.c
@@ -624,28 +624,12 @@ parse_hsla (ClutterColor *color,
*
* The format of @str can be either one of:
*
- * <itemizedlist>
- * <listitem>
- * <para>a standard name (as taken from the X11 rgb.txt file)</para>
- * </listitem>
- * <listitem>
- * <para>an hexadecimal value in the form: <literal>#rgb</literal>,
- * <literal>#rrggbb</literal>, <literal>#rgba</literal> or
- * <literal>#rrggbbaa</literal></para>
- * </listitem>
- * <listitem>
- * <para>a RGB color in the form: <literal>rgb(r, g, b)</literal></para>
- * </listitem>
- * <listitem>
- * <para>a RGB color in the form: <literal>rgba(r, g, b, a)</literal></para>
- * </listitem>
- * <listitem>
- * <para>a HSL color in the form: <literal>hsl(h, s, l)</literal></para>
- * </listitem>
- * <listitem>
- * <para>a HSL color in the form: <literal>hsla(h, s, l, a)</literal></para>
- * </listitem>
- * </itemizedlist>
+ * - a standard name (as taken from the X11 rgb.txt file)
+ * - an hexadecimal value in the form: `#rgb`, `#rrggbb`, `#rgba`, or `#rrggbbaa`
+ * - a RGB color in the form: `rgb(r, g, b)`
+ * - a RGB color in the form: `rgba(r, g, b, a)`
+ * - a HSL color in the form: `hsl(h, s, l)`
+ * -a HSL color in the form: `hsla(h, s, l, a)`
*
* where 'r', 'g', 'b' and 'a' are (respectively) the red, green, blue color
* intensities and the opacity. The 'h', 's' and 'l' are (respectively) the
diff --git a/clutter/clutter-constraint.c b/clutter/clutter-constraint.c
index 9b481b5..8749ed9 100644
--- a/clutter/clutter-constraint.c
+++ b/clutter/clutter-constraint.c
@@ -13,126 +13,95 @@
* allocation of the actor to which they are applied by overriding the
* #ClutterConstraintClass.update_allocation() virtual function.
*
- * <refsect2 id="ClutterConstraint-usage">
- * <title>Using Constraints</title>
- * <para>Constraints can be used with fixed layout managers, like
- * #ClutterFixedLayout, or with actors implicitly using a fixed layout
- * manager, like #ClutterGroup and #ClutterStage.</para>
- * <para>Constraints provide a way to build user interfaces by using
- * relations between #ClutterActor<!-- -->s, without explicit fixed
- * positioning and sizing, similarly to how fluid layout managers like
- * #ClutterBoxLayout and #ClutterTableLayout lay out their children.</para>
- * <para>Constraints are attached to a #ClutterActor, and are available
- * for inspection using clutter_actor_get_constraints().</para>
- * <para>Clutter provides different implementation of the #ClutterConstraint
- * abstract class, for instance:</para>
- * <variablelist>
- * <varlistentry>
- * <term>#ClutterAlignConstraint</term>
- * <listitem><simpara>this constraint can be used to align an actor
- * to another one, on either the horizontal or the vertical axis; the
- * #ClutterAlignConstraint uses a normalized offset between 0.0 (the
- * top or the left of the source actor, depending on the axis) and
- * 1.0 (the bottom or the right of the source actor, depending on the
- * axis).</simpara></listitem>
- * </varlistentry>
- * <varlistentry>
- * <term>#ClutterBindConstraint</term>
- * <listitem><simpara>this constraint binds the X, Y, width or height
- * of an actor to the corresponding position or size of a source
- * actor; it can also apply an offset.</simpara></listitem>
- * </varlistentry>
- * <varlistentry>
- * <term>#ClutterSnapConstraint</term>
- * <listitem><simpara>this constraint "snaps" together the edges of
- * two #ClutterActor<!-- -->s; if an actor uses two constraints on
- * both its horizontal or vertical edges then it can also expand to
- * fit the empty space.</simpara></listitem>
- * </varlistentry>
- * </variablelist>
- * <example id="ClutterConstraint-usage-example">
- * <title>Usage of constraints</title>
- * <para>The example below uses various #ClutterConstraint<!-- -->s to
- * lay out three actors on a resizable stage. Only the central actor has
- * an explicit size, and no actor has an explicit position.</para>
- * <orderedlist>
- * <listitem><simpara>The #ClutterRectangle with #ClutterActor:name
- * <emphasis>layerA</emphasis> is explicitly sized to 100 pixels by 25
- * pixels, and it's added to the #ClutterStage;</simpara></listitem>
- * <listitem><simpara>two #ClutterAlignConstraint<!-- -->s are used
- * to anchor <emphasis>layerA</emphasis> to the center of the stage,
- * by using 0.5 as the alignment #ClutterAlignConstraint:factor on
- * both the X and Y axis.</simpara></listitem>
- * <listitem><simpara>the #ClutterRectangle with #ClutterActor:name
- * <emphasis>layerB</emphasis> is added to the #ClutterStage with
- * no explicit size;</simpara></listitem>
- * <listitem><simpara>the #ClutterActor:x and #ClutterActor:width
- * of <emphasis>layerB</emphasis> are bound to the same properties
- * of <emphasis>layerA</emphasis> using two #ClutterBindConstraint
- * objects, thus keeping <emphasis>layerB</emphasis> aligned to
- * <emphasis>layerA</emphasis>;</simpara></listitem>
- * <listitem><simpara>the top edge of <emphasis>layerB</emphasis> is
- * snapped together with the bottom edge of <emphasis>layerA</emphasis>;
- * the bottom edge of <emphasis>layerB</emphasis> is also snapped
- * together with the bottom edge of the #ClutterStage; an offset is
- * given to the two #ClutterSnapConstraint<!-- -->s to allow for some
- * padding; since <emphasis>layerB</emphasis> is snapped between two
- * different #ClutterActor<!-- -->s, its height is stretched to match
- * the gap;</simpara></listitem>
- * <listitem><simpara>the #ClutterRectangle with #ClutterActor:name
- * <emphasis>layerC</emphasis> mirrors <emphasis>layerB</emphasis>,
- * snapping the top edge of the #ClutterStage to the top edge of
- * <emphasis>layerC</emphasis> and the top edge of
- * <emphasis>layerA</emphasis> to the bottom edge of
- * <emphasis>layerC</emphasis>;</simpara></listitem>
- * </orderedlist>
- * <figure id="constraints-example">
- * <title>Constraints</title>
- * <graphic fileref="constraints-example.png" format="PNG"/>
- * </figure>
- * <programlisting>
- *<xi:include xmlns:xi="http://www.w3.org/2001/XInclude"; href="../../../../examples/constraints.c"
parse="text">
- * <xi:fallback>FIXME: MISSING XINCLUDE CONTENT</xi:fallback>
- *</xi:include>
- * </programlisting>
- * <para>You can try resizing interactively the #ClutterStage and verify
- * that the three #ClutterActor<!-- -->s maintain the same position and
- * size relative to each other, and to the #ClutterStage.</para>
- * </example>
- * <warning><para>It's important to note that Clutter does not avoid loops
- * or competing constraints; if two or more #ClutterConstraint<!-- -->s
- * are operating on the same positional or dimensional attributes of an
- * actor, or if the constraints on two different actors depend on each
- * other, then the behavior is undefined.</para></warning>
- * </refsect2>
- *
- * <refsect2 id="ClutterConstraint-implementation">
- * <title>Implementing a ClutterConstraint</title>
- * <para>Creating a sub-class of #ClutterConstraint requires the
- * implementation of the <function>update_allocation()</function>
- * virtual function.</para>
- * <para>The <function>update_allocation()</function> virtual function
- * is called during the allocation sequence of a #ClutterActor, and
- * allows any #ClutterConstraint attached to that actor to modify the
- * allocation before it is passed to the <function>allocate()</function>
- * implementation.</para>
- * <para>The #ClutterActorBox passed to the
- * <function>update_allocation()</function> implementation contains the
- * original allocation of the #ClutterActor, plus the eventual modifications
- * applied by the other #ClutterConstraint<!-- -->s.</para>
- * <note><para>Constraints are queried in the same order as they were
- * applied using clutter_actor_add_constraint() or
- * clutter_actor_add_constraint_with_name().</para></note>
- * <para>It is not necessary for a #ClutterConstraint sub-class to chain
- * up to the parent's implementation.</para>
- * <para>If a #ClutterConstraint is parametrized - i.e. if it contains
- * properties that affect the way the constraint is implemented - it should
- * call clutter_actor_queue_relayout() on the actor to which it is attached
- * to whenever any parameter is changed. The actor to which it is attached
- * can be recovered at any point using clutter_actor_meta_get_actor().</para>
- * </refsect2>
- *
* #ClutterConstraint is available since Clutter 1.4
+ *
+ * ## Using Constraints
+ *
+ * Constraints can be used with fixed layout managers, like
+ * #ClutterFixedLayout, or with actors implicitly using a fixed layout
+ * manager, like #ClutterGroup and #ClutterStage.
+ *
+ * Constraints provide a way to build user interfaces by using
+ * relations between #ClutterActors, without explicit fixed
+ * positioning and sizing, similarly to how fluid layout managers like
+ * #ClutterBoxLayout and #ClutterTableLayout lay out their children.
+ *
+ * Constraints are attached to a #ClutterActor, and are available
+ * for inspection using clutter_actor_get_constraints().
+ *
+ * Clutter provides different implementation of the #ClutterConstraint
+ * abstract class, for instance:
+ *
+ * - #ClutterAlignConstraint, a constraint that can be used to align
+ * an actor to another one on either the horizontal or the vertical
+ * axis, using a normalized value between 0 and 1.
+ * - #ClutterBindConstraint, a constraint binds the X, Y, width or height
+ * of an actor to the corresponding position or size of a source actor,
+ * with or without an offset.
+ * - #ClutterSnapConstraint, a constraint that "snaps" together the edges
+ * of two #ClutterActors; if an actor uses two constraints on both its
+ * horizontal or vertical edges then it can also expand to fit the empty
+ * space.
+ *
+ * The [constraints example](https://git.gnome.org/browse/clutter/tree/examples/constraints.c?h=clutter-1.18)
+ * uses various types of #ClutterConstraints to lay out three actors on a
+ * resizable stage. Only the central actor has an explicit size, and no
+ * actor has an explicit position.
+ *
+ * - The #ClutterActor with #ClutterActor:name `layerA` is explicitly
+ * sized to 100 pixels by 25 pixels, and it's added to the #ClutterStage
+ * - two #ClutterAlignConstraints are used to anchor `layerA` to the
+ * center of the stage, by using 0.5 as the alignment #ClutterAlignConstraint:factor on
+ * both the X and Y axis
+ * - the #ClutterActor with #ClutterActor:name `layerB` is added to the
+ * #ClutterStage with no explicit size
+ * - the #ClutterActor:x and #ClutterActor:width of `layerB` are bound
+ * to the same properties of `layerA` using two #ClutterBindConstraint
+ * objects, thus keeping `layerB` aligned to `layerA`
+ * - the top edge of `layerB` is snapped together with the bottom edge
+ * of `layerA`; the bottom edge of `layerB` is also snapped together with
+ * the bottom edge of the #ClutterStage; an offset is given to the two
+ * #ClutterSnapConstraintss to allow for some padding; since `layerB` is
+ * snapped between two different #ClutterActors, its height is stretched
+ * to match the gap
+ * - the #ClutterActor with #ClutterActor:name `layerC` mirrors `layerB`,
+ * snapping the top edge of the #ClutterStage to the top edge of `layerC`
+ * and the top edge of `layerA` to the bottom edge of `layerC`
+ *
+ * You can try resizing interactively the #ClutterStage and verify
+ * that the three #ClutterActors maintain the same position and
+ * size relative to each other, and to the #ClutterStage.
+ *
+ * It is important to note that Clutter does not avoid loops or
+ * competing constraints; if two or more #ClutterConstraints
+ * are operating on the same positional or dimensional attributes of an
+ * actor, or if the constraints on two different actors depend on each
+ * other, then the behavior is undefined.
+ *
+ * ## Implementing a ClutterConstraint
+ *
+ * Creating a sub-class of #ClutterConstraint requires the
+ * implementation of the #ClutterConstraintClass.update_allocation()
+ * virtual function.
+ *
+ * The `update_allocation()` virtual function is called during the
+ * allocation sequence of a #ClutterActor, and allows any #ClutterConstraint
+ * attached to that actor to modify the allocation before it is passed to
+ * the actor's #ClutterActorClass.allocate() implementation.
+ *
+ * The #ClutterActorBox passed to the `update_allocation()` implementation
+ * contains the original allocation of the #ClutterActor, plus the eventual
+ * modifications applied by the other #ClutterConstraints, in the same order
+ * the constraints have been applied to the actor.
+ *
+ * It is not necessary for a #ClutterConstraint sub-class to chain
+ * up to the parent's implementation.
+ *
+ * If a #ClutterConstraint is parametrized - i.e. if it contains
+ * properties that affect the way the constraint is implemented - it should
+ * call clutter_actor_queue_relayout() on the actor to which it is attached
+ * to whenever any parameter is changed. The actor to which it is attached
+ * can be recovered at any point using clutter_actor_meta_get_actor().
*/
#ifdef HAVE_CONFIG_H
diff --git a/clutter/clutter-deform-effect.c b/clutter/clutter-deform-effect.c
index f619505..925866a 100644
--- a/clutter/clutter-deform-effect.c
+++ b/clutter/clutter-deform-effect.c
@@ -39,17 +39,16 @@
* a #ClutterActor and then the Cogl vertex buffers API to submit the
* geometry to the GPU.
*
- * <refsect2>
- * <title>Implementing ClutterDeformEffect</title>
- * <para>Sub-classes of #ClutterDeformEffect should override the
- * #ClutterDeformEffectClass.deform_vertex() virtual function; this function
- * is called on every vertex that needs to be deformed by the effect.
- * Each passed vertex is an in-out parameter that initially contains the
- * position of the vertex and should be modified according to a specific
- * deformation algorithm.</para>
- * </refsect2>
- *
* #ClutterDeformEffect is available since Clutter 1.4
+ *
+ * ## Implementing ClutterDeformEffect
+ *
+ * Sub-classes of #ClutterDeformEffect should override the
+ * #ClutterDeformEffectClass.deform_vertex() virtual function; this function
+ * is called on every vertex that needs to be deformed by the effect.
+ * Each passed vertex is an in-out parameter that initially contains the
+ * position of the vertex and should be modified according to a specific
+ * deformation algorithm.
*/
#ifdef HAVE_CONFIG_H
diff --git a/clutter/clutter-drag-action.c b/clutter/clutter-drag-action.c
index c805453..1314522 100644
--- a/clutter/clutter-drag-action.c
+++ b/clutter/clutter-drag-action.c
@@ -34,7 +34,7 @@
* a #ClutterActor and setting it as reactive; for instance, the following
* code:
*
- * |[
+ * |[<!-- language="C" -->
* clutter_actor_add_action (actor, clutter_drag_action_new ());
* clutter_actor_set_reactive (actor, TRUE);
* ]|
@@ -54,19 +54,11 @@
* parented and exist between the emission of #ClutterDragAction::drag-begin
* and #ClutterDragAction::drag-end.
*
- * <example id="drag-action-example">
- * <title>A simple draggable actor</title>
- * <programlisting>
- * <xi:include xmlns:xi="http://www.w3.org/2001/XInclude"; parse="text"
href="../../../../examples/drag-action.c">
- * <xi:fallback>FIXME: MISSING XINCLUDE CONTENT</xi:fallback>
- * </xi:include>
- * </programlisting>
- * <para>The example program above allows dragging the rectangle around
- * the stage using a #ClutterDragAction. When pressing the
- * <keycap>Shift</keycap> key the actor that is going to be dragged is a
- * separate rectangle, and when the drag ends, the original rectangle will
- * be animated to the final coordinates.</para>
- * </example>
+ * The [drag-action example](https://git.gnome.org/browse/clutter/tree/examples/drag-action.c?h=clutter-1.18)
+ * allows dragging the rectangle around the stage using a #ClutterDragAction.
+ * When pressing the `Shift` key the actor that is being dragged will be a
+ * separate rectangle, and when the drag ends, the original rectangle will be
+ * animated to the final drop coordinates.
*
* #ClutterDragAction is available since Clutter 1.4
*/
diff --git a/clutter/clutter-drop-action.c b/clutter/clutter-drop-action.c
index 7f71ae3..a1a99fb 100644
--- a/clutter/clutter-drop-action.c
+++ b/clutter/clutter-drop-action.c
@@ -36,7 +36,7 @@
* #ClutterDropAction::drop signal and handling the drop from there,
* for instance:
*
- * |[
+ * |[<!-- language="C" -->
* ClutterAction *action = clutter_drop_action ();
*
* g_signal_connect (action, "drop", G_CALLBACK (on_drop), NULL);
@@ -49,18 +49,12 @@
* cause the #ClutterDropAction::drop signal to be skipped when the input
* device button is released.
*
- * <example id="drop-action-example">
- * <title>Drop targets</title>
- * <programlisting>
- * <xi:include xmlns:xi="http://www.w3.org/2001/XInclude"; parse="text"
href="../../../../examples/drop-action.c">
- * <xi:fallback>FIXME: MISSING XINCLUDE CONTENT</xi:fallback>
- * </xi:include>
- * </programlisting>
- * </example>
- *
* It's important to note that #ClutterDropAction will only work with
* actors dragged using #ClutterDragAction.
*
+ * See [drop-action.c](https://git.gnome.org/browse/clutter/tree/examples/drop-action.c?h=clutter-1.18)
+ * for an example of how to use #ClutterDropAction.
+ *
* #ClutterDropAction is available since Clutter 1.8
*/
diff --git a/clutter/clutter-effect.c b/clutter/clutter-effect.c
index 8430a76..33d8f13 100644
--- a/clutter/clutter-effect.c
+++ b/clutter/clutter-effect.c
@@ -36,78 +36,50 @@
* actor without sub-classing the actor itself and overriding the
* #ClutterActorClass.paint()_ virtual function.
*
- * <refsect2 id="ClutterEffect-implementation">
- * <title>Implementing a ClutterEffect</title>
- * <para>
- * Creating a sub-class of #ClutterEffect requires overriding the
- * ‘paint’ method. The implementation of the function should look
- * something like this:
- * </para>
- * <programlisting>
+ * ## Implementing a ClutterEffect
+ *
+ * Creating a sub-class of #ClutterEffect requires overriding the
+ * #ClutterEffectClass.paint() method. The implementation of the function should look
+ * something like this:
+ *
+ * |[
* void effect_paint (ClutterEffect *effect, ClutterEffectPaintFlags flags)
* {
- * /* Set up initialisation of the paint such as binding a
- * CoglOffscreen or other operations */
+ * // Set up initialisation of the paint such as binding a
+ * // CoglOffscreen or other operations
*
- * /* Chain to the next item in the paint sequence. This will either call
- * ‘paint’ on the next effect or just paint the actor if this is
- * the last effect. */
+ * // Chain to the next item in the paint sequence. This will either call
+ * // ‘paint’ on the next effect or just paint the actor if this is
+ * // the last effect.
* ClutterActor *actor =
* clutter_actor_meta_get_actor (CLUTTER_ACTOR_META (effect));
+ *
* clutter_actor_continue_paint (actor);
*
- * /* perform any cleanup of state, such as popping the
- * CoglOffscreen */
+ * // perform any cleanup of state, such as popping the CoglOffscreen
* }
- * </programlisting>
- * <para>
- * The effect can optionally avoid calling
- * clutter_actor_continue_paint() to skip any further stages of
- * the paint sequence. This is useful for example if the effect
- * contains a cached image of the actor. In that case it can
- * optimise painting by avoiding the actor paint and instead
- * painting the cached image. The %CLUTTER_EFFECT_PAINT_ACTOR_DIRTY
- * flag is useful in this case. Clutter will set this flag when a
- * redraw has been queued on the actor since it was last
- * painted. The effect can use this information to decide if the
- * cached image is still valid.
- * </para>
- * <para>
- * The ‘paint’ virtual was added in Clutter 1.8. Prior to that there
- * were two separate functions as follows.
- * </para>
- * <itemizedlist>
- * <listitem><simpara><function>pre_paint()</function>, which is called
- * before painting the #ClutterActor.</simpara></listitem>
- * <listitem><simpara><function>post_paint()</function>, which is called
- * after painting the #ClutterActor.</simpara></listitem>
- * </itemizedlist>
- * <para>The <function>pre_paint()</function> function was used to set
- * up the #ClutterEffect right before the #ClutterActor's paint
- * sequence. This function can fail, and return %FALSE; in that case, no
- * <function>post_paint()</function> invocation will follow.</para>
- * <para>The <function>post_paint()</function> function was called after the
- * #ClutterActor's paint sequence.</para>
- * <para>
- * With these two functions it is not possible to skip the rest of
- * the paint sequence. The default implementation of the ‘paint’
- * virtual calls #ClutterEffectClass.pre_paint(), clutter_actor_continue_paint()
- * and then #ClutterEffectClass.post_paint() so that existing actors that aren't
- * using the #ClutterEffectClass.paint() virtual will continue to work. New
- * effects using the #ClutterEffectClass.paint() virtual do not need to implement
- * pre or post paint.
- * </para>
- * <example id="ClutterEffect-example">
- * <title>A simple ClutterEffect implementation</title>
- * <para>The example below creates two rectangles: one will be
- * painted "behind" the actor, while another will be painted "on
- * top" of the actor. The #ClutterActorMetaClass.set_actor()
- * implementation will create the two materials used for the two
- * different rectangles; the #ClutterEffectClass.paint() implementation
- * will paint the first material using cogl_rectangle(), before
- * continuing and then it will paint paint the second material
- * after.</para>
- * <programlisting>
+ * ]|
+ *
+ * The effect can optionally avoid calling clutter_actor_continue_paint() to skip any
+ * further stages of the paint sequence. This is useful for example if the effect
+ * contains a cached image of the actor. In that case it can optimise painting by
+ * avoiding the actor paint and instead painting the cached image.
+ *
+ * The %CLUTTER_EFFECT_PAINT_ACTOR_DIRTY flag is useful in this case. Clutter will set
+ * this flag when a redraw has been queued on the actor since it was last painted. The
+ * effect can use this information to decide if the cached image is still valid.
+ *
+ * ## A simple ClutterEffect implementation
+ *
+ * The example below creates two rectangles: one will be painted "behind" the actor,
+ * while another will be painted "on top" of the actor.
+ *
+ * The #ClutterActorMetaClass.set_actor() implementation will create the two materials
+ * used for the two different rectangles; the #ClutterEffectClass.paint() implementation
+ * will paint the first material using cogl_rectangle(), before continuing and then it
+ * will paint paint the second material after.
+ *
+ * |[
* typedef struct {
* ClutterEffect parent_instance;
*
@@ -125,35 +97,33 @@
* {
* MyEffect *self = MY_EFFECT (meta);
*
- * /* Clear the previous state */
- * if (self->rect_1)
+ * // Clear the previous state //
+ * if (self->rect_1)
* {
- * cogl_handle_unref (self->rect_1);
- * self->rect_1 = NULL;
+ * cogl_handle_unref (self->rect_1);
+ * self->rect_1 = NULL;
* }
*
- * if (self->rect_2)
+ * if (self->rect_2)
* {
- * cogl_handle_unref (self->rect_2);
- * self->rect_2 = NULL;
+ * cogl_handle_unref (self->rect_2);
+ * self->rect_2 = NULL;
* }
*
- * /* Maintain a pointer to the actor *
- * self->actor = actor;
+ * // Maintain a pointer to the actor
+ * self->actor = actor;
*
- * /* If we've been detached by the actor then we should
- * * just bail out here
- * */
- * if (self->actor == NULL)
+ * // If we've been detached by the actor then we should just bail out here
+ * if (self->actor == NULL)
* return;
*
- * /* Create a red material */
- * self->rect_1 = cogl_material_new ();
- * cogl_material_set_color4f (self->rect_1, 1.0, 0.0, 0.0, 1.0);
+ * // Create a red material
+ * self->rect_1 = cogl_material_new ();
+ * cogl_material_set_color4f (self->rect_1, 1.0, 0.0, 0.0, 1.0);
*
- * /* Create a green material */
- * self->rect_2 = cogl_material_new ();
- * cogl_material_set_color4f (self->rect_2, 0.0, 1.0, 0.0, 1.0);
+ * // Create a green material
+ * self->rect_2 = cogl_material_new ();
+ * cogl_material_set_color4f (self->rect_2, 0.0, 1.0, 0.0, 1.0);
* }
*
* static gboolean
@@ -162,17 +132,17 @@
* MyEffect *self = MY_EFFECT (effect);
* gfloat width, height;
*
- * clutter_actor_get_size (self->actor, &width, &height);
+ * clutter_actor_get_size (self->actor, &width, &height);
*
- * /* Paint the first rectangle in the upper left quadrant */
- * cogl_set_source (self->rect_1);
+ * // Paint the first rectangle in the upper left quadrant
+ * cogl_set_source (self->rect_1);
* cogl_rectangle (0, 0, width / 2, height / 2);
*
- * /* Continue to the rest of the paint sequence */
- * clutter_actor_continue_paint (self->actor);
+ * // Continue to the rest of the paint sequence
+ * clutter_actor_continue_paint (self->actor);
*
- * /* Paint the second rectangle in the lower right quadrant */
- * cogl_set_source (self->rect_2);
+ * // Paint the second rectangle in the lower right quadrant
+ * cogl_set_source (self->rect_2);
* cogl_rectangle (width / 2, height / 2, width, height);
* }
*
@@ -181,13 +151,11 @@
* {
* ClutterActorMetaClas *meta_class = CLUTTER_ACTOR_META_CLASS (klass);
*
- * meta_class->set_actor = my_effect_set_actor;
+ * meta_class->set_actor = my_effect_set_actor;
*
- * klass->paint = my_effect_paint;
+ * klass->paint = my_effect_paint;
* }
- * </programlisting>
- * </example>
- * </refsect2>
+ * ]|
*
* #ClutterEffect is available since Clutter 1.4
*/
diff --git a/clutter/clutter-flow-layout.c b/clutter/clutter-flow-layout.c
index eb23b53..0645666 100644
--- a/clutter/clutter-flow-layout.c
+++ b/clutter/clutter-flow-layout.c
@@ -29,40 +29,25 @@
* #ClutterFlowLayout is a layout manager which implements the following
* policy:
*
- * <itemizedlist>
- * <listitem><para>the preferred natural size depends on the value
+ * - the preferred natural size depends on the value
* of the #ClutterFlowLayout:orientation property; the layout will try
* to maintain all its children on a single row or
- * column;</para></listitem>
- * <listitem><para>if either the width or the height allocated are
+ * column;
+ * - if either the width or the height allocated are
* smaller than the preferred ones, the layout will wrap; in this case,
* the preferred height or width, respectively, will take into account
- * the amount of columns and rows;</para></listitem>
- * <listitem><para>each line (either column or row) in reflowing will
+ * the amount of columns and rows;
+ * - each line (either column or row) in reflowing will
* have the size of the biggest cell on that line; if the
* #ClutterFlowLayout:homogeneous property is set to %FALSE the actor
* will be allocated within that area, and if set to %TRUE instead the
- * actor will be given exactly that area;</para></listitem>
- * <listitem><para>the size of the columns or rows can be controlled
+ * actor will be given exactly that area;
+ * - the size of the columns or rows can be controlled
* for both minimum and maximum; the spacing can also be controlled
- * in both columns and rows.</para></listitem>
- * </itemizedlist>
+ * in both columns and rows.
*
- * <figure id="flow-layout-image">
- * <title>Horizontal flow layout</title>
- * <para>The image shows a #ClutterFlowLayout with the
- * #ClutterFlowLayout:orientation propert set to
- * %CLUTTER_FLOW_HORIZONTAL.</para>
- * <graphic fileref="flow-layout.png" format="PNG"/>
- * </figure>
- *
- * <informalexample>
- * <programlisting>
- * <xi:include xmlns:xi="http://www.w3.org/2001/XInclude"; parse="text"
href="../../../../examples/flow-layout.c">
- * <xi:fallback>FIXME: MISSING XINCLUDE CONTENT</xi:fallback>
- * </xi:include>
- * </programlisting>
- * </informalexample>
+ * The [flow-layout example](https://git.gnome.org/browse/clutter/tree/examples/flow-layout.c?h=clutter-1.18)
+ * shows how to use the #ClutterFlowLayout.
*
* #ClutterFlowLayout is available since Clutter 1.2
*/
diff --git a/clutter/clutter-gesture-action.c b/clutter/clutter-gesture-action.c
index 35019a7..179905e 100644
--- a/clutter/clutter-gesture-action.c
+++ b/clutter/clutter-gesture-action.c
@@ -38,7 +38,7 @@
* To use #ClutterGestureAction you just need to apply it to a #ClutterActor
* using clutter_actor_add_action() and connect to the signals:
*
- * |[
+ * |[<!-- language="C" -->
* ClutterAction *action = clutter_gesture_action_new ();
*
* clutter_actor_add_action (actor, action);
@@ -48,37 +48,37 @@
* g_signal_connect (action, "gesture-end", G_CALLBACK (on_gesture_end), NULL);
* ]|
*
- * <refsect2 id="creating-gesture-action">
- * <title>Creating Gesture actions</title>
- * <para>A #ClutterGestureAction provides four separate states that can be
- * used to recognize or ignore gestures when writing a new action class:</para>
- * <informalexample><programlisting><![CDATA[
- Prepare -> Cancel
- Prepare -> Begin -> Cancel
- Prepare -> Begin -> End
- Prepare -> Begin -> Progress -> Cancel
- Prepare -> Begin -> Progress -> End
- * ]]>
- * </programlisting></informalexample>
- * <para>Each #ClutterGestureAction starts in the "prepare" state, and calls
- * the #ClutterGestureActionClass.gesture_prepare() virtual function; this
- * state can be used to reset the internal state of a #ClutterGestureAction
- * subclass, but it can also immediately cancel a gesture without going
- * through the rest of the states.</para>
- * <para>The "begin" state follows the "prepare" state, and calls the
- * #ClutterGestureActionClass.gesture_begin() virtual function. This state
- * signals the start of a gesture recognizing process. From the "begin" state
- * the gesture recognition process can successfully end, by going to the
- * "end" state; it can continue in the "progress" state, in case of a
- * continuous gesture; or it can be terminated, by moving to the "cancel"
- * state.</para>
- * <para>In case of continuous gestures, the #ClutterGestureAction will use
- * the "progress" state, calling the #ClutterGestureActionClass.gesture_progress()
- * virtual function; the "progress" state will continue until the end of the
- * gesture, in which case the "end" state will be reached, or until the
- * gesture is cancelled, in which case the "cancel" gesture will be used
- * instead.</para>
- * </refsect2>
+ * ## Creating Gesture actions
+ *
+ * A #ClutterGestureAction provides four separate states that can be
+ * used to recognize or ignore gestures when writing a new action class:
+ *
+ * - Prepare -> Cancel
+ * - Prepare -> Begin -> Cancel
+ * - Prepare -> Begin -> End
+ * - Prepare -> Begin -> Progress -> Cancel
+ * - Prepare -> Begin -> Progress -> End
+ *
+ * Each #ClutterGestureAction starts in the "prepare" state, and calls
+ * the #ClutterGestureActionClass.gesture_prepare() virtual function; this
+ * state can be used to reset the internal state of a #ClutterGestureAction
+ * subclass, but it can also immediately cancel a gesture without going
+ * through the rest of the states.
+ *
+ * The "begin" state follows the "prepare" state, and calls the
+ * #ClutterGestureActionClass.gesture_begin() virtual function. This state
+ * signals the start of a gesture recognizing process. From the "begin" state
+ * the gesture recognition process can successfully end, by going to the
+ * "end" state; it can continue in the "progress" state, in case of a
+ * continuous gesture; or it can be terminated, by moving to the "cancel"
+ * state.
+ *
+ * In case of continuous gestures, the #ClutterGestureAction will use
+ * the "progress" state, calling the #ClutterGestureActionClass.gesture_progress()
+ * virtual function; the "progress" state will continue until the end of the
+ * gesture, in which case the "end" state will be reached, or until the
+ * gesture is cancelled, in which case the "cancel" gesture will be used
+ * instead.
*
* Since: 1.8
*/
diff --git a/clutter/clutter-image.c b/clutter/clutter-image.c
index 96dba91..c494767 100644
--- a/clutter/clutter-image.c
+++ b/clutter/clutter-image.c
@@ -28,13 +28,10 @@
* @Short_Description: Image data content
*
* #ClutterImage is a #ClutterContent implementation that displays
- * image data.
+ * image data inside a #ClutterActor.
*
- * <informalexample><programlisting>
- * <xi:include xmlns:xi="http://www.w3.org/2001/XInclude"; parse="text"
href="../../../../examples/image-content.c">
- * <xi:fallback>FIXME: MISSING XINCLUDE CONTENT</xi:fallback>
- * </xi:include>
- * </programlisting></informalexample>
+ * See [image.c](https://git.gnome.org/browse/clutter/tree/examples/image.c?h=clutter-1.18)
+ * for an example of how to use #ClutterImage.
*
* #ClutterImage is available since Clutter 1.10.
*/
diff --git a/clutter/clutter-input-device.c b/clutter/clutter-input-device.c
index 6fe05b0..9b05453 100644
--- a/clutter/clutter-input-device.c
+++ b/clutter/clutter-input-device.c
@@ -1036,9 +1036,9 @@ clutter_input_device_get_device_mode (ClutterInputDevice *device)
* |[
* ClutterEvent c_event;
*
- * translate_native_event_to_clutter (native_event, &c_event);
+ * translate_native_event_to_clutter (native_event, &c_event);
*
- * clutter_do_event (&c_event);
+ * clutter_do_event (&c_event);
* ]|
*
* Before letting clutter_do_event() process the event, it is necessary to call
@@ -1049,20 +1049,18 @@ clutter_input_device_get_device_mode (ClutterInputDevice *device)
* ClutterDeviceManager *manager;
* ClutterInputDevice *device;
*
- * translate_native_event_to_clutter (native_event, &c_event);
+ * translate_native_event_to_clutter (native_event, &c_event);
*
- * /* get the device manager */
+ * // get the device manager
* manager = clutter_device_manager_get_default ();
*
- * /* use the default Core Pointer that Clutter
- * * backends register by default
- * */
+ * // use the default Core Pointer that Clutter backends register by default
* device = clutter_device_manager_get_core_device (manager, %CLUTTER_POINTER_DEVICE);
*
- * /* update the state of the input device */
- * clutter_input_device_update_from_event (device, &c_event, FALSE);
+ * // update the state of the input device
+ * clutter_input_device_update_from_event (device, &c_event, FALSE);
*
- * clutter_do_event (&c_event);
+ * clutter_do_event (&c_event);
* ]|
*
* The @update_stage boolean argument should be used when the input device
@@ -1272,7 +1270,7 @@ clutter_input_device_get_axis (ClutterInputDevice *device,
*
* clutter_input_device_get_axis_value (device, axes,
* CLUTTER_INPUT_AXIS_PRESSURE,
- * &pressure_value);
+ * &pressure_value);
* ]|
*
* Return value: %TRUE if the value was set, and %FALSE otherwise
diff --git a/clutter/clutter-layout-manager.c b/clutter/clutter-layout-manager.c
index e1bce2e..3b731c9 100644
--- a/clutter/clutter-layout-manager.c
+++ b/clutter/clutter-layout-manager.c
@@ -38,227 +38,36 @@
* Clutter provides some simple #ClutterLayoutManager sub-classes, like
* #ClutterFlowLayout and #ClutterBinLayout.
*
- * <refsect2 id="ClutterLayoutManager-use-in-Actor">
- * <title>Using a Layout Manager inside an Actor</title>
- * <para>In order to use a #ClutterLayoutManager inside a #ClutterActor
- * sub-class you should invoke clutter_layout_manager_get_preferred_width()
- * inside the #ClutterActorClass.get_preferred_width() virtual function and
- * clutter_layout_manager_get_preferred_height() inside the
- * #ClutterActorClass.get_preferred_height() virtual functions implementation.
- * You should also call clutter_layout_manager_allocate() inside the
- * implementation of the #ClutterActorClass.allocate() virtual function.</para>
- * <para>In order to receive notifications for changes in the layout
- * manager policies you should also connect to the
- * #ClutterLayoutManager::layout-changed signal and queue a relayout
- * on your actor. The following code should be enough if the actor
- * does not need to perform specific operations whenever a layout
- * manager changes:</para>
- * <informalexample><programlisting>
- * g_signal_connect_swapped (layout_manager,
- * "layout-changed",
- * G_CALLBACK (clutter_actor_queue_relayout),
- * actor);
- * </programlisting></informalexample>
- * </refsect2>
- *
- * <refsect2 id="ClutterLayoutManager-implementation">
- * <title>Implementing a ClutterLayoutManager</title>
- * <para>The implementation of a layout manager does not differ from
- * the implementation of the size requisition and allocation bits of
- * #ClutterActor, so you should read the relative documentation
- * <link linkend="clutter-subclassing-ClutterActor">for subclassing
- * ClutterActor</link>.</para>
- * <para>The layout manager implementation can hold a back pointer
- * to the #ClutterContainer by implementing the
- * <function>set_container()</function> virtual function. The layout manager
- * should not hold a real reference (i.e. call g_object_ref()) on the
- * container actor, to avoid reference cycles.</para>
- * <para>If a layout manager has properties affecting the layout
- * policies then it should emit the #ClutterLayoutManager::layout-changed
- * signal on itself by using the clutter_layout_manager_layout_changed()
- * function whenever one of these properties changes.</para>
- * </refsect2>
- *
- * <refsect2 id="ClutterLayoutManager-animation">
- * <title>Animating a ClutterLayoutManager</title>
- * <para>A layout manager is used to let a #ClutterContainer take complete
- * ownership over the layout (that is: the position and sizing) of its
- * children; this means that using the Clutter animation API, like
- * clutter_actor_animate(), to animate the position and sizing of a child of
- * a layout manager it is not going to work properly, as the animation will
- * automatically override any setting done by the layout manager
- * itself.</para>
- * <para>It is possible for a #ClutterLayoutManager sub-class to animate its
- * children layout by using the base class animation support. The
- * #ClutterLayoutManager animation support consists of three virtual
- * functions: #ClutterLayoutManagerClass.begin_animation(),
- * #ClutterLayoutManagerClass.get_animation_progress(), and
- * #ClutterLayoutManagerClass.end_animation().</para>
- * <variablelist>
- * <varlistentry>
- * <term><function>begin_animation (duration, easing)</function></term>
- * <listitem><para>This virtual function is invoked when the layout
- * manager should begin an animation. The implementation should set up
- * the state for the animation and create the ancillary objects for
- * animating the layout. The default implementation creates a
- * #ClutterTimeline for the given duration and a #ClutterAlpha binding
- * the timeline to the given easing mode. This function returns a
- * #ClutterAlpha which should be used to control the animation from
- * the caller perspective.</para></listitem>
- * </varlistentry>
- * <varlistentry>
- * <term><function>get_animation_progress()</function></term>
- * <listitem><para>This virtual function should be invoked when animating
- * a layout manager. It returns the progress of the animation, using the
- * same semantics as the #ClutterAlpha:alpha value.</para></listitem>
- * </varlistentry>
- * <varlistentry>
- * <term><function>end_animation()</function></term>
- * <listitem><para>This virtual function is invoked when the animation of
- * a layout manager ends, and it is meant to be used for bookkeeping the
- * objects created in the <function>begin_animation()</function>
- * function. The default implementation will call it implicitly when the
- * timeline is complete.</para></listitem>
- * </varlistentry>
- * </variablelist>
- * <para>The simplest way to animate a layout is to create a #ClutterTimeline
- * inside the <function>begin_animation()</function> virtual function, along
- * with a #ClutterAlpha, and for each #ClutterTimeline::new-frame signal
- * emission call clutter_layout_manager_layout_changed(), which will cause a
- * relayout. The #ClutterTimeline::completed signal emission should cause
- * clutter_layout_manager_end_animation() to be called. The default
- * implementation provided internally by #ClutterLayoutManager does exactly
- * this, so most sub-classes should either not override any animation-related
- * virtual function or simply override #ClutterLayoutManagerClass.begin_animation()
- * and #ClutterLayoutManagerClass.end_animation() to set up ad hoc state, and then
- * chain up to the parent's implementation.</para>
- * <example id="example-ClutterLayoutManager-animation">
- * <title>Animation of a Layout Manager</title>
- * <para>The code below shows how a #ClutterLayoutManager sub-class should
- * provide animating the allocation of its children from within the
- * #ClutterLayoutManagerClass.allocate() virtual function implementation. The
- * animation is computed between the last stable allocation performed
- * before the animation started and the desired final allocation.</para>
- * <para>The <varname>is_animating</varname> variable is stored inside the
- * #ClutterLayoutManager sub-class and it is updated by overriding the
- * #ClutterLayoutManagerClass.begin_animation() and the
- * #ClutterLayoutManagerClass.end_animation() virtual functions and chaining up
- * to the base class implementation.</para>
- * <para>The last stable allocation is stored within a #ClutterLayoutMeta
- * sub-class used by the implementation.</para>
- * <programlisting>
- * static void
- * my_layout_manager_allocate (ClutterLayoutManager *manager,
- * ClutterContainer *container,
- * const ClutterActorBox *allocation,
- * ClutterAllocationFlags flags)
- * {
- * MyLayoutManager *self = MY_LAYOUT_MANAGER (manager);
- * ClutterActor *child;
- *
- * for (child = clutter_actor_get_first_child (CLUTTER_ACTOR (container));
- * child != NULL;
- * child = clutter_actor_get_next_sibling (child))
- * {
- * ClutterLayoutMeta *meta;
- * MyLayoutMeta *my_meta;
- *
- * /* retrieve the layout meta-object */
- * meta = clutter_layout_manager_get_child_meta (manager,
- * container,
- * child);
- * my_meta = MY_LAYOUT_META (meta);
- *
- * /* compute the desired allocation for the child */
- * compute_allocation (self, my_meta, child,
- * allocation, flags,
- * &child_box);
- *
- * /* this is the additional code that deals with the animation
- * * of the layout manager
- * */
- * if (!self->is_animating)
- * {
- * /* store the last stable allocation for later use */
- * my_meta->last_alloc = clutter_actor_box_copy (&child_box);
- * }
- * else
- * {
- * ClutterActorBox end = { 0, };
- * gdouble p;
- *
- * /* get the progress of the animation */
- * p = clutter_layout_manager_get_animation_progress (manager);
- *
- * if (my_meta->last_alloc != NULL)
- * {
- * /* copy the desired allocation as the final state */
- * end = child_box;
- *
- * /* then interpolate the initial and final state
- * * depending on the progress of the animation,
- * * and put the result inside the box we will use
- * * to allocate the child
- * */
- * clutter_actor_box_interpolate (my_meta->last_alloc,
- * &end,
- * p,
- * &child_box);
- * }
- * else
- * {
- * /* if there is no stable allocation then the child was
- * * added while animating; one possible course of action
- * * is to just bail out and fall through to the allocation
- * * to position the child directly at its final state
- * */
- * my_meta->last_alloc =
- * clutter_actor_box_copy (&child_box);
- * }
- * }
- *
- * /* allocate the child */
- * clutter_actor_allocate (child, &child_box, flags);
- * }
- * }
- * </programlisting>
- * </example>
- * <para>Sub-classes of #ClutterLayoutManager that support animations of the
- * layout changes should call clutter_layout_manager_begin_animation()
- * whenever a layout property changes value, e.g.:</para>
- * <informalexample>
- * <programlisting>
- * if (self->orientation != new_orientation)
- * {
- * ClutterLayoutManager *manager;
- *
- * self->orientation = new_orientation;
- *
- * manager = CLUTTER_LAYOUT_MANAGER (self);
- * clutter_layout_manager_layout_changed (manager);
- * clutter_layout_manager_begin_animation (manager, 500, CLUTTER_LINEAR);
- *
- * g_object_notify (G_OBJECT (self), "orientation");
- * }
- * </programlisting>
- * </informalexample>
- * <para>The code above will animate a change in the
- * <varname>orientation</varname> layout property of a layout manager.</para>
- * </refsect2>
- *
- * <refsect2 id="clutter-layout-properties">
- * <title>Layout Properties</title>
- * <para>If a layout manager has layout properties, that is properties that
- * should exist only as the result of the presence of a specific (layout
- * manager, container actor, child actor) combination, and it wishes to store
- * those properties inside a #ClutterLayoutMeta, then it should override the
- * #ClutterLayoutManagerClass.get_child_meta_type() virtual function to return
- * the #GType of the #ClutterLayoutMeta sub-class used to store the layout
- * properties; optionally, the #ClutterLayoutManager sub-class might also
- * override the #ClutterLayoutManagerClass.create_child_meta() virtual function
- * to control how the #ClutterLayoutMeta instance is created, otherwise the
- * default implementation will be equivalent to:</para>
- * <informalexample><programlisting>
+ * ## Implementing a ClutterLayoutManager
+ * The implementation of a layout manager does not differ from the
+ * implementation of the size requisition and allocation bits of
+ * #ClutterActor, so you should read the relative documentation
+ * forr subclassing #ClutterActor.
+ *
+ * The layout manager implementation can hold a back pointer to the
+ * #ClutterContainer by implementing the #ClutterLayoutManagerClass.set_container()
+ * virtual function. The layout manager should not hold a real reference (i.e.
+ * call g_object_ref()) on the container actor, to avoid reference cycles.
+ *
+ * If a layout manager has properties affecting the layout policies then it should
+ * emit the #ClutterLayoutManager::layout-changed signal on itself by using the
+ * clutter_layout_manager_layout_changed() function whenever one of these properties
+ * changes.
+ *
+ * ## Layout Properties
+ *
+ * If a layout manager has layout properties, that is properties that
+ * should exist only as the result of the presence of a specific (layout
+ * manager, container actor, child actor) combination, and it wishes to store
+ * those properties inside a #ClutterLayoutMeta, then it should override the
+ * #ClutterLayoutManagerClass.get_child_meta_type() virtual function to return
+ * the #GType of the #ClutterLayoutMeta sub-class used to store the layout
+ * properties; optionally, the #ClutterLayoutManager sub-class might also
+ * override the #ClutterLayoutManagerClass.create_child_meta() virtual function
+ * to control how the #ClutterLayoutMeta instance is created, otherwise the
+ * default implementation will be equivalent to:
+ *
+ * |[
* ClutterLayoutManagerClass *klass;
* GType meta_type;
*
@@ -270,22 +79,23 @@
* "container", container,
* "actor", actor,
* NULL);
- * </programlisting></informalexample>
- * <para>Where <varname>manager</varname> is the #ClutterLayoutManager,
- * <varname>container</varname> is the #ClutterContainer using the
- * #ClutterLayoutManager and <varname>actor</varname> is the #ClutterActor
- * child of the #ClutterContainer.</para>
- * </refsect2>
+ * ]|
+ *
+ * Where `manager` is the #ClutterLayoutManager, `container` is the
+ * #ClutterContainer using the #ClutterLayoutManager, and `actor` is
+ * the #ClutterActor child of the #ClutterContainer.
+ *
+ * ## Using ClutterLayoutManager with ClutterScript
+ *
+ * #ClutterLayoutManager instances can be created in the same way
+ * as other objects in #ClutterScript; properties can be set using the
+ * common syntax.
+ *
+ * Layout properties can be set on children of a container with
+ * a #ClutterLayoutManager using the `layout::` modifier on the property
+ * name, for instance:
*
- * <refsect2 id="clutter-layout-script">
- * <title>Using ClutterLayoutManager with ClutterScript</title>
- * <para>#ClutterLayoutManager instance can be created in the same way
- * as other objects in #ClutterScript; properties can be set using the
- * common syntax.</para>
- * <para>Layout properties can be set on children of a container with
- * a #ClutterLayoutManager using the <emphasis>layout::</emphasis>
- * modifier on the property name, for instance:</para>
- * <informalexample><programlisting>
+ * |[
* {
* "type" : "ClutterBox",
* "layout-manager" : { "type" : "ClutterTableLayout" },
@@ -314,8 +124,7 @@
* }
* ]
* }
- * </programlisting></informalexample>
- * </refsect2>
+ * ]|
*
* #ClutterLayoutManager is available since Clutter 1.2
*/
diff --git a/clutter/clutter-main.c b/clutter/clutter-main.c
index bfa1dd0..04834d3 100644
--- a/clutter/clutter-main.c
+++ b/clutter/clutter-main.c
@@ -23,70 +23,28 @@
/**
* SECTION:clutter-main
- * @short_description: Various 'global' clutter functions.
+ * @short_description: Various 'global' Clutter functions.
*
* Functions to retrieve various global Clutter resources and other utility
* functions for mainloops, events and threads
*
- * <refsect2 id="clutter-Threading-Model">
- * <title>Threading Model</title>
- * <para>Clutter is <emphasis>thread-aware</emphasis>: all operations
- * performed by Clutter are assumed to be under the big Clutter lock,
- * which is created when the threading is initialized through
- * clutter_init().</para>
- * <example id="example-Thread-Init">
- * <title>Thread Initialization</title>
- * <para>The code below shows how to correctly initialize Clutter
- * in a multi-threaded environment. These operations are mandatory for
- * applications that wish to use threads with Clutter.</para>
- * <programlisting>
- * int
- * main (int argc, char *argv[])
- * {
- * /* initialize Clutter */
- * clutter_init (&argc, &argv);
- *
- * /* program code */
+ * ## The Clutter Threading Model
*
- * /* acquire the main lock */
- * clutter_threads_enter ();
+ * Clutter is *thread-aware*: all operations performed by Clutter are assumed
+ * to be under the Big Clutter Lock, which is created when the threading is
+ * initialized through clutter_init(), and entered when calling user-related
+ * code during event handling and actor drawing.
*
- * /* start the main loop */
- * clutter_main ();
+ * The only safe and portable way to use the Clutter API in a multi-threaded
+ * environment is to only access the Clutter API from a thread that did called
+ * clutter_init() and clutter_main().
*
- * /* release the main lock */
- * clutter_threads_leave ();
+ * The common pattern for using threads with Clutter is to use worker threads
+ * to perform blocking operations and then install idle or timeout sources with
+ * the result when the thread finishes, and update the UI from those callbacks.
*
- * /* clean up */
- * return 0;
- * }
- * </programlisting>
- * </example>
- * <para>This threading model has the caveat that it is only safe to call
- * Clutter's API when the lock has been acquired — which happens
- * between pairs of clutter_threads_enter() and clutter_threads_leave()
- * calls.</para>
- * <para>The only safe and portable way to use the Clutter API in a
- * multi-threaded environment is to never access the API from a thread that
- * did not call clutter_init() and clutter_main().</para>
- * <para>The common pattern for using threads with Clutter is to use worker
- * threads to perform blocking operations and then install idle or timeout
- * sources with the result when the thread finished.</para>
- * <para>Clutter provides thread-aware variants of g_idle_add() and
- * g_timeout_add() that acquire the Clutter lock before invoking the provided
- * callback: clutter_threads_add_idle() and
- * clutter_threads_add_timeout().</para>
- * <para>The example below shows how to use a worker thread to perform a
- * blocking operation, and perform UI updates using the main loop.</para>
- * <example id="worker-thread-example">
- * <title>A worker thread example</title>
- * <programlisting>
- * <xi:include xmlns:xi="http://www.w3.org/2001/XInclude"; parse="text" href="../../../../examples/threads.c">
- * <xi:fallback>FIXME: MISSING XINCLUDE CONTENT</xi:fallback>
- * </xi:include>
- * </programlisting>
- * </example>
- * </refsect2>
+ * For a working example of how to use a worker thread to update the UI, see
+ * [threads.c](https://git.gnome.org/browse/clutter/tree/examples/threads.c?h=clutter-1.18)
*/
#ifdef HAVE_CONFIG_H
@@ -556,12 +514,10 @@ clutter_redraw (ClutterStage *stage)
* all #ClutterStage<!-- -->s managed by Clutter.
*
* If @enable is %FALSE the following events will not work:
- * <itemizedlist>
- * <listitem><para>ClutterActor::motion-event, unless on the
- * #ClutterStage</para></listitem>
- * <listitem><para>ClutterActor::enter-event</para></listitem>
- * <listitem><para>ClutterActor::leave-event</para></listitem>
- * </itemizedlist>
+ *
+ * - ClutterActor::motion-event, except on the #ClutterStage
+ * - ClutterActor::enter-event
+ * - ClutterActor::leave-event
*
* Since: 0.6
*
@@ -1110,13 +1066,13 @@ _clutter_threads_dispatch_free (gpointer data)
* SafeClosure *closure = data;
* gboolean res = FALSE;
*
- * /* mark the critical section */
+ * // mark the critical section //
*
* clutter_threads_enter();
*
- * /* the callback does not need to acquire the Clutter
- * * lock itself, as it is held by the this proxy handler
- * */
+ * // the callback does not need to acquire the Clutter
+ * / lock itself, as it is held by the this proxy handler
+ * //
* res = closure->callback (closure->data);
*
* clutter_threads_leave();
@@ -1129,8 +1085,8 @@ _clutter_threads_dispatch_free (gpointer data)
* {
* SafeClosure *closure = g_new0 (SafeClosure, 1);
*
- * closure->callback = callback;
- * closure->data = data;
+ * closure->callback = callback;
+ * closure->data = data;
*
* return g_idle_add_full (G_PRIORITY_DEFAULT_IDLE,
* idle_safe_callback,
@@ -1151,24 +1107,24 @@ _clutter_threads_dispatch_free (gpointer data)
* {
* SomeClosure *closure = data;
*
- * /* it is safe to call Clutter API from this function because
- * * it is invoked from the same thread that started the main
- * * loop and under the Clutter thread lock
- * */
- * clutter_label_set_text (CLUTTER_LABEL (closure->label),
- * closure->text);
+ * // it is safe to call Clutter API from this function because
+ * / it is invoked from the same thread that started the main
+ * / loop and under the Clutter thread lock
+ * //
+ * clutter_label_set_text (CLUTTER_LABEL (closure->label),
+ * closure->text);
*
- * g_object_unref (closure->label);
+ * g_object_unref (closure->label);
* g_free (closure);
*
* return FALSE;
* }
*
- * /* within another thread */
+ * // within another thread //
* closure = g_new0 (SomeClosure, 1);
- * /* always take a reference on GObject instances */
- * closure->label = g_object_ref (my_application->label);
- * closure->text = g_strdup (processed_text_to_update_the_label);
+ * // always take a reference on GObject instances //
+ * closure->label = g_object_ref (my_application->label);
+ * closure->text = g_strdup (processed_text_to_update_the_label);
*
* clutter_threads_add_idle_full (G_PRIORITY_HIGH_IDLE,
* update_ui,
@@ -1809,13 +1765,13 @@ post_parse_hook (GOptionContext *context,
*
* |[
* g_option_context_set_main_group (context, clutter_get_option_group ());
- * res = g_option_context_parse (context, &argc, &argc, NULL);
+ * res = g_option_context_parse (context, &argc, &argc, NULL);
* ]|
*
* is functionally equivalent to:
*
* |[
- * clutter_init (&argc, &argv);
+ * clutter_init (&argc, &argv);
* ]|
*
* After g_option_context_parse() on a #GOptionContext containing the
@@ -1865,7 +1821,7 @@ clutter_get_option_group (void)
* the #GOptionGroup returned by this function requires a subsequent explicit
* call to clutter_init(); use this function when needing to set foreign
* display connection with clutter_x11_set_display(), or with
- * <function>gtk_clutter_init()</function>.
+ * `gtk_clutter_init()`.
*
* Return value: (transfer full): a #GOptionGroup for the commandline arguments
* recognized by Clutter
@@ -2050,12 +2006,12 @@ clutter_parse_args (int *argc,
*
* It is safe to call this function multiple times.
*
- * <note>This function will not abort in case of errors during
+ * This function will not abort in case of errors during
* initialization; clutter_init() will print out the error message on
* stderr, and will return an error code. It is up to the application
* code to handle this case. If you need to display the error message
* yourself, you can use clutter_init_with_args(), which takes a #GError
- * pointer.</note>
+ * pointer.
*
* If this function fails, and returns an error code, any subsequent
* Clutter API will have undefined behaviour - including segmentation
@@ -2919,10 +2875,10 @@ on_grab_actor_destroy (ClutterActor *actor,
* the event delivery chain. The source set in the event will be the actor
* that would have received the event if the pointer grab was not in effect.
*
- * <note><para>Grabs completely override the entire event delivery chain
+ * Grabs completely override the entire event delivery chain
* done by Clutter. Pointer grabs should only be used as a last resource;
* using the #ClutterActor::captured-event signal should always be the
- * preferred way to intercept event delivery to reactive actors.</para></note>
+ * preferred way to intercept event delivery to reactive actors.
*
* This function should rarely be used.
*
@@ -3878,20 +3834,20 @@ _clutter_context_get_motion_events_enabled (void)
* windowing system; for instance:
*
* |[
- * #ifdef CLUTTER_WINDOWING_X11
+ * #ifdef CLUTTER_WINDOWING_X11
* if (clutter_check_windowing_backend (CLUTTER_WINDOWING_X11))
* {
- * /* it is safe to use the clutter_x11_* API */
+ * // it is safe to use the clutter_x11_* API
* }
* else
- * #endif
- * #ifdef CLUTTER_WINDOWING_WIN32
+ * #endif
+ * #ifdef CLUTTER_WINDOWING_WIN32
* if (clutter_check_windowing_backend (CLUTTER_WINDOWING_WIN32))
* {
- * /* it is safe to use the clutter_win32_* API */
+ * // it is safe to use the clutter_win32_* API
* }
* else
- * #endif
+ * #endif
* g_error ("Unknown Clutter backend.");
* ]|
*
diff --git a/clutter/clutter-model.c b/clutter/clutter-model.c
index f43c545..28ed768 100644
--- a/clutter/clutter-model.c
+++ b/clutter/clutter-model.c
@@ -37,8 +37,11 @@
* The #ClutterModel class is a list model which can accept most GObject
* types as a column type.
*
- * Creating a simple clutter model:
- * <informalexample><programlisting>
+ * ## Creating a simple ClutterModel
+ *
+ * The example below shows how to create a simple list model.
+ *
+ * |[<!-- language="C" -->
* enum
* {
* COLUMN_INT,
@@ -51,10 +54,10 @@
* ClutterModel *model;
* gint i;
*
- * model = clutter_model_default_new (N_COLUMNS,
- * /<!-- -->* column type, column title *<!-- -->/
- * G_TYPE_INT, "my integers",
- * G_TYPE_STRING, "my strings");
+ * model = clutter_list_model_new (N_COLUMNS,
+ * // column type, title
+ * G_TYPE_INT, "my integers",
+ * G_TYPE_STRING, "my strings");
* for (i = 0; i < 10; i++)
* {
* gchar *string = g_strdup_printf ("String %d", i);
@@ -67,7 +70,9 @@
*
*
* }
- * </programlisting></informalexample>
+ * ]|
+ *
+ * ## Iterating through a ClutterModel
*
* Iterating through the model consists of retrieving a new #ClutterModelIter
* pointing to the starting row, and calling clutter_model_iter_next() or
@@ -79,8 +84,7 @@
* after the last row. In an empty sequence, the first and last iterators are
* the same.
*
- * Iterating a #ClutterModel:
- * <informalexample><programlisting>
+ * |[<!-- language="C" -->
* enum
* {
* COLUMN_INT,
@@ -93,10 +97,10 @@
* ClutterModel *model;
* ClutterModelIter *iter = NULL;
*
- * /<!-- -->* Fill the model *<!-- -->/
+ * // fill the model
* model = populate_model ();
*
- * /<!-- -->* Get the first iter *<!-- -->/
+ * // get the iterator for the first row in the model
* iter = clutter_model_get_first_iter (model);
* while (!clutter_model_iter_is_last (iter))
* {
@@ -105,32 +109,33 @@
* iter = clutter_model_iter_next (iter);
* }
*
- * /<!-- -->* Make sure to unref the iter *<!-- -->/
+ * // Make sure to unref the iter
* g_object_unref (iter);
* }
- * </programlisting></informalexample>
+ * ]|
*
* #ClutterModel is an abstract class. Clutter provides a list model
* implementation called #ClutterListModel which has been optimised
* for insertion and look up in sorted lists.
*
- * <refsect2 id="ClutterModel-script">
- * <title>ClutterModel custom properties for #ClutterScript</title>
- * <para>#ClutterModel defines a custom property "columns" for #ClutterScript
- * which allows defining the column names and types. It also defines a custom
- * "rows" property which allows filling the #ClutterModel with some
- * data.</para>
- * <example id="ClutterModel-script-example">
- * <title>Example of the "columns" and "rows" custom properties</title>
- * <para>The definition below will create a #ClutterListModel with three
- * columns: the first one with name "Name" and containing strings; the
- * second one with name "Score" and containing integers; the third one with
- * name "Icon" and containing #ClutterTexture<!-- -->s. The model is filled
- * with three rows. A row can be defined either with an array that holds
- * all columns of a row, or an object that holds "column-name" :
- * "column-value" pairs.
- * </para>
- * <programlisting>
+ * #ClutterModel is available since Clutter 0.6
+ *
+ * ## ClutterModel custom properties for ClutterScript
+ *
+ * #ClutterModel defines a custom property "columns" for #ClutterScript
+ * which allows defining the column names and types. It also defines a custom
+ * "rows" property which allows filling the #ClutterModel with some
+ * data.
+ *
+ * The definition below will create a #ClutterListModel with three
+ * columns: the first one with name "Name" and containing strings; the
+ * second one with name "Score" and containing integers; the third one with
+ * name "Icon" and containing #ClutterTextures. The model is filled
+ * with three rows. A row can be defined either with an array that holds
+ * all columns of a row, or an object that holds "column-name" :
+ * "column-value" pairs.
+ *
+ * |[
* {
* "type" : "ClutterListModel",
* "id" : "teams-model",
@@ -145,11 +150,6 @@
* { "Name" : "Team 3", "Icon" : "team3-icon-script-id" }
* ]
* }
- * </programlisting>
- * </example>
- * </refsect2>
- *
- * #ClutterModel is available since Clutter 0.6
*/
diff --git a/clutter/clutter-offscreen-effect.c b/clutter/clutter-offscreen-effect.c
index de71912..c308113 100644
--- a/clutter/clutter-offscreen-effect.c
+++ b/clutter/clutter-offscreen-effect.c
@@ -40,25 +40,26 @@
* offscreen framebuffer, the redirection and the final paint of the texture on
* the desired stage.
*
- * <refsect2 id="ClutterOffscreenEffect-implementing">
- * <title>Implementing a ClutterOffscreenEffect</title>
- * <para>Creating a sub-class of #ClutterOffscreenEffect requires, in case
- * of overriding the #ClutterEffect virtual functions, to chain up to the
- * #ClutterOffscreenEffect's implementation.</para>
- * <para>On top of the #ClutterEffect's virtual functions,
- * #ClutterOffscreenEffect also provides a #ClutterOffscreenEffectClass.paint_target()
- * function, which encapsulates the effective painting of the texture that
- * contains the result of the offscreen redirection.</para>
- * <para>The size of the target material is defined to be as big as the
- * transformed size of the #ClutterActor using the offscreen effect.
- * Sub-classes of #ClutterOffscreenEffect can change the texture creation
- * code to provide bigger textures by overriding the
- * #ClutterOffscreenEffectClass.create_texture() virtual function; no chain up
- * to the #ClutterOffscreenEffect implementation is required in this
- * case.</para>
- * </refsect2>
- *
* #ClutterOffscreenEffect is available since Clutter 1.4
+ *
+ * ## Implementing a ClutterOffscreenEffect
+ *
+ * Creating a sub-class of #ClutterOffscreenEffect requires, in case
+ * of overriding the #ClutterEffect virtual functions, to chain up to the
+ * #ClutterOffscreenEffect's implementation.
+ *
+ * On top of the #ClutterEffect's virtual functions,
+ * #ClutterOffscreenEffect also provides a #ClutterOffscreenEffectClass.paint_target()
+ * function, which encapsulates the effective painting of the texture that
+ * contains the result of the offscreen redirection.
+ *
+ * The size of the target material is defined to be as big as the
+ * transformed size of the #ClutterActor using the offscreen effect.
+ * Sub-classes of #ClutterOffscreenEffect can change the texture creation
+ * code to provide bigger textures by overriding the
+ * #ClutterOffscreenEffectClass.create_texture() virtual function; no chain up
+ * to the #ClutterOffscreenEffect implementation is required in this
+ * case.
*/
#ifdef HAVE_CONFIG_H
@@ -596,7 +597,7 @@ clutter_offscreen_effect_create_texture (ClutterOffscreenEffect *effect,
* paint the actor to which it has been applied.
*
* This function should only be called by #ClutterOffscreenEffect
- * implementations, from within the <function>paint_target()</function>
+ * implementations, from within the #ClutterOffscreenEffectClass.paint_target()
* virtual function.
*
* Return value: %TRUE if the offscreen buffer has a valid size,
@@ -638,7 +639,7 @@ clutter_offscreen_effect_get_target_size (ClutterOffscreenEffect *effect,
* paint the actor to which it has been applied.
*
* This function should only be called by #ClutterOffscreenEffect
- * implementations, from within the <function>paint_target()</function>
+ * implementations, from within the #ClutterOffscreenEffectClass.paint_target()
* virtual function.
*
* Return value: %TRUE if the offscreen buffer has a valid rectangle,
diff --git a/clutter/clutter-paint-volume.c b/clutter/clutter-paint-volume.c
index 9eeee1e..184e186 100644
--- a/clutter/clutter-paint-volume.c
+++ b/clutter/clutter-paint-volume.c
@@ -290,20 +290,21 @@ clutter_paint_volume_set_width (ClutterPaintVolume *pv,
* around the volume. It returns the size of that bounding box as
* measured along the x-axis.
*
- * <note><para>If, for example, clutter_actor_get_transformed_paint_volume()
+ * If, for example, clutter_actor_get_transformed_paint_volume()
* is used to transform a 2D child actor that is 100px wide, 100px
* high and 0px deep into container coordinates then the width might
* not simply be 100px if the child actor has a 3D rotation applied to
- * it.</para>
- * <para>Remember; after clutter_actor_get_transformed_paint_volume() is
+ * it.
+ *
+ * Remember: if clutter_actor_get_transformed_paint_volume() is
* used then a transformed child volume will be defined relative to the
- * ancestor container actor and so a 2D child actor
- * can have a 3D bounding volume.</para></note>
+ * ancestor container actor and so a 2D child actor can have a 3D
+ * bounding volume.
*
- * <note>There are no accuracy guarantees for the reported width,
- * except that it must always be >= to the true width. This is
- * because actors may report simple, loose fitting paint-volumes
- * for efficiency</note>
+ * There are no accuracy guarantees for the reported width,
+ * except that it must always be greater than, or equal to, the
+ * actor's width. This is because actors may report simple, loose
+ * fitting paint volumes for efficiency.
* Return value: the width, in units of @pv's local coordinate system.
*
@@ -381,20 +382,21 @@ clutter_paint_volume_set_height (ClutterPaintVolume *pv,
* around the volume. It returns the size of that bounding box as
* measured along the y-axis.
*
- * <note><para>If, for example, clutter_actor_get_transformed_paint_volume()
+ * If, for example, clutter_actor_get_transformed_paint_volume()
* is used to transform a 2D child actor that is 100px wide, 100px
* high and 0px deep into container coordinates then the height might
* not simply be 100px if the child actor has a 3D rotation applied to
- * it.</para>
- * <para>Remember; after clutter_actor_get_transformed_paint_volume() is
+ * it.
+ *
+ * Remember: if clutter_actor_get_transformed_paint_volume() is
* used then a transformed child volume will be defined relative to the
* ancestor container actor and so a 2D child actor
- * can have a 3D bounding volume.</para></note>
+ * can have a 3D bounding volume.
*
- * <note>There are no accuracy guarantees for the reported height,
- * except that it must always be >= to the true height. This is
- * because actors may report simple, loose fitting paint-volumes
- * for efficiency</note>
+ * There are no accuracy guarantees for the reported height,
+ * except that it must always be greater than, or equal to, the actor's
+ * height. This is because actors may report simple, loose fitting paint
+ * volumes for efficiency.
*
* Return value: the height, in units of @pv's local coordinate system.
*
@@ -473,20 +475,21 @@ clutter_paint_volume_set_depth (ClutterPaintVolume *pv,
* around the volume. It returns the size of that bounding box as
* measured along the z-axis.
*
- * <note><para>If, for example, clutter_actor_get_transformed_paint_volume()
+ * If, for example, clutter_actor_get_transformed_paint_volume()
* is used to transform a 2D child actor that is 100px wide, 100px
* high and 0px deep into container coordinates then the depth might
* not simply be 0px if the child actor has a 3D rotation applied to
- * it.</para>
- * <para>Remember; after clutter_actor_get_transformed_paint_volume() is
+ * it.
+ *
+ * Remember: if clutter_actor_get_transformed_paint_volume() is
* used then the transformed volume will be defined relative to the
* container actor and in container coordinates a 2D child actor
- * can have a 3D bounding volume.</para></note>
+ * can have a 3D bounding volume.
*
- * <note>There are no accuracy guarantees for the reported depth,
- * except that it must always be >= to the true depth. This is
- * because actors may report simple, loose fitting paint-volumes
- * for efficiency.</note>
+ * There are no accuracy guarantees for the reported depth,
+ * except that it must always be greater than, or equal to, the actor's
+ * depth. This is because actors may report simple, loose fitting paint
+ * volumes for efficiency.
*
* Return value: the depth, in units of @pv's local coordinate system.
*
@@ -521,8 +524,8 @@ clutter_paint_volume_get_depth (const ClutterPaintVolume *pv)
*
* Updates the geometry of @pv to encompass @pv and @another_pv.
*
- * <note>There are no guarantees about how precisely the two volumes
- * will be encompassed.</note>
+ * There are no guarantees about how precisely the two volumes
+ * will be unioned.
*
* Since: 1.6
*/
@@ -743,9 +746,10 @@ _clutter_paint_volume_complete (ClutterPaintVolume *pv)
* the paint volume into window coordinates before getting
* the 2D bounding box.
*
- * <note>The coordinates of the returned box are not clamped to
- * integer pixel values, if you need them to be clamped you can use
- * clutter_actor_box_clamp_to_pixel()</note>
+ * The coordinates of the returned box are not clamped to
+ * integer pixel values; if you need them to be rounded to the
+ * nearest integer pixel values, you can use the
+ * clutter_actor_box_clamp_to_pixel() function.
*
* Since: 1.6
*/
diff --git a/clutter/clutter-path.c b/clutter/clutter-path.c
index 23886fc..0ff7a21 100644
--- a/clutter/clutter-path.c
+++ b/clutter/clutter-path.c
@@ -33,32 +33,19 @@
* The path consists of a series of nodes. Each node is one of the
* following four types:
*
- * <variablelist>
- * <varlistentry><term>%CLUTTER_PATH_MOVE_TO</term>
- * <listitem><para>
- * Changes the position of the path to the given pair of
- * coordinates. This is usually used as the first node of a path to
- * mark the start position. If it is used in the middle of a path then
- * the path will be disjoint and the actor will appear to jump to the
- * new position when animated.
- * </para></listitem></varlistentry>
- * <varlistentry><term>%CLUTTER_PATH_LINE_TO</term>
- * <listitem><para>
- * Creates a straight line from the previous point to the given point.
- * </para></listitem></varlistentry>
- * <varlistentry><term>%CLUTTER_PATH_CURVE_TO</term>
- * <listitem><para>
- * Creates a bezier curve. The end of the last node is used as the
- * first control point and the three subsequent coordinates given in
- * the node as used as the other three.
- * </para></listitem></varlistentry>
- * <varlistentry><term>%CLUTTER_PATH_CLOSE</term>
- * <listitem><para>
- * Creates a straight line from the last node to the last
- * %CLUTTER_PATH_MOVE_TO node. This can be used to close a path so
- * that it will appear as a loop when animated.
- * </para></listitem></varlistentry>
- * </variablelist>
+ * - %CLUTTER_PATH_MOVE_TO, changes the position of the path to the
+ * given pair of coordinates. This is usually used as the first node
+ * of a path to mark the start position. If it is used in the middle
+ * of a path then the path will be disjoint and the actor will appear
+ * to jump to the new position when animated.
+ * - %CLUTTER_PATH_LINE_TO, creates a straight line from the previous
+ * point to the given point.
+ * - %CLUTTER_PATH_CURVE_TO, creates a bezier curve. The end of the
+ * last node is used as the first control point and the three
+ * subsequent coordinates given in the node as used as the other three.
+ * -%CLUTTER_PATH_CLOSE, creates a straight line from the last node to
+ * the last %CLUTTER_PATH_MOVE_TO node. This can be used to close a
+ * path so that it will appear as a loop when animated.
*
* The first three types have the corresponding relative versions
* %CLUTTER_PATH_REL_MOVE_TO, %CLUTTER_PATH_REL_LINE_TO and
@@ -711,24 +698,10 @@ clutter_path_add_nodes (ClutterPath *path,
* coordinates. The coordinates can be separated by spaces or a
* comma. The types are:
*
- * <variablelist>
- * <varlistentry><term>M</term>
- * <listitem><para>
- * Adds a %CLUTTER_PATH_MOVE_TO node. Takes one pair of coordinates.
- * </para></listitem></varlistentry>
- * <varlistentry><term>L</term>
- * <listitem><para>
- * Adds a %CLUTTER_PATH_LINE_TO node. Takes one pair of coordinates.
- * </para></listitem></varlistentry>
- * <varlistentry><term>C</term>
- * <listitem><para>
- * Adds a %CLUTTER_PATH_CURVE_TO node. Takes three pairs of coordinates.
- * </para></listitem></varlistentry>
- * <varlistentry><term>z</term>
- * <listitem><para>
- * Adds a %CLUTTER_PATH_CLOSE node. No coordinates are needed.
- * </para></listitem></varlistentry>
- * </variablelist>
+ * - `M`: Adds a %CLUTTER_PATH_MOVE_TO node. Takes one pair of coordinates.
+ * - `L`: Adds a %CLUTTER_PATH_LINE_TO node. Takes one pair of coordinates.
+ * - `C`: Adds a %CLUTTER_PATH_CURVE_TO node. Takes three pairs of coordinates.
+ * - `z`: Adds a %CLUTTER_PATH_CLOSE node. No coordinates are needed.
*
* The M, L and C commands can also be specified in lower case which
* means the coordinates are relative to the previous node.
@@ -736,11 +709,9 @@ clutter_path_add_nodes (ClutterPath *path,
* For example, to move an actor in a 100 by 100 pixel square centered
* on the point 300,300 you could use the following path:
*
- * <informalexample>
- * <programlisting>
+ * |[
* M 250,350 l 0 -100 L 350,250 l 0 100 z
- * </programlisting>
- * </informalexample>
+ * ]|
*
* If the path description isn't valid %FALSE will be returned and no
* nodes will be added.
diff --git a/clutter/clutter-script.c b/clutter/clutter-script.c
index 4434b4d..8df91b2 100644
--- a/clutter/clutter-script.c
+++ b/clutter/clutter-script.c
@@ -756,15 +756,15 @@ clutter_script_get_objects_valist (ClutterScript *script,
* names/return location pairs should be listed, with a %NULL pointer
* ending the list, like:
*
- * <informalexample><programlisting>
+ * |[
* GObject *my_label, *a_button, *main_timeline;
*
* clutter_script_get_objects (script,
- * "my-label", &my_label,
- * "a-button", &a_button,
- * "main-timeline", &main_timeline,
+ * "my-label", &my_label,
+ * "a-button", &a_button,
+ * "main-timeline", &main_timeline,
* NULL);
- * </programlisting></informalexample>
+ * ]|
*
* Note: This function does not increment the reference count of the
* returned objects.
diff --git a/clutter/clutter-scroll-actor.c b/clutter/clutter-scroll-actor.c
index e1acc1e..49f7327 100644
--- a/clutter/clutter-scroll-actor.c
+++ b/clutter/clutter-scroll-actor.c
@@ -36,13 +36,8 @@
* #ClutterScrollActor does not provide pointer or keyboard event handling,
* nor does it provide visible scroll handles.
*
- * <informalexample>
- * <programlisting>
- * <xi:include xmlns:xi="http://www.w3.org/2001/XInclude"; parse="text"
href="../../../../examples/scroll-actor.c">
- * <xi:fallback>FIXME: MISSING XINCLUDE CONTENT</xi:fallback>
- * </xi:include>
- * </programlisting>
- * </informalexample>
+ * See [scroll-actor.c](https://git.gnome.org/browse/clutter/tree/examples/scroll-actor.c?h=clutter-1.18)
+ * for an example of how to use #ClutterScrollActor.
*
* #ClutterScrollActor is available since Clutter 1.12.
*/
diff --git a/clutter/clutter-settings.c b/clutter/clutter-settings.c
index f0e3ef0..7b00329 100644
--- a/clutter/clutter-settings.c
+++ b/clutter/clutter-settings.c
@@ -600,12 +600,11 @@ clutter_settings_class_init (ClutterSettingsClass *klass)
*
* The style of the hinting used when rendering text. Valid values
* are:
- * <itemizedlist>
- * <listitem><simpara>hintnone</simpara></listitem>
- * <listitem><simpara>hintslight</simpara></listitem>
- * <listitem><simpara>hintmedium</simpara></listitem>
- * <listitem><simpara>hintfull</simpara></listitem>
- * </itemizedlist>
+ *
+ * - hintnone
+ * - hintslight
+ * - hintmedium
+ * - hintfull
*
* Since: 1.4
*/
@@ -621,13 +620,12 @@ clutter_settings_class_init (ClutterSettingsClass *klass)
*
* The type of sub-pixel antialiasing used when rendering text. Valid
* values are:
- * <itemizedlist>
- * <listitem><simpara>none</simpara></listitem>
- * <listitem><simpara>rgb</simpara></listitem>
- * <listitem><simpara>bgr</simpara></listitem>
- * <listitem><simpara>vrgb</simpara></listitem>
- * <listitem><simpara>vbgr</simpara></listitem>
- * </itemizedlist>
+ *
+ * - none
+ * - rgb
+ * - bgr
+ * - vrgb
+ * - vbgr
*
* Since: 1.4
*/
diff --git a/clutter/clutter-shader-effect.c b/clutter/clutter-shader-effect.c
index 95b7d6a..a516978 100644
--- a/clutter/clutter-shader-effect.c
+++ b/clutter/clutter-shader-effect.c
@@ -34,35 +34,43 @@
* GLSL shader (after checking whether the compilation and linking were
* successfull) to the buffer before painting it on screen.
*
- * <refsect2 id="ClutterShaderEffect-implementing">
- * <title>Implementing a ClutterShaderEffect</title>
- * <para>Creating a sub-class of #ClutterShaderEffect requires the
- * overriding of the #ClutterOffscreenEffectClass.paint_target() virtual
- * function from the #ClutterOffscreenEffect class as well as the
- * <function>get_static_shader_source()</function> virtual from the
- * #ClutterShaderEffect class.</para>
- * <para>The #ClutterShaderEffectClass.get_static_shader_source()
- * function should return a copy of the shader source to use. This
- * function is only called once per subclass of #ClutterShaderEffect
- * regardless of how many instances of the effect are created. The
- * source for the shader is typically stored in a static const
- * string which is returned from this function via
- * g_strdup().</para>
- * <para>The <function>paint_target()</function> should set the
- * shader's uniforms if any. This is done by calling
- * clutter_shader_effect_set_uniform_value() or
- * clutter_shader_effect_set_uniform(). The sub-class should then
- * chain up to the #ClutterShaderEffect implementation.</para>
- * <example id="ClutterShaderEffect-example-uniforms">
- * <title>Setting uniforms on a ClutterShaderEffect</title>
- * <para>The example below shows a typical implementation of the
- * <function>get_static_shader_source()</function> and
- * <function>paint_target()</function> phases of a
- * #ClutterShaderEffect sub-class.</para>
- * <programlisting>
+ * #ClutterShaderEffect is available since Clutter 1.4
+ *
+ * ## Implementing a ClutterShaderEffect
+ *
+ * Creating a sub-class of #ClutterShaderEffect requires the
+ * overriding of the #ClutterOffscreenEffectClass.paint_target() virtual
+ * function from the #ClutterOffscreenEffect class. It is also convenient
+ * to implement the #ClutterShaderEffectClass.get_static_shader_source()
+ * virtual function in case you are planning to create more than one
+ * instance of the effect.
+ *
+ * The #ClutterShaderEffectClass.get_static_shader_source()
+ * function should return a copy of the shader source to use. This
+ * function is only called once per subclass of #ClutterShaderEffect
+ * regardless of how many instances of the effect are created. The
+ * source for the shader is typically stored in a static const
+ * string which is returned from this function via
+ * g_strdup().
+ *
+ * The #ClutterOffscreenEffectClass.paint_target() should set the
+ * shader's uniforms if any. This is done by calling
+ * clutter_shader_effect_set_uniform_value() or
+ * clutter_shader_effect_set_uniform(). The sub-class should then
+ * chain up to the #ClutterShaderEffect implementation.
+ *
+ * ## Setting uniforms on a ClutterShaderEffect
+ *
+ * The example below shows a typical implementation of the
+ * #ClutterShaderEffectClass.get_static_shader_source() and
+ * #ClutterOffscreenEffectClass.paint_target() virtual functions
+ * for a #ClutterShaderEffect subclass.
+ *
+ * |[<!-- language="C" -->
* static gchar *
* my_effect_get_static_shader_source (ClutterShaderEffect *effect)
* {
+ * // shader_source is set elsewhere
* return g_strdup (shader_source);
* }
*
@@ -74,21 +82,19 @@
* ClutterEffectClass *parent_class;
* gfloat component_r, component_g, component_b;
*
- * /* the "tex" uniform is declared in the shader as:
- * *
- * * uniform int tex;
- * *
- * * and it is passed a constant value of 0
- * */
+ * // the "tex" uniform is declared in the shader as:
+ * //
+ * // uniform int tex;
+ * //
+ * // and it is passed a constant value of 0
* clutter_shader_effect_set_uniform (shader, "tex", G_TYPE_INT, 1, 0);
*
- * /* the "component" uniform is declared in the shader as:
- * *
- * * uniform vec3 component;
- * *
- * * and it's defined to contain the normalized components
- * * of a #ClutterColor
- * */
+ * // the "component" uniform is declared in the shader as:
+ * //
+ * // uniform vec3 component;
+ * //
+ * // and it's defined to contain the normalized components
+ * // of a #ClutterColor
* component_r = self->color.red / 255.0f;
* component_g = self->color.green / 255.0f;
* component_b = self->color.blue / 255.0f;
@@ -98,15 +104,11 @@
* component_g,
* component_b);
*
- * /* chain up to the parent's implementation */
+ * // chain up to the parent's implementation
* parent_class = CLUTTER_OFFSCREEN_EFFECT_CLASS (my_effect_parent_class);
* return parent_class->paint_target (effect);
* }
- * </programlisting>
- * </example>
- * </refsect2>
- *
- * #ClutterShaderEffect is available since Clutter 1.4
+ * ]|
*/
#ifdef HAVE_CONFIG_H
@@ -805,7 +807,7 @@ add_uniform:
* argument, and by the @gtype argument. For instance, a uniform named
* "sampler0" and containing a single integer value is set using:
*
- * |[
+ * |[<!-- language="C" -->
* clutter_shader_effect_set_uniform (effect, "sampler0",
* G_TYPE_INT, 1,
* 0);
@@ -814,7 +816,7 @@ add_uniform:
* While a uniform named "components" and containing a 3-elements vector
* of floating point values (a "vec3") can be set using:
*
- * |[
+ * |[<!-- language="C" -->
* gfloat component_r, component_g, component_b;
*
* clutter_shader_effect_set_uniform (effect, "components",
@@ -826,7 +828,7 @@ add_uniform:
*
* or can be set using:
*
- * |[
+ * |[<!-- language="C" -->
* gfloat component_vec[3];
*
* clutter_shader_effect_set_uniform (effect, "components",
@@ -836,7 +838,7 @@ add_uniform:
*
* Finally, a uniform named "map" and containing a matrix can be set using:
*
- * |[
+ * |[<!-- language="C" -->
* clutter_shader_effect_set_uniform (effect, "map",
* CLUTTER_TYPE_SHADER_MATRIX, 1,
* cogl_matrix_get_array (&matrix));
diff --git a/clutter/clutter-stage.c b/clutter/clutter-stage.c
index d9a1c67..24f6759 100644
--- a/clutter/clutter-stage.c
+++ b/clutter/clutter-stage.c
@@ -2179,9 +2179,9 @@ clutter_stage_class_init (ClutterStageClass *klass)
* It is possible to override the default behaviour by connecting
* a new handler and returning %TRUE there.
*
- * <note>This signal is emitted only on Clutter backends that
+ * This signal is emitted only on Clutter backends that
* embed #ClutterStage in native windows. It is not emitted for
- * backends that use a static frame buffer.</note>
+ * backends that use a static frame buffer.
*
* Since: 1.2
*/
@@ -3194,29 +3194,29 @@ clutter_stage_set_use_fog (ClutterStage *stage,
* ClutterColor stage_color = { 0, };
* CoglColor fog_color = { 0, };
*
- * /* set the fog color to the stage background color */
- * clutter_stage_get_color (CLUTTER_STAGE (actor), &stage_color);
- * cogl_color_init_from_4ub (&fog_color,
+ * // set the fog color to the stage background color
+ * clutter_stage_get_color (CLUTTER_STAGE (actor), &stage_color);
+ * cogl_color_init_from_4ub (&fog_color,
* stage_color.red,
* stage_color.green,
* stage_color.blue,
* stage_color.alpha);
*
- * /* enable fog */
- * cogl_set_fog (&fog_color,
- * COGL_FOG_MODE_EXPONENTIAL, /* mode */
- * 0.5, /* density */
- * 5.0, 30.0); /* z_near and z_far */
+ * // enable fog //
+ * cogl_set_fog (&fog_color,
+ * COGL_FOG_MODE_EXPONENTIAL, // mode
+ * 0.5, // density
+ * 5.0, 30.0); // z_near and z_far
* }
* ]|
*
- * <note>The fogging functions only work correctly when the visible actors use
+ * The fogging functions only work correctly when the visible actors use
* unmultiplied alpha colors. By default Cogl will premultiply textures and
* cogl_set_source_color() will premultiply colors, so unless you explicitly
* load your textures requesting an unmultiplied internal format and use
* cogl_material_set_color() you can only use fogging with fully opaque actors.
* Support for premultiplied colors will improve in the future when we can
- * depend on fragment shaders.</note>
+ * depend on fragment shaders.
*
* Since: 0.6
*
@@ -3616,8 +3616,8 @@ clutter_stage_ensure_redraw (ClutterStage *stage)
*
* Queues a redraw for the passed stage.
*
- * <note>Applications should call clutter_actor_queue_redraw() and not
- * this function.</note>
+ * Applications should call clutter_actor_queue_redraw() and not
+ * this function.
*
* Since: 0.8
*
@@ -3925,12 +3925,12 @@ _clutter_stage_clear_update_time (ClutterStage *stage)
* if the stage is always covered - for instance, in a full-screen
* video player or in a game with a background texture.
*
- * <note><para>This setting is a hint; Clutter might discard this
- * hint depending on its internal state.</para></note>
+ * This setting is a hint; Clutter might discard this hint
+ * depending on its internal state.
*
- * <warning><para>If parts of the stage are visible and you disable
- * clearing you might end up with visual artifacts while painting the
- * contents of the stage.</para></warning>
+ * If parts of the stage are visible and you disable clearing you
+ * might end up with visual artifacts while painting the contents of
+ * the stage.
*
* Since: 1.4
*/
@@ -4232,14 +4232,12 @@ clutter_stage_get_accept_focus (ClutterStage *stage)
*
* The default is %TRUE.
*
- * If @enable is %FALSE the following events will not be delivered
- * to the actors children of @stage.
+ * If @enable is %FALSE the following signals will not be emitted
+ * by the actors children of @stage:
*
- * <itemizedlist>
- * <listitem><para>#ClutterActor::motion-event</para></listitem>
- * <listitem><para>#ClutterActor::enter-event</para></listitem>
- * <listitem><para>#ClutterActor::leave-event</para></listitem>
- * </itemizedlist>
+ * - #ClutterActor::motion-event
+ * - #ClutterActor::enter-event
+ * - #ClutterActor::leave-event
*
* The events will still be delivered to the #ClutterStage.
*
diff --git a/clutter/clutter-test-utils.c b/clutter/clutter-test-utils.c
index bf38be5..415e222 100644
--- a/clutter/clutter-test-utils.c
+++ b/clutter/clutter-test-utils.c
@@ -226,7 +226,7 @@ clutter_test_add_data_full (const char *test_path,
* int
* main (int argc, char *argv[])
* {
- * clutter_test_init (&argc, &argv);
+ * clutter_test_init (&argc, &argv);
*
* clutter_test_add ("/unit/foo", unit_foo);
* clutter_test_add ("/unit/bar", unit_bar);
diff --git a/clutter/clutter-test-utils.h b/clutter/clutter-test-utils.h
index d88727d..81dad97 100644
--- a/clutter/clutter-test-utils.h
+++ b/clutter/clutter-test-utils.h
@@ -64,7 +64,7 @@ G_BEGIN_DECLS
* main (int argc,
* char *argv[])
* {
- * clutter_test_init (&argc, &argv);
+ * clutter_test_init (&argc, &argv);
*
* clutter_test_add ("/foobarize", foobarize);
* clutter_test_add ("/bar-enabled", bar_enabled);
diff --git a/clutter/clutter-text.c b/clutter/clutter-text.c
index 2ce8319..bb4b364 100644
--- a/clutter/clutter-text.c
+++ b/clutter/clutter-text.c
@@ -3709,10 +3709,10 @@ clutter_text_class_init (ClutterTextClass *klass)
* For more informations about the Pango markup format, see
* pango_layout_set_markup() in the Pango documentation.
*
- * <note>It is not possible to round-trip this property between
+ * It is not possible to round-trip this property between
* %TRUE and %FALSE. Once a string with markup has been set on
* a #ClutterText actor with :use-markup set to %TRUE, the markup
- * is stripped from the string.</note>
+ * is stripped from the string.
*
* Since: 1.0
*/
diff --git a/clutter/clutter-timeline.c b/clutter/clutter-timeline.c
index b830b37..f64fd93 100644
--- a/clutter/clutter-timeline.c
+++ b/clutter/clutter-timeline.c
@@ -19,8 +19,6 @@
*
* You should have received a copy of the GNU Lesser General Public
* License along with this library. If not, see <http://www.gnu.org/licenses/>.
- *
- *
*/
/**
@@ -57,8 +55,8 @@
* its #ClutterTimeline:duration.
*
* It is possible to connect to specific points in the timeline progress by
- * adding <emphasis>markers</emphasis> using clutter_timeline_add_marker_at_time()
- * and connecting to the #ClutterTimeline::marker-reached signal.
+ * adding markers using clutter_timeline_add_marker_at_time() and connecting
+ * to the #ClutterTimeline::marker-reached signal.
*
* Timelines can be made to loop once they reach the end of their duration, by
* using clutter_timeline_set_repeat_count(); a looping timeline will still
@@ -75,13 +73,14 @@
* Timelines are used in the Clutter animation framework by classes like
* #ClutterAnimation, #ClutterAnimator, and #ClutterState.
*
- * <refsect2 id="timeline-script">
- * <title>Defining Timelines in ClutterScript</title>
- * <para>A #ClutterTimeline can be described in #ClutterScript like any
- * other object. Additionally, it is possible to define markers directly
- * inside the JSON definition by using the <emphasis>markers</emphasis>
- * JSON object member, such as:</para>
- * <informalexample><programlisting><![CDATA[
+ * ## Defining Timelines in ClutterScript
+ *
+ * A #ClutterTimeline can be described in #ClutterScript like any
+ * other object. Additionally, it is possible to define markers directly
+ * inside the JSON definition by using the `markers` JSON object member,
+ * such as:
+ *
+ * |[
{
"type" : "ClutterTimeline",
"duration" : 1000,
@@ -91,8 +90,7 @@
{ "name" : "three-quarters", "time" : 750 }
]
}
- * ]]></programlisting></informalexample>
- * </refsect2>
+ * ]|
*/
#ifdef HAVE_CONFIG_H
@@ -1366,10 +1364,9 @@ clutter_timeline_skip (ClutterTimeline *timeline,
* Advance timeline to the requested point. The point is given as a
* time in milliseconds since the timeline started.
*
- * <note><para>The @timeline will not emit the #ClutterTimeline::new-frame
+ * The @timeline will not emit the #ClutterTimeline::new-frame
* signal for the given time. The first ::new-frame signal after the call to
* clutter_timeline_advance() will be emit the skipped markers.
- * </para></note>
*/
void
clutter_timeline_advance (ClutterTimeline *timeline,
@@ -1423,15 +1420,15 @@ clutter_timeline_is_playing (ClutterTimeline *timeline)
* Create a new #ClutterTimeline instance which has property values
* matching that of supplied timeline. The cloned timeline will not
* be started and will not be positioned to the current position of
- * the original @timeline: you will have to start it with clutter_timeline_start().
+ * the original @timeline: you will have to start it with
+ * clutter_timeline_start().
+ *
+ * The only cloned properties are:
*
- * <note><para>The only cloned properties are:</para>
- * <itemizedlist>
- * <listitem><simpara>#ClutterTimeline:duration</simpara></listitem>
- * <listitem><simpara>#ClutterTimeline:loop</simpara></listitem>
- * <listitem><simpara>#ClutterTimeline:delay</simpara></listitem>
- * <listitem><simpara>#ClutterTimeline:direction</simpara></listitem>
- * </itemizedlist></note>
+ * - #ClutterTimeline:duration
+ * - #ClutterTimeline:loop
+ * - #ClutterTimeline:delay
+ * - #ClutterTimeline:direction
*
* Return value: (transfer full): a new #ClutterTimeline, cloned
* from @timeline
@@ -1934,10 +1931,10 @@ clutter_timeline_list_markers (ClutterTimeline *timeline,
*
* Advances @timeline to the time of the given @marker_name.
*
- * <note><para>Like clutter_timeline_advance(), this function will not
+ * Like clutter_timeline_advance(), this function will not
* emit the #ClutterTimeline::new-frame for the time where @marker_name
* is set, nor it will emit #ClutterTimeline::marker-reached for
- * @marker_name.</para></note>
+ * @marker_name.
*
* Since: 0.8
*/
diff --git a/clutter/clutter-types.h b/clutter/clutter-types.h
index ad97a63..10ef8dd 100644
--- a/clutter/clutter-types.h
+++ b/clutter/clutter-types.h
@@ -564,9 +564,9 @@ void clutter_actor_box_set_size (ClutterActorBox *box,
*
* The rectangle containing an actor's bounding box, measured in pixels.
*
- * <warning>You should not use #ClutterGeometry, or operate on its fields
+ * You should not use #ClutterGeometry, or operate on its fields
* directly; you should use #cairo_rectangle_int_t or #ClutterRect if you
- * need a rectangle type, depending on the precision required.</warning>
+ * need a rectangle type, depending on the precision required.
*
* Deprecated: 1.16
*/
diff --git a/clutter/clutter-units.c b/clutter/clutter-units.c
index f07f0f6..f49df9b 100644
--- a/clutter/clutter-units.c
+++ b/clutter/clutter-units.c
@@ -466,7 +466,7 @@ clutter_units_to_pixels (ClutterUnits *units)
* omg!1!ponies
* ]|
*
- * <note><para>If no unit is specified, pixels are assumed.</para></note>
+ * If no unit is specified, pixels are assumed.
*
* Return value: %TRUE if the string was successfully parsed,
* and %FALSE otherwise
@@ -595,9 +595,9 @@ clutter_unit_type_name (ClutterUnitType unit_type)
* See clutter_units_from_string() for the units syntax and for
* examples of output
*
- * <note>Fractional values are truncated to the second decimal
+ * Fractional values are truncated to the second decimal
* position for em, mm and cm, and to the first decimal position for
- * typographic points. Pixels are integers.</note>
+ * typographic points. Pixels are integers.
*
* Return value: a newly allocated string containing the encoded
* #ClutterUnits value. Use g_free() to free the string
[
Date Prev][
Date Next] [
Thread Prev][
Thread Next]
[
Thread Index]
[
Date Index]
[
Author Index]
