docs: Move to markdown

We're removing docbook tags in favour of the markdown syntax.
This commit is contained in:
Emmanuele Bassi 2014-03-17 23:07:58 +00:00
parent 115104db8c
commit 12370bd4f8
36 changed files with 1048 additions and 1477 deletions

File diff suppressed because it is too large Load Diff

View File

@ -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.
*

View File

@ -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
*/

View File

@ -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
*/

View File

@ -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));
* ]|
*

View File

@ -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().

View File

@ -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.
*/

View File

@ -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
*/

View File

@ -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
*/

View File

@ -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

View File

@ -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

View File

@ -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

View File

@ -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
*/

View File

@ -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
*/

View File

@ -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;
* }
*
* /&ast; Maintain a pointer to the actor &ast;
* self-&gt;actor = actor;
* // Maintain a pointer to the actor
* self->actor = actor;
*
* /&ast; If we've been detached by the actor then we should
* &ast; just bail out here
* &ast;/
* if (self-&gt;actor == NULL)
* // If we've been detached by the actor then we should just bail out here
* if (self->actor == NULL)
* return;
*
* /&ast; Create a red material &ast;/
* self-&gt;rect_1 = cogl_material_new ();
* cogl_material_set_color4f (self-&gt;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);
*
* /&ast; Create a green material &ast;/
* self-&gt;rect_2 = cogl_material_new ();
* cogl_material_set_color4f (self-&gt;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-&gt;actor, &amp;width, &amp;height);
* clutter_actor_get_size (self->actor, &width, &height);
*
* /&ast; Paint the first rectangle in the upper left quadrant &ast;/
* cogl_set_source (self-&gt;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);
*
* /&ast; Continue to the rest of the paint sequence &ast;/
* clutter_actor_continue_paint (self-&gt;actor);
* // Continue to the rest of the paint sequence
* clutter_actor_continue_paint (self->actor);
*
* /&ast; Paint the second rectangle in the lower right quadrant &ast;/
* cogl_set_source (self-&gt;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-&gt;set_actor = my_effect_set_actor;
* meta_class->set_actor = my_effect_set_actor;
*
* klass-&gt;paint = my_effect_paint;
* klass->paint = my_effect_paint;
* }
* </programlisting>
* </example>
* </refsect2>
* ]|
*
* #ClutterEffect is available since Clutter 1.4
*/

View File

@ -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
*/

View File

@ -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
*/

View File

@ -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.
*/

View File

@ -1036,9 +1036,9 @@ clutter_input_device_get_device_mode (ClutterInputDevice *device)
* |[
* ClutterEvent c_event;
*
* translate_native_event_to_clutter (native_event, &amp;c_event);
* translate_native_event_to_clutter (native_event, &c_event);
*
* clutter_do_event (&amp;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, &amp;c_event);
* translate_native_event_to_clutter (native_event, &c_event);
*
* /&ast; get the device manager &ast;/
* // get the device manager
* manager = clutter_device_manager_get_default ();
*
* /&ast; use the default Core Pointer that Clutter
* &ast; backends register by default
* &ast;/
* // use the default Core Pointer that Clutter backends register by default
* device = clutter_device_manager_get_core_device (manager, %CLUTTER_POINTER_DEVICE);
*
* /&ast; update the state of the input device &ast;/
* clutter_input_device_update_from_event (device, &amp;c_event, FALSE);
* // update the state of the input device
* clutter_input_device_update_from_event (device, &c_event, FALSE);
*
* clutter_do_event (&amp;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,
* &amp;pressure_value);
* &pressure_value);
* ]|
*
* Return value: %TRUE if the value was set, and %FALSE otherwise

View File

@ -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>
* ## 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.
*
* <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>
* 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.
*
* <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;
* 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.
*
* for (child = clutter_actor_get_first_child (CLUTTER_ACTOR (container));
* child != NULL;
* child = clutter_actor_get_next_sibling (child))
* {
* ClutterLayoutMeta *meta;
* MyLayoutMeta *my_meta;
* ## Layout Properties
*
* /&ast; retrieve the layout meta-object &ast;/
* meta = clutter_layout_manager_get_child_meta (manager,
* container,
* child);
* my_meta = MY_LAYOUT_META (meta);
* 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:
*
* /&ast; compute the desired allocation for the child &ast;/
* compute_allocation (self, my_meta, child,
* allocation, flags,
* &amp;child_box);
*
* /&ast; this is the additional code that deals with the animation
* &ast; of the layout manager
* &ast;/
* if (!self-&gt;is_animating)
* {
* /&ast; store the last stable allocation for later use &ast;/
* my_meta-&gt;last_alloc = clutter_actor_box_copy (&amp;child_box);
* }
* else
* {
* ClutterActorBox end = { 0, };
* gdouble p;
*
* /&ast; get the progress of the animation &ast;/
* p = clutter_layout_manager_get_animation_progress (manager);
*
* if (my_meta-&gt;last_alloc != NULL)
* {
* /&ast; copy the desired allocation as the final state &ast;/
* end = child_box;
*
* /&ast; then interpolate the initial and final state
* &ast; depending on the progress of the animation,
* &ast; and put the result inside the box we will use
* &ast; to allocate the child
* &ast;/
* clutter_actor_box_interpolate (my_meta-&gt;last_alloc,
* &amp;end,
* p,
* &amp;child_box);
* }
* else
* {
* /&ast; if there is no stable allocation then the child was
* &ast; added while animating; one possible course of action
* &ast; is to just bail out and fall through to the allocation
* &ast; to position the child directly at its final state
* &ast;/
* my_meta-&gt;last_alloc =
* clutter_actor_box_copy (&amp;child_box);
* }
* }
*
* /&ast; allocate the child &ast;/
* 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>
* |[
* 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>
* ]|
*
* <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>
* 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:
*
* |[
* {
* "type" : "ClutterBox",
* "layout-manager" : { "type" : "ClutterTableLayout" },
@ -314,8 +124,7 @@
* }
* ]
* }
* </programlisting></informalexample>
* </refsect2>
* ]|
*
* #ClutterLayoutManager is available since Clutter 1.2
*/

