Commit 12370bd4 authored by Emmanuele Bassi's avatar Emmanuele Bassi

docs: Move to markdown

We're removing docbook tags in favour of the markdown syntax.
parent 115104db
This diff is collapsed.
......@@ -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.
*
......
......@@ -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
*/
......
......@@ -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:
*
* |[
* /&ast; source &ast;/
* rect[0] = clutter_rectangle_new_with_color (&amp;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);
*
* /&ast; second rectangle &ast;/
* rect[1] = clutter_rectangle_new_with_color (&amp;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);
*
* /&ast; third rectangle &ast;/
* rect[2] = clutter_rectangle_new_with_color (&amp;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
*/
......
......@@ -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;
*
* /&ast; retrieve the binding pool for the type of the actor &ast;/
* // retrieve the binding pool for the type of the actor
* pool = clutter_binding_pool_find (G_OBJECT_TYPE_NAME (actor));
*
* /&ast; activate any callback matching the key symbol and modifiers
* &ast; mask of the key event. the returned value can be directly
* &ast; used to signal that the actor has handled the event.
* &ast;/
* // 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-&gt;keyval,
* key_event-&gt;modifier_state,
* key_event->keyval,
* key_event->modifier_state,
* G_OBJECT (actor));
* ]|
*
......
......@@ -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().
......
......@@ -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.
*/
......
......@@ -63,14 +63,14 @@ typedef struct _ClutterChildMetaClass ClutterChildMetaClass;
* static void
* my_container_iface_init (ClutterContainerIface *iface)
* {
* /&ast; set the rest of the #ClutterContainer vtable &ast;/
* // 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
*/
......
......@@ -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
*/
......
......@@ -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>&num;rgb</literal>,
* <literal>&num;rrggbb</literal>, <literal>&num;rgba</literal> or
* <literal>&num;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
......
......@@ -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
......
......@@ -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
......
......@@ -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
*/
......
......@@ -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
*/
......
......@@ -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)
* {
* /&ast; Set up initialisation of the paint such as binding a
* CoglOffscreen or other operations &ast;/
* // Set up initialisation of the paint such as binding a
* // CoglOffscreen or other operations
*
* /&ast; 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. &ast;/
* // 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);
*
* /&ast; perform any cleanup of state, such as popping the
* CoglOffscreen &ast;/
* // 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);
*
* /&ast; Clear the previous state &ast;/
* if (self-&gt;rect_1)
* // Clear the previous state //
* if (self->rect_1)
* {
* cogl_handle_unref (self-&gt;rect_1);
* self-&gt;rect_1 = NULL;
* cogl_handle_unref (self->rect_1);
* self->rect_1 = NULL;
* }
*
* if (self-&gt;rect_2)
* if (self->rect_2)
* {
* cogl_handle_unref (self-&gt;rect_2);
* self-&gt;rect_2 = NULL;
* cogl_handle_unref (self->rect_2);
* self->rect_2 = NULL;
* }