View File

@ -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[])
* {
* /&ast; initialize Clutter &ast;/
* clutter_init (&amp;argc, &amp;argv);
* ## The Clutter Threading Model
*
* /&ast; program code &ast;/
* 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.
*
* /&ast; acquire the main lock &ast;/
* clutter_threads_enter ();
* 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().
*
* /&ast; start the main loop &ast;/
* clutter_main ();
* 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.
*
* /&ast; release the main lock &ast;/
* clutter_threads_leave ();
*
* /&ast; clean up &ast;/
* 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 &mdash; 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;
*
* /&ast; mark the critical section &ast;/
* // mark the critical section //
*
* clutter_threads_enter();
*
* /&ast; the callback does not need to acquire the Clutter
* &ast; lock itself, as it is held by the this proxy handler
* &ast;/
* // 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-&gt;callback = callback;
* closure-&gt;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;
*
* /&ast; it is safe to call Clutter API from this function because
* &ast; it is invoked from the same thread that started the main
* &ast; loop and under the Clutter thread lock
* &ast;/
* clutter_label_set_text (CLUTTER_LABEL (closure-&gt;label),
* closure-&gt;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-&gt;label);
* g_object_unref (closure->label);
* g_free (closure);
*
* return FALSE;
* }
*
* /&ast; within another thread &ast;/
* // within another thread //
* closure = g_new0 (SomeClosure, 1);
* /&ast; always take a reference on GObject instances &ast;/
* closure-&gt;label = g_object_ref (my_application-&gt;label);
* closure-&gt;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, &amp;argc, &amp;argc, NULL);
* res = g_option_context_parse (context, &argc, &argc, NULL);
* ]|
*
* is functionally equivalent to:
*
* |[
* clutter_init (&amp;argc, &amp;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:
*
* |[
* &num;ifdef CLUTTER_WINDOWING_X11
* #ifdef CLUTTER_WINDOWING_X11
* if (clutter_check_windowing_backend (CLUTTER_WINDOWING_X11))
* {
* /&ast; it is safe to use the clutter_x11_* API &ast;/
* // it is safe to use the clutter_x11_* API
* }
* else
* &num;endif
* &num;ifdef CLUTTER_WINDOWING_WIN32
* #endif
* #ifdef CLUTTER_WINDOWING_WIN32
* if (clutter_check_windowing_backend (CLUTTER_WINDOWING_WIN32))
* {
* /&ast; it is safe to use the clutter_win32_* API &ast;/
* // it is safe to use the clutter_win32_* API
* }
* else
* &num;endif
* #endif
* g_error ("Unknown Clutter backend.");
* ]|
*

View File

@ -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
*/

View File

@ -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,

View File

@ -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
*/

View File

@ -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.

View File

@ -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", &amp;my_label,
* "a-button", &amp;a_button,
* "main-timeline", &amp;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.

View File

@ -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.
*/

View File

@ -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
*/

View File

@ -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;
*
* /&ast; the "tex" uniform is declared in the shader as:
* &ast;
* &ast; uniform int tex;
* &ast;
* &ast; and it is passed a constant value of 0
* &ast;/
* // 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);
*
* /&ast; the "component" uniform is declared in the shader as:
* &ast;
* &ast; uniform vec3 component;
* &ast;
* &ast; and it's defined to contain the normalized components
* &ast; of a #ClutterColor
* &ast;/
* // 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);
*
* /&ast; chain up to the parent's implementation &ast;/
* // 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));

View File

@ -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, };
*
* /&ast; set the fog color to the stage background color &ast;/
* clutter_stage_get_color (CLUTTER_STAGE (actor), &amp;stage_color);
* cogl_color_init_from_4ub (&amp;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);
*
* /&ast; enable fog &ast;/
* cogl_set_fog (&amp;fog_color,
* COGL_FOG_MODE_EXPONENTIAL, /&ast; mode &ast;/
* 0.5, /&ast; density &ast;/
* 5.0, 30.0); /&ast; z_near and z_far &ast;/
* // 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.
*

View File

@ -226,7 +226,7 @@ clutter_test_add_data_full (const char *test_path,
* int
* main (int argc, char *argv[])
* {
* clutter_test_init (&amp;argc, &amp;argv);
* clutter_test_init (&argc, &argv);
*
* clutter_test_add ("/unit/foo", unit_foo);
* clutter_test_add ("/unit/bar", unit_bar);

View File

@ -64,7 +64,7 @@ G_BEGIN_DECLS
* main (int argc,
* char *argv[])
* {
* clutter_test_init (&amp;argc, &amp;argv);
* clutter_test_init (&argc, &argv);
*
* clutter_test_add ("/foobarize", foobarize);
* clutter_test_add ("/bar-enabled", bar_enabled);

View File

@ -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
*/

View File

@ -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().
*
* <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>
* The only cloned properties are:
*
* - #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
*/

View File

@ -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
*/

View File

@ -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