sungmg/mutter-performance-source
1
0
Fork 0
Code Activity

docs: Move to markdown

Browse source 
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
Show stats Download patch file Download diff file Expand all files Collapse all files

888
clutter/clutter-actor.c
View file

File diff suppressed because it is too large Load diff

8
clutter/clutter-backend.c
View file

@ -1344,12 +1344,12 @@ _clutter_backend_remove_event_translator (ClutterBackend *backend,
* @backend. A #CoglContext is required when using some of the * @backend. A #CoglContext is required when using some of the
* experimental 2.0 Cogl API. * experimental 2.0 Cogl API.
* *
* <note>Since CoglContext is itself experimental API this API should * Since CoglContext is itself experimental API this API should
* be considered experimental too.</note> * 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 * 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. * Return value: (transfer none): The #CoglContext associated with @backend.
* *

34
clutter/clutter-bin-layout.c
View file

@ -29,34 +29,16 @@
* #ClutterBinLayout is a layout manager which implements the following * #ClutterBinLayout is a layout manager which implements the following
* policy: * policy:
* *
* <itemizedlist> * - the preferred size is the maximum preferred size
* <listitem><simpara>the preferred size is the maximum preferred size
* between all the children of the container using the * between all the children of the container using the
* layout;</simpara></listitem> * layout;
* <listitem><simpara>each child is allocated in "layers", on on top * - each child is allocated in "layers", on on top
* of the other;</simpara></listitem> * of the other;
* <listitem><simpara>for each layer there are horizontal and vertical * - for each layer there are horizontal and vertical
* alignment policies.</simpara></listitem> * alignment policies.
* </itemizedlist>
* *
* <figure id="bin-layout"> * The [bin-layout example](https://git.gnome.org/browse/clutter/tree/examples/bin-layout.c?h=clutter-1.18)
* <title>Bin layout</title> * shows how to pack actors inside a #ClutterBinLayout.
* <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>
* *
* #ClutterBinLayout is available since Clutter 1.2 * #ClutterBinLayout is available since Clutter 1.2
*/ */

31
clutter/clutter-bind-constraint.c
View file

@ -36,14 +36,14 @@
* can also be animated. For instance, the following code will set up three * can also be animated. For instance, the following code will set up three
* actors to be bound to the same origin: * actors to be bound to the same origin:
* *
* |[ * |[<!-- language="C" -->
* /&ast; source &ast;/ * // source
* rect[0] = clutter_rectangle_new_with_color (&amp;red_color); * rect[0] = clutter_rectangle_new_with_color (&red_color);
* clutter_actor_set_position (rect[0], x_pos, y_pos); * clutter_actor_set_position (rect[0], x_pos, y_pos);
* clutter_actor_set_size (rect[0], 100, 100); * clutter_actor_set_size (rect[0], 100, 100);
* *
* /&ast; second rectangle &ast;/ * // second rectangle
* rect[1] = clutter_rectangle_new_with_color (&amp;green_color); * rect[1] = clutter_rectangle_new_with_color (&green_color);
* clutter_actor_set_size (rect[1], 100, 100); * clutter_actor_set_size (rect[1], 100, 100);
* clutter_actor_set_opacity (rect[1], 0); * clutter_actor_set_opacity (rect[1], 0);
* *
@ -52,8 +52,8 @@
* constraint = clutter_bind_constraint_new (rect[0], CLUTTER_BIND_Y, 0.0); * constraint = clutter_bind_constraint_new (rect[0], CLUTTER_BIND_Y, 0.0);
* clutter_actor_add_constraint_with_name (rect[1], "green-y", constraint); * clutter_actor_add_constraint_with_name (rect[1], "green-y", constraint);
* *
* /&ast; third rectangle &ast;/ * // third rectangle
* rect[2] = clutter_rectangle_new_with_color (&amp;blue_color); * rect[2] = clutter_rectangle_new_with_color (&blue_color);
* clutter_actor_set_size (rect[2], 100, 100); * clutter_actor_set_size (rect[2], 100, 100);
* clutter_actor_set_opacity (rect[2], 0); * clutter_actor_set_opacity (rect[2], 0);
* *
@ -66,7 +66,7 @@
* The following code animates the second and third rectangles to "expand" * The following code animates the second and third rectangles to "expand"
* them horizontally from underneath the first rectangle: * them horizontally from underneath the first rectangle:
* *
* |[ * |[<!-- language="C" -->
* clutter_actor_animate (rect[1], CLUTTER_EASE_OUT_CUBIC, 250, * clutter_actor_animate (rect[1], CLUTTER_EASE_OUT_CUBIC, 250,
* "@constraints.green-x.offset", 100.0, * "@constraints.green-x.offset", 100.0,
* "opacity", 255, * "opacity", 255,
@ -77,21 +77,6 @@
* NULL); * 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 * #ClutterBindConstraint is available since Clutter 1.4
*/ */

19
clutter/clutter-binding-pool.c
View file

@ -38,7 +38,7 @@
* inside their class initialization function and then install actions * inside their class initialization function and then install actions
* like this: * like this:
* *
* |[ * |[<!-- language="C" -->
* static void * static void
* foo_class_init (FooClass *klass) * foo_class_init (FooClass *klass)
* { * {
@ -59,7 +59,7 @@
* *
* The callback has a signature of: * The callback has a signature of:
* *
* |[ * |[<!-- language="C" -->
* gboolean (* callback) (GObject *instance, * gboolean (* callback) (GObject *instance,
* const gchar *action_name, * const gchar *action_name,
* guint key_val, * guint key_val,
@ -71,19 +71,18 @@
* use clutter_binding_pool_activate() to match a #ClutterKeyEvent structure * use clutter_binding_pool_activate() to match a #ClutterKeyEvent structure
* to one of the actions: * to one of the actions:
* *
* |[ * |[<!-- language="C" -->
* ClutterBindingPool *pool; * 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)); * pool = clutter_binding_pool_find (G_OBJECT_TYPE_NAME (actor));
* *
* /&ast; activate any callback matching the key symbol and modifiers * // activate any callback matching the key symbol and modifiers
* &ast; mask of the key event. the returned value can be directly * // mask of the key event. the returned value can be directly
* &ast; used to signal that the actor has handled the event. * // used to signal that the actor has handled the event.
* &ast;/
* return clutter_binding_pool_activate (pool, * return clutter_binding_pool_activate (pool,
* key_event-&gt;keyval, * key_event->keyval,
* key_event-&gt;modifier_state, * key_event->modifier_state,
* G_OBJECT (actor)); * G_OBJECT (actor));
* ]| * ]|
* *

32
clutter/clutter-box-layout.c
View file

@ -31,30 +31,16 @@
* *
* The #ClutterBoxLayout is a #ClutterLayoutManager implementing the * The #ClutterBoxLayout is a #ClutterLayoutManager implementing the
* following layout policy: * 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"> * - all children are arranged on a single line
* <title>Box layout</title> * - the axis used is controlled by the #ClutterBoxLayout:orientation property
* <para>The image shows a #ClutterBoxLayout with the * - the order of the packing is determined by the #ClutterBoxLayout:pack-start boolean property
* #ClutterBoxLayout:vertical property set to %FALSE.</para> * - each child will be allocated to its natural size or, if #ClutterActor:x-expand or
* <graphic fileref="box-layout.png" format="PNG"/> * #ClutterActor:y-expand are set, the available size
* </figure> * - 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 * It is possible to control the spacing between children of a
* #ClutterBoxLayout by using clutter_box_layout_set_spacing(). * #ClutterBoxLayout by using clutter_box_layout_set_spacing().

9
clutter/clutter-canvas.c
View file

@ -36,13 +36,8 @@
* that can be used to draw. #ClutterCanvas will emit the #ClutterCanvas::draw * that can be used to draw. #ClutterCanvas will emit the #ClutterCanvas::draw
* signal when invalidated using clutter_content_invalidate(). * signal when invalidated using clutter_content_invalidate().
* *
* <informalexample id="canvas-example"> * See [canvas.c](https://git.gnome.org/browse/clutter/tree/examples/canvas.c?h=clutter-1.18)
* <programlisting> * for an example of how to use #ClutterCanvas.
* <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>
* *
* #ClutterCanvas is available since Clutter 1.10. * #ClutterCanvas is available since Clutter 1.10.
*/ */

9
clutter/clutter-child-meta.h
View file

@ -63,14 +63,14 @@ typedef struct _ClutterChildMetaClass ClutterChildMetaClass;
* static void * static void
* my_container_iface_init (ClutterContainerIface *iface) * 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; * container_iface->child_meta_type = MY_TYPE_CHILD_META;
* } * }
* ]| * ]|
* *
* This will automatically create a #ClutterChildMeta of type * 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 * The child data for an actor can be retrieved using the
* clutter_container_get_child_meta() function. * 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 * You can provide hooks for your own storage as well as control the
* instantiation by overriding the #ClutterContainerIface virtual functions * instantiation by overriding the #ClutterContainerIface virtual functions
* <function>create_child_meta</function>, * #ClutterContainerIface.create_child_meta(), #ClutterContainerIface.destroy_child_meta(),
* <function>destroy_child_meta</function>, * and #ClutterContainerIface.get_child_meta().
* and <function>get_child_meta</function>.
* *
* Since: 0.8 * Since: 0.8
*/ */

6
clutter/clutter-clone.c
View file

@ -30,9 +30,9 @@
* *
* #ClutterClone can be used to efficiently clone any other actor. * #ClutterClone can be used to efficiently clone any other actor.
* *
* <note><para>This is different from clutter_texture_new_from_actor() * Unlike clutter_texture_new_from_actor(), #ClutterClone does not require
* which requires support for FBOs in the underlying GL * the presence of support for FBOs in the underlying GL or GLES
* implementation.</para></note> * implementation.
* *
* #ClutterClone is available since Clutter 1.0 * #ClutterClone is available since Clutter 1.0
*/ */

28
clutter/clutter-color.c
View file

@ -624,28 +624,12 @@ parse_hsla (ClutterColor *color,
* *
* The format of @str can be either one of: * The format of @str can be either one of:
* *
* <itemizedlist> * - a standard name (as taken from the X11 rgb.txt file)
* <listitem> * - an hexadecimal value in the form: `#rgb`, `#rrggbb`, `#rgba`, or `#rrggbbaa`
* <para>a standard name (as taken from the X11 rgb.txt file)</para> * - a RGB color in the form: `rgb(r, g, b)`
* </listitem> * - a RGB color in the form: `rgba(r, g, b, a)`
* <listitem> * - a HSL color in the form: `hsl(h, s, l)`
* <para>an hexadecimal value in the form: <literal>&num;rgb</literal>, * -a HSL color in the form: `hsla(h, s, l, a)`
* <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>
* *
* where 'r', 'g', 'b' and 'a' are (respectively) the red, green, blue color * 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 * intensities and the opacity. The 'h', 's' and 'l' are (respectively) the

207
clutter/clutter-constraint.c
View file

@ -13,126 +13,95 @@
* allocation of the actor to which they are applied by overriding the * allocation of the actor to which they are applied by overriding the
* #ClutterConstraintClass.update_allocation() virtual function. * #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 * #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 #ifdef HAVE_CONFIG_H

19
clutter/clutter-deform-effect.c
View file

@ -39,17 +39,16 @@
* a #ClutterActor and then the Cogl vertex buffers API to submit the * a #ClutterActor and then the Cogl vertex buffers API to submit the
* geometry to the GPU. * 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 * #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 #ifdef HAVE_CONFIG_H

20
clutter/clutter-drag-action.c
View file

@ -34,7 +34,7 @@
* a #ClutterActor and setting it as reactive; for instance, the following * a #ClutterActor and setting it as reactive; for instance, the following
* code: * code:
* *
* |[ * |[<!-- language="C" -->
* clutter_actor_add_action (actor, clutter_drag_action_new ()); * clutter_actor_add_action (actor, clutter_drag_action_new ());
* clutter_actor_set_reactive (actor, TRUE); * clutter_actor_set_reactive (actor, TRUE);
* ]| * ]|
@ -54,19 +54,11 @@
* parented and exist between the emission of #ClutterDragAction::drag-begin * parented and exist between the emission of #ClutterDragAction::drag-begin
* and #ClutterDragAction::drag-end. * and #ClutterDragAction::drag-end.
* *
* <example id="drag-action-example"> * The [drag-action example](https://git.gnome.org/browse/clutter/tree/examples/drag-action.c?h=clutter-1.18)
* <title>A simple draggable actor</title> * allows dragging the rectangle around the stage using a #ClutterDragAction.
* <programlisting> * When pressing the `Shift` key the actor that is being dragged will be a
* <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" parse="text" href="../../../../examples/drag-action.c"> * separate rectangle, and when the drag ends, the original rectangle will be
* <xi:fallback>FIXME: MISSING XINCLUDE CONTENT</xi:fallback> * animated to the final drop coordinates.
* </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>
* *
* #ClutterDragAction is available since Clutter 1.4 * #ClutterDragAction is available since Clutter 1.4
*/ */

14
clutter/clutter-drop-action.c
View file

@ -36,7 +36,7 @@
* #ClutterDropAction::drop signal and handling the drop from there, * #ClutterDropAction::drop signal and handling the drop from there,
* for instance: * for instance:
* *
* |[ * |[<!-- language="C" -->
* ClutterAction *action = clutter_drop_action (); * ClutterAction *action = clutter_drop_action ();
* *
* g_signal_connect (action, "drop", G_CALLBACK (on_drop), NULL); * 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 * cause the #ClutterDropAction::drop signal to be skipped when the input
* device button is released. * 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 * It's important to note that #ClutterDropAction will only work with
* actors dragged using #ClutterDragAction. * 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 * #ClutterDropAction is available since Clutter 1.8
*/ */

158
clutter/clutter-effect.c
View file

@ -36,78 +36,50 @@
* actor without sub-classing the actor itself and overriding the * actor without sub-classing the actor itself and overriding the
* #ClutterActorClass.paint()_ virtual function. * #ClutterActorClass.paint()_ virtual function.
* *
* <refsect2 id="ClutterEffect-implementation"> * ## Implementing a ClutterEffect
* <title>Implementing a ClutterEffect</title> *
* <para> * Creating a sub-class of #ClutterEffect requires overriding the
* Creating a sub-class of #ClutterEffect requires overriding the * #ClutterEffectClass.paint() method. The implementation of the function should look
* ‘paint’ method. The implementation of the function should look * something like this:
* something like this: *
* </para> * |[
* <programlisting>
* void effect_paint (ClutterEffect *effect, ClutterEffectPaintFlags flags) * void effect_paint (ClutterEffect *effect, ClutterEffectPaintFlags flags)
* { * {
* /&ast; Set up initialisation of the paint such as binding a * // Set up initialisation of the paint such as binding a
* CoglOffscreen or other operations &ast;/ * // CoglOffscreen or other operations
* *
* /&ast; Chain to the next item in the paint sequence. This will either call * // 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 * // ‘paint’ on the next effect or just paint the actor if this is
* the last effect. &ast;/ * // the last effect.
* ClutterActor *actor = * ClutterActor *actor =
* clutter_actor_meta_get_actor (CLUTTER_ACTOR_META (effect)); * clutter_actor_meta_get_actor (CLUTTER_ACTOR_META (effect));
*
* clutter_actor_continue_paint (actor); * clutter_actor_continue_paint (actor);
* *
* /&ast; perform any cleanup of state, such as popping the * // perform any cleanup of state, such as popping the CoglOffscreen
* CoglOffscreen &ast;/
* } * }
* </programlisting> * ]|
* <para> *
* The effect can optionally avoid calling * The effect can optionally avoid calling clutter_actor_continue_paint() to skip any
* clutter_actor_continue_paint() to skip any further stages of * further stages of the paint sequence. This is useful for example if the effect
* 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
* contains a cached image of the actor. In that case it can * avoiding the actor paint and instead painting the cached image.
* optimise painting by avoiding the actor paint and instead *
* painting the cached image. The %CLUTTER_EFFECT_PAINT_ACTOR_DIRTY * The %CLUTTER_EFFECT_PAINT_ACTOR_DIRTY flag is useful in this case. Clutter will set
* flag is useful in this case. Clutter will set this flag when a * this flag when a redraw has been queued on the actor since it was last painted. The
* redraw has been queued on the actor since it was last * effect can use this information to decide if the cached image is still valid.
* painted. The effect can use this information to decide if the *
* cached image is still valid. * ## A simple ClutterEffect implementation
* </para> *
* <para> * The example below creates two rectangles: one will be painted "behind" the actor,
* The ‘paint’ virtual was added in Clutter 1.8. Prior to that there * while another will be painted "on top" of the actor.
* were two separate functions as follows. *
* </para> * The #ClutterActorMetaClass.set_actor() implementation will create the two materials
* <itemizedlist> * used for the two different rectangles; the #ClutterEffectClass.paint() implementation
* <listitem><simpara><function>pre_paint()</function>, which is called * will paint the first material using cogl_rectangle(), before continuing and then it
* before painting the #ClutterActor.</simpara></listitem> * will paint paint the second material after.
* <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>
* typedef struct { * typedef struct {
* ClutterEffect parent_instance; * ClutterEffect parent_instance;
* *
@ -125,35 +97,33 @@
* { * {
* MyEffect *self = MY_EFFECT (meta); * MyEffect *self = MY_EFFECT (meta);
* *
* /&ast; Clear the previous state &ast;/ * // Clear the previous state //
* if (self-&gt;rect_1) * if (self->rect_1)
* { * {
* cogl_handle_unref (self-&gt;rect_1); * cogl_handle_unref (self->rect_1);
* self-&gt;rect_1 = NULL; * self->rect_1 = NULL;
* } * }
* *
* if (self-&gt;rect_2) * if (self->rect_2)
* { * {
* cogl_handle_unref (self-&gt;rect_2); * cogl_handle_unref (self->rect_2);
* self-&gt;rect_2 = NULL; * self->rect_2 = NULL;
* } * }
* *
* /&ast; Maintain a pointer to the actor &ast; * // Maintain a pointer to the actor
* self-&gt;actor = actor; * self->actor = actor;
* *
* /&ast; If we've been detached by the actor then we should * // If we've been detached by the actor then we should just bail out here
* &ast; just bail out here * if (self->actor == NULL)
* &ast;/
* if (self-&gt;actor == NULL)
* return; * return;
* *
* /&ast; Create a red material &ast;/ * // Create a red material
* self-&gt;rect_1 = cogl_material_new (); * self->rect_1 = cogl_material_new ();
* cogl_material_set_color4f (self-&gt;rect_1, 1.0, 0.0, 0.0, 1.0); * cogl_material_set_color4f (self->rect_1, 1.0, 0.0, 0.0, 1.0);
* *
* /&ast; Create a green material &ast;/ * // Create a green material
* self-&gt;rect_2 = cogl_material_new (); * self->rect_2 = cogl_material_new ();
* cogl_material_set_color4f (self-&gt;rect_2, 0.0, 1.0, 0.0, 1.0); * cogl_material_set_color4f (self->rect_2, 0.0, 1.0, 0.0, 1.0);
* } * }
* *
* static gboolean * static gboolean
@ -162,17 +132,17 @@
* MyEffect *self = MY_EFFECT (effect); * MyEffect *self = MY_EFFECT (effect);
* gfloat width, height; * 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;/ * // Paint the first rectangle in the upper left quadrant
* cogl_set_source (self-&gt;rect_1); * cogl_set_source (self->rect_1);
* cogl_rectangle (0, 0, width / 2, height / 2); * cogl_rectangle (0, 0, width / 2, height / 2);
* *
* /&ast; Continue to the rest of the paint sequence &ast;/ * // Continue to the rest of the paint sequence
* clutter_actor_continue_paint (self-&gt;actor); * clutter_actor_continue_paint (self->actor);
* *
* /&ast; Paint the second rectangle in the lower right quadrant &ast;/ * // Paint the second rectangle in the lower right quadrant
* cogl_set_source (self-&gt;rect_2); * cogl_set_source (self->rect_2);
* cogl_rectangle (width / 2, height / 2, width, height); * cogl_rectangle (width / 2, height / 2, width, height);
* } * }
* *
@ -181,13 +151,11 @@
* { * {
* ClutterActorMetaClas *meta_class = CLUTTER_ACTOR_META_CLASS (klass); * 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 * #ClutterEffect is available since Clutter 1.4
*/ */

35
clutter/clutter-flow-layout.c
View file

@ -29,40 +29,25 @@
* #ClutterFlowLayout is a layout manager which implements the following * #ClutterFlowLayout is a layout manager which implements the following
* policy: * policy:
* *
* <itemizedlist> * - the preferred natural size depends on the value
* <listitem><para>the preferred natural size depends on the value
* of the #ClutterFlowLayout:orientation property; the layout will try * of the #ClutterFlowLayout:orientation property; the layout will try
* to maintain all its children on a single row or * to maintain all its children on a single row or
* column;</para></listitem> * column;
* <listitem><para>if either the width or the height allocated are * - if either the width or the height allocated are
* smaller than the preferred ones, the layout will wrap; in this case, * smaller than the preferred ones, the layout will wrap; in this case,
* the preferred height or width, respectively, will take into account * the preferred height or width, respectively, will take into account
* the amount of columns and rows;</para></listitem> * the amount of columns and rows;
* <listitem><para>each line (either column or row) in reflowing will * - each line (either column or row) in reflowing will
* have the size of the biggest cell on that line; if the * have the size of the biggest cell on that line; if the
* #ClutterFlowLayout:homogeneous property is set to %FALSE the actor * #ClutterFlowLayout:homogeneous property is set to %FALSE the actor
* will be allocated within that area, and if set to %TRUE instead the * will be allocated within that area, and if set to %TRUE instead the
* actor will be given exactly that area;</para></listitem> * actor will be given exactly that area;
* <listitem><para>the size of the columns or rows can be controlled * - the size of the columns or rows can be controlled
* for both minimum and maximum; the spacing can also be controlled * for both minimum and maximum; the spacing can also be controlled
* in both columns and rows.</para></listitem> * in both columns and rows.
* </itemizedlist>
* *
* <figure id="flow-layout-image"> * The [flow-layout example](https://git.gnome.org/browse/clutter/tree/examples/flow-layout.c?h=clutter-1.18)
* <title>Horizontal flow layout</title> * shows how to use the #ClutterFlowLayout.
* <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>
* *
* #ClutterFlowLayout is available since Clutter 1.2 * #ClutterFlowLayout is available since Clutter 1.2
*/ */

64
clutter/clutter-gesture-action.c
View file

@ -38,7 +38,7 @@
* To use #ClutterGestureAction you just need to apply it to a #ClutterActor * To use #ClutterGestureAction you just need to apply it to a #ClutterActor
* using clutter_actor_add_action() and connect to the signals: * using clutter_actor_add_action() and connect to the signals:
* *
* |[ * |[<!-- language="C" -->
* ClutterAction *action = clutter_gesture_action_new (); * ClutterAction *action = clutter_gesture_action_new ();
* *
* clutter_actor_add_action (actor, action); * clutter_actor_add_action (actor, action);
@ -48,37 +48,37 @@
* g_signal_connect (action, "gesture-end", G_CALLBACK (on_gesture_end), NULL); * g_signal_connect (action, "gesture-end", G_CALLBACK (on_gesture_end), NULL);
* ]| * ]|
* *
* <refsect2 id="creating-gesture-action"> * ## Creating Gesture actions
* <title>Creating Gesture actions</title> *
* <para>A #ClutterGestureAction provides four separate states that can be * A #ClutterGestureAction provides four separate states that can be
* used to recognize or ignore gestures when writing a new action class:</para> * used to recognize or ignore gestures when writing a new action class:
* <informalexample><programlisting><![CDATA[ *
Prepare -> Cancel * - Prepare -> Cancel
Prepare -> Begin -> Cancel * - Prepare -> Begin -> Cancel
Prepare -> Begin -> End * - Prepare -> Begin -> End
Prepare -> Begin -> Progress -> Cancel * - Prepare -> Begin -> Progress -> Cancel
Prepare -> Begin -> Progress -> End * - Prepare -> Begin -> Progress -> End
* ]]> *
* </programlisting></informalexample> * Each #ClutterGestureAction starts in the "prepare" state, and calls
* <para>Each #ClutterGestureAction starts in the "prepare" state, and calls * the #ClutterGestureActionClass.gesture_prepare() virtual function; this
* the #ClutterGestureActionClass.gesture_prepare() virtual function; this * state can be used to reset the internal state of a #ClutterGestureAction
* state can be used to reset the internal state of a #ClutterGestureAction * subclass, but it can also immediately cancel a gesture without going
* subclass, but it can also immediately cancel a gesture without going * through the rest of the states.
* through the rest of the states.</para> *
* <para>The "begin" state follows the "prepare" state, and calls the * The "begin" state follows the "prepare" state, and calls the
* #ClutterGestureActionClass.gesture_begin() virtual function. This state * #ClutterGestureActionClass.gesture_begin() virtual function. This state
* signals the start of a gesture recognizing process. From the "begin" state * signals the start of a gesture recognizing process. From the "begin" state
* the gesture recognition process can successfully end, by going to the * the gesture recognition process can successfully end, by going to the
* "end" state; it can continue in the "progress" state, in case of a * "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" * continuous gesture; or it can be terminated, by moving to the "cancel"
* state.</para> * state.
* <para>In case of continuous gestures, the #ClutterGestureAction will use *
* the "progress" state, calling the #ClutterGestureActionClass.gesture_progress() * In case of continuous gestures, the #ClutterGestureAction will use
* virtual function; the "progress" state will continue until the end of the * the "progress" state, calling the #ClutterGestureActionClass.gesture_progress()
* gesture, in which case the "end" state will be reached, or until the * virtual function; the "progress" state will continue until the end of the
* gesture is cancelled, in which case the "cancel" gesture will be used * gesture, in which case the "end" state will be reached, or until the
* instead.</para> * gesture is cancelled, in which case the "cancel" gesture will be used
* </refsect2> * instead.
* *
* Since: 1.8 * Since: 1.8
*/ */

9
clutter/clutter-image.c
View file

@ -28,13 +28,10 @@
* @Short_Description: Image data content * @Short_Description: Image data content
* *
* #ClutterImage is a #ClutterContent implementation that displays * #ClutterImage is a #ClutterContent implementation that displays
* image data. * image data inside a #ClutterActor.
* *
* <informalexample><programlisting> * See [image.c](https://git.gnome.org/browse/clutter/tree/examples/image.c?h=clutter-1.18)
* <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" parse="text" href="../../../../examples/image-content.c"> * for an example of how to use #ClutterImage.
* <xi:fallback>FIXME: MISSING XINCLUDE CONTENT</xi:fallback>
* </xi:include>
* </programlisting></informalexample>
* *
* #ClutterImage is available since Clutter 1.10. * #ClutterImage is available since Clutter 1.10.
*/ */

20
clutter/clutter-input-device.c
View file

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

275
clutter/clutter-layout-manager.c
View file

@ -38,227 +38,36 @@
* Clutter provides some simple #ClutterLayoutManager sub-classes, like * Clutter provides some simple #ClutterLayoutManager sub-classes, like
* #ClutterFlowLayout and #ClutterBinLayout. * #ClutterFlowLayout and #ClutterBinLayout.
* *
* <refsect2 id="ClutterLayoutManager-use-in-Actor"> * ## Implementing a ClutterLayoutManager
* <title>Using a Layout Manager inside an Actor</title> * The implementation of a layout manager does not differ from the
* <para>In order to use a #ClutterLayoutManager inside a #ClutterActor * implementation of the size requisition and allocation bits of
* sub-class you should invoke clutter_layout_manager_get_preferred_width() * #ClutterActor, so you should read the relative documentation
* inside the #ClutterActorClass.get_preferred_width() virtual function and * forr subclassing #ClutterActor.
* clutter_layout_manager_get_preferred_height() inside the
* #ClutterActorClass.get_preferred_height() virtual functions implementation.
* You should also call clutter_layout_manager_allocate() inside the
* implementation of the #ClutterActorClass.allocate() virtual function.</para>
* <para>In order to receive notifications for changes in the layout
* manager policies you should also connect to the
* #ClutterLayoutManager::layout-changed signal and queue a relayout
* on your actor. The following code should be enough if the actor
* does not need to perform specific operations whenever a layout
* manager changes:</para>
* <informalexample><programlisting>
* g_signal_connect_swapped (layout_manager,
* "layout-changed",
* G_CALLBACK (clutter_actor_queue_relayout),
* actor);
* </programlisting></informalexample>
* </refsect2>
* *
* <refsect2 id="ClutterLayoutManager-implementation"> * The layout manager implementation can hold a back pointer to the
* <title>Implementing a ClutterLayoutManager</title> * #ClutterContainer by implementing the #ClutterLayoutManagerClass.set_container()
* <para>The implementation of a layout manager does not differ from * virtual function. The layout manager should not hold a real reference (i.e.
* the implementation of the size requisition and allocation bits of * call g_object_ref()) on the container actor, to avoid reference cycles.
* #ClutterActor, so you should read the relative documentation
* <link linkend="clutter-subclassing-ClutterActor">for subclassing
* ClutterActor</link>.</para>
* <para>The layout manager implementation can hold a back pointer
* to the #ClutterContainer by implementing the
* <function>set_container()</function> virtual function. The layout manager
* should not hold a real reference (i.e. call g_object_ref()) on the
* container actor, to avoid reference cycles.</para>
* <para>If a layout manager has properties affecting the layout
* policies then it should emit the #ClutterLayoutManager::layout-changed
* signal on itself by using the clutter_layout_manager_layout_changed()
* function whenever one of these properties changes.</para>
* </refsect2>
* *
* <refsect2 id="ClutterLayoutManager-animation"> * If a layout manager has properties affecting the layout policies then it should
* <title>Animating a ClutterLayoutManager</title> * emit the #ClutterLayoutManager::layout-changed signal on itself by using the
* <para>A layout manager is used to let a #ClutterContainer take complete * clutter_layout_manager_layout_changed() function whenever one of these properties
* ownership over the layout (that is: the position and sizing) of its * changes.
* children; this means that using the Clutter animation API, like
* clutter_actor_animate(), to animate the position and sizing of a child of
* a layout manager it is not going to work properly, as the animation will
* automatically override any setting done by the layout manager
* itself.</para>
* <para>It is possible for a #ClutterLayoutManager sub-class to animate its
* children layout by using the base class animation support. The
* #ClutterLayoutManager animation support consists of three virtual
* functions: #ClutterLayoutManagerClass.begin_animation(),
* #ClutterLayoutManagerClass.get_animation_progress(), and
* #ClutterLayoutManagerClass.end_animation().</para>
* <variablelist>
* <varlistentry>
* <term><function>begin_animation (duration, easing)</function></term>
* <listitem><para>This virtual function is invoked when the layout
* manager should begin an animation. The implementation should set up
* the state for the animation and create the ancillary objects for
* animating the layout. The default implementation creates a
* #ClutterTimeline for the given duration and a #ClutterAlpha binding
* the timeline to the given easing mode. This function returns a
* #ClutterAlpha which should be used to control the animation from
* the caller perspective.</para></listitem>
* </varlistentry>
* <varlistentry>
* <term><function>get_animation_progress()</function></term>
* <listitem><para>This virtual function should be invoked when animating
* a layout manager. It returns the progress of the animation, using the
* same semantics as the #ClutterAlpha:alpha value.</para></listitem>
* </varlistentry>
* <varlistentry>
* <term><function>end_animation()</function></term>
* <listitem><para>This virtual function is invoked when the animation of
* a layout manager ends, and it is meant to be used for bookkeeping the
* objects created in the <function>begin_animation()</function>
* function. The default implementation will call it implicitly when the
* timeline is complete.</para></listitem>
* </varlistentry>
* </variablelist>
* <para>The simplest way to animate a layout is to create a #ClutterTimeline
* inside the <function>begin_animation()</function> virtual function, along
* with a #ClutterAlpha, and for each #ClutterTimeline::new-frame signal
* emission call clutter_layout_manager_layout_changed(), which will cause a
* relayout. The #ClutterTimeline::completed signal emission should cause
* clutter_layout_manager_end_animation() to be called. The default
* implementation provided internally by #ClutterLayoutManager does exactly
* this, so most sub-classes should either not override any animation-related
* virtual function or simply override #ClutterLayoutManagerClass.begin_animation()
* and #ClutterLayoutManagerClass.end_animation() to set up ad hoc state, and then
* chain up to the parent's implementation.</para>
* <example id="example-ClutterLayoutManager-animation">
* <title>Animation of a Layout Manager</title>
* <para>The code below shows how a #ClutterLayoutManager sub-class should
* provide animating the allocation of its children from within the
* #ClutterLayoutManagerClass.allocate() virtual function implementation. The
* animation is computed between the last stable allocation performed
* before the animation started and the desired final allocation.</para>
* <para>The <varname>is_animating</varname> variable is stored inside the
* #ClutterLayoutManager sub-class and it is updated by overriding the
* #ClutterLayoutManagerClass.begin_animation() and the
* #ClutterLayoutManagerClass.end_animation() virtual functions and chaining up
* to the base class implementation.</para>
* <para>The last stable allocation is stored within a #ClutterLayoutMeta
* sub-class used by the implementation.</para>
* <programlisting>
* static void
* my_layout_manager_allocate (ClutterLayoutManager *manager,
* ClutterContainer *container,
* const ClutterActorBox *allocation,
* ClutterAllocationFlags flags)
* {
* MyLayoutManager *self = MY_LAYOUT_MANAGER (manager);
* ClutterActor *child;
* *
* for (child = clutter_actor_get_first_child (CLUTTER_ACTOR (container)); * ## Layout Properties
* child != NULL;
* child = clutter_actor_get_next_sibling (child))
* {
* ClutterLayoutMeta *meta;
* MyLayoutMeta *my_meta;
* *
* /&ast; retrieve the layout meta-object &ast;/ * If a layout manager has layout properties, that is properties that
* meta = clutter_layout_manager_get_child_meta (manager, * should exist only as the result of the presence of a specific (layout
* container, * manager, container actor, child actor) combination, and it wishes to store
* child); * those properties inside a #ClutterLayoutMeta, then it should override the
* my_meta = MY_LAYOUT_META (meta); * #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; * ClutterLayoutManagerClass *klass;
* GType meta_type; * GType meta_type;
* *
@ -270,22 +79,23 @@
* "container", container, * "container", container,
* "actor", actor, * "actor", actor,
* NULL); * 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"> * Where `manager` is the #ClutterLayoutManager, `container` is the
* <title>Using ClutterLayoutManager with ClutterScript</title> * #ClutterContainer using the #ClutterLayoutManager, and `actor` is
* <para>#ClutterLayoutManager instance can be created in the same way * the #ClutterActor child of the #ClutterContainer.
* as other objects in #ClutterScript; properties can be set using the *
* common syntax.</para> * ## Using ClutterLayoutManager with ClutterScript
* <para>Layout properties can be set on children of a container with *
* a #ClutterLayoutManager using the <emphasis>layout::</emphasis> * #ClutterLayoutManager instances can be created in the same way
* modifier on the property name, for instance:</para> * as other objects in #ClutterScript; properties can be set using the
* <informalexample><programlisting> * 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", * "type" : "ClutterBox",
* "layout-manager" : { "type" : "ClutterTableLayout" }, * "layout-manager" : { "type" : "ClutterTableLayout" },
@ -314,8 +124,7 @@
* } * }
* ] * ]
* } * }
* </programlisting></informalexample> * ]|
* </refsect2>
* *
* #ClutterLayoutManager is available since Clutter 1.2 * #ClutterLayoutManager is available since Clutter 1.2
*/ */

140
clutter/clutter-main.c
View file

@ -23,70 +23,28 @@
/** /**
* SECTION:clutter-main * 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 to retrieve various global Clutter resources and other utility
* functions for mainloops, events and threads * functions for mainloops, events and threads
* *
* <refsect2 id="clutter-Threading-Model"> * ## The 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);
* *
* /&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;/ * The only safe and portable way to use the Clutter API in a multi-threaded
* clutter_threads_enter (); * 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;/ * The common pattern for using threads with Clutter is to use worker threads
* clutter_main (); * 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;/ * For a working example of how to use a worker thread to update the UI, see
* clutter_threads_leave (); * [threads.c](https://git.gnome.org/browse/clutter/tree/examples/threads.c?h=clutter-1.18)
*
* /&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>
*/ */
#ifdef HAVE_CONFIG_H #ifdef HAVE_CONFIG_H
@ -556,12 +514,10 @@ clutter_redraw (ClutterStage *stage)
* all #ClutterStage<!-- -->s managed by Clutter. * all #ClutterStage<!-- -->s managed by Clutter.
* *
* If @enable is %FALSE the following events will not work: * If @enable is %FALSE the following events will not work:
* <itemizedlist> *
* <listitem><para>ClutterActor::motion-event, unless on the * - ClutterActor::motion-event, except on the #ClutterStage
* #ClutterStage</para></listitem> * - ClutterActor::enter-event
* <listitem><para>ClutterActor::enter-event</para></listitem> * - ClutterActor::leave-event
* <listitem><para>ClutterActor::leave-event</para></listitem>
* </itemizedlist>
* *
* Since: 0.6 * Since: 0.6
* *
@ -1110,13 +1066,13 @@ _clutter_threads_dispatch_free (gpointer data)
* SafeClosure *closure = data; * SafeClosure *closure = data;
* gboolean res = FALSE; * gboolean res = FALSE;
* *
* /&ast; mark the critical section &ast;/ * // mark the critical section //
* *
* clutter_threads_enter(); * clutter_threads_enter();
* *
* /&ast; the callback does not need to acquire the Clutter * // the callback does not need to acquire the Clutter
* &ast; lock itself, as it is held by the this proxy handler * / lock itself, as it is held by the this proxy handler
* &ast;/ * //
* res = closure->callback (closure->data); * res = closure->callback (closure->data);
* *
* clutter_threads_leave(); * clutter_threads_leave();
@ -1129,8 +1085,8 @@ _clutter_threads_dispatch_free (gpointer data)
* { * {
* SafeClosure *closure = g_new0 (SafeClosure, 1); * SafeClosure *closure = g_new0 (SafeClosure, 1);
* *
* closure-&gt;callback = callback; * closure->callback = callback;
* closure-&gt;data = data; * closure->data = data;
* *
* return g_idle_add_full (G_PRIORITY_DEFAULT_IDLE, * return g_idle_add_full (G_PRIORITY_DEFAULT_IDLE,
* idle_safe_callback, * idle_safe_callback,
@ -1151,24 +1107,24 @@ _clutter_threads_dispatch_free (gpointer data)
* { * {
* SomeClosure *closure = data; * SomeClosure *closure = data;
* *
* /&ast; it is safe to call Clutter API from this function because * // it is safe to call Clutter API from this function because
* &ast; it is invoked from the same thread that started the main * / it is invoked from the same thread that started the main
* &ast; loop and under the Clutter thread lock * / loop and under the Clutter thread lock
* &ast;/ * //
* clutter_label_set_text (CLUTTER_LABEL (closure-&gt;label), * clutter_label_set_text (CLUTTER_LABEL (closure->label),
* closure-&gt;text); * closure->text);
* *
* g_object_unref (closure-&gt;label); * g_object_unref (closure->label);
* g_free (closure); * g_free (closure);
* *
* return FALSE; * return FALSE;
* } * }
* *
* /&ast; within another thread &ast;/ * // within another thread //
* closure = g_new0 (SomeClosure, 1); * closure = g_new0 (SomeClosure, 1);
* /&ast; always take a reference on GObject instances &ast;/ * // always take a reference on GObject instances //
* closure-&gt;label = g_object_ref (my_application-&gt;label); * closure->label = g_object_ref (my_application->label);
* closure-&gt;text = g_strdup (processed_text_to_update_the_label); * closure->text = g_strdup (processed_text_to_update_the_label);
* *
* clutter_threads_add_idle_full (G_PRIORITY_HIGH_IDLE, * clutter_threads_add_idle_full (G_PRIORITY_HIGH_IDLE,
* update_ui, * update_ui,
@ -1809,13 +1765,13 @@ post_parse_hook (GOptionContext *context,
* *
* |[ * |[
* g_option_context_set_main_group (context, clutter_get_option_group ()); * 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: * is functionally equivalent to:
* *
* |[ * |[
* clutter_init (&amp;argc, &amp;argv); * clutter_init (&argc, &argv);
* ]| * ]|
* *
* After g_option_context_parse() on a #GOptionContext containing the * 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 * the #GOptionGroup returned by this function requires a subsequent explicit
* call to clutter_init(); use this function when needing to set foreign * call to clutter_init(); use this function when needing to set foreign
* display connection with clutter_x11_set_display(), or with * 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 * Return value: (transfer full): a #GOptionGroup for the commandline arguments
* recognized by Clutter * recognized by Clutter
@ -2050,12 +2006,12 @@ clutter_parse_args (int *argc,
* *
* It is safe to call this function multiple times. * 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 * initialization; clutter_init() will print out the error message on
* stderr, and will return an error code. It is up to the application * 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 * 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 * 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 * If this function fails, and returns an error code, any subsequent
* Clutter API will have undefined behaviour - including segmentation * 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 * 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. * 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; * done by Clutter. Pointer grabs should only be used as a last resource;
* using the #ClutterActor::captured-event signal should always be the * 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. * This function should rarely be used.
* *
@ -3878,20 +3834,20 @@ _clutter_context_get_motion_events_enabled (void)
* windowing system; for instance: * windowing system; for instance:
* *
* |[ * |[
* &num;ifdef CLUTTER_WINDOWING_X11 * #ifdef CLUTTER_WINDOWING_X11
* if (clutter_check_windowing_backend (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 * else
* &num;endif * #endif
* &num;ifdef CLUTTER_WINDOWING_WIN32 * #ifdef CLUTTER_WINDOWING_WIN32
* if (clutter_check_windowing_backend (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 * else
* &num;endif * #endif
* g_error ("Unknown Clutter backend."); * g_error ("Unknown Clutter backend.");
* ]| * ]|
* *

70
clutter/clutter-model.c
View file

@ -37,8 +37,11 @@
* The #ClutterModel class is a list model which can accept most GObject * The #ClutterModel class is a list model which can accept most GObject
* types as a column type. * types as a column type.
* *
* Creating a simple clutter model: * ## Creating a simple ClutterModel
* <informalexample><programlisting> *
* The example below shows how to create a simple list model.
*
* |[<!-- language="C" -->
* enum * enum
* { * {
* COLUMN_INT, * COLUMN_INT,
@ -51,10 +54,10 @@
* ClutterModel *model; * ClutterModel *model;
* gint i; * gint i;
* *
* model = clutter_model_default_new (N_COLUMNS, * model = clutter_list_model_new (N_COLUMNS,
* /<!-- -->* column type, column title *<!-- -->/ * // column type, title
* G_TYPE_INT, "my integers", * G_TYPE_INT, "my integers",
* G_TYPE_STRING, "my strings"); * G_TYPE_STRING, "my strings");
* for (i = 0; i < 10; i++) * for (i = 0; i < 10; i++)
* { * {
* gchar *string = g_strdup_printf ("String %d", 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 * Iterating through the model consists of retrieving a new #ClutterModelIter
* pointing to the starting row, and calling clutter_model_iter_next() or * 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 * after the last row. In an empty sequence, the first and last iterators are
* the same. * the same.
* *
* Iterating a #ClutterModel: * |[<!-- language="C" -->
* <informalexample><programlisting>
* enum * enum
* { * {
* COLUMN_INT, * COLUMN_INT,
@ -93,10 +97,10 @@
* ClutterModel *model; * ClutterModel *model;
* ClutterModelIter *iter = NULL; * ClutterModelIter *iter = NULL;
* *
* /<!-- -->* Fill the model *<!-- -->/ * // fill the model
* model = populate_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); * iter = clutter_model_get_first_iter (model);
* while (!clutter_model_iter_is_last (iter)) * while (!clutter_model_iter_is_last (iter))
* { * {
@ -105,32 +109,33 @@
* iter = clutter_model_iter_next (iter); * iter = clutter_model_iter_next (iter);
* } * }
* *
* /<!-- -->* Make sure to unref the iter *<!-- -->/ * // Make sure to unref the iter
* g_object_unref (iter); * g_object_unref (iter);
* } * }
* </programlisting></informalexample> * ]|
* *
* #ClutterModel is an abstract class. Clutter provides a list model * #ClutterModel is an abstract class. Clutter provides a list model
* implementation called #ClutterListModel which has been optimised * implementation called #ClutterListModel which has been optimised
* for insertion and look up in sorted lists. * for insertion and look up in sorted lists.
* *
* <refsect2 id="ClutterModel-script"> * #ClutterModel is available since Clutter 0.6
* <title>ClutterModel custom properties for #ClutterScript</title> *
* <para>#ClutterModel defines a custom property "columns" for #ClutterScript * ## ClutterModel custom properties for ClutterScript
* which allows defining the column names and types. It also defines a custom *
* "rows" property which allows filling the #ClutterModel with some * #ClutterModel defines a custom property "columns" for #ClutterScript
* data.</para> * which allows defining the column names and types. It also defines a custom
* <example id="ClutterModel-script-example"> * "rows" property which allows filling the #ClutterModel with some
* <title>Example of the "columns" and "rows" custom properties</title> * data.
* <para>The definition below will create a #ClutterListModel with three *
* columns: the first one with name "Name" and containing strings; the * The definition below will create a #ClutterListModel with three
* second one with name "Score" and containing integers; the third one with * columns: the first one with name "Name" and containing strings; the
* name "Icon" and containing #ClutterTexture<!-- -->s. The model is filled * second one with name "Score" and containing integers; the third one with
* with three rows. A row can be defined either with an array that holds * name "Icon" and containing #ClutterTextures. The model is filled
* all columns of a row, or an object that holds "column-name" : * with three rows. A row can be defined either with an array that holds
* "column-value" pairs. * all columns of a row, or an object that holds "column-name" :
* </para> * "column-value" pairs.
* <programlisting> *
* |[
* { * {
* "type" : "ClutterListModel", * "type" : "ClutterListModel",
* "id" : "teams-model", * "id" : "teams-model",
@ -145,11 +150,6 @@
* { "Name" : "Team 3", "Icon" : "team3-icon-script-id" } * { "Name" : "Team 3", "Icon" : "team3-icon-script-id" }
* ] * ]
* } * }
* </programlisting>
* </example>
* </refsect2>
*
* #ClutterModel is available since Clutter 0.6
*/ */

41
clutter/clutter-offscreen-effect.c
View file

@ -40,25 +40,26 @@
* offscreen framebuffer, the redirection and the final paint of the texture on * offscreen framebuffer, the redirection and the final paint of the texture on
* the desired stage. * 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 * #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 #ifdef HAVE_CONFIG_H
@ -596,7 +597,7 @@ clutter_offscreen_effect_create_texture (ClutterOffscreenEffect *effect,
* paint the actor to which it has been applied. * paint the actor to which it has been applied.
* *
* This function should only be called by #ClutterOffscreenEffect * 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. * virtual function.
* *
* Return value: %TRUE if the offscreen buffer has a valid size, * 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. * paint the actor to which it has been applied.
* *
* This function should only be called by #ClutterOffscreenEffect * 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. * virtual function.
* *
* Return value: %TRUE if the offscreen buffer has a valid rectangle, * Return value: %TRUE if the offscreen buffer has a valid rectangle,

64
clutter/clutter-paint-volume.c
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 * around the volume. It returns the size of that bounding box as
* measured along the x-axis. * 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 * is used to transform a 2D child actor that is 100px wide, 100px
* high and 0px deep into container coordinates then the width might * 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 * not simply be 100px if the child actor has a 3D rotation applied to
* it.</para> * it.
* <para>Remember; after clutter_actor_get_transformed_paint_volume() is *
* Remember: if clutter_actor_get_transformed_paint_volume() is
* used then a transformed child volume will be defined relative to the * used then a transformed child volume will be defined relative to the
* ancestor container actor and so a 2D child actor * ancestor container actor and so a 2D child actor can have a 3D
* can have a 3D bounding volume.</para></note> * bounding volume.
* *
* <note>There are no accuracy guarantees for the reported width, * There are no accuracy guarantees for the reported width,
* except that it must always be >= to the true width. This is * except that it must always be greater than, or equal to, the
* because actors may report simple, loose fitting paint-volumes * actor's width. This is because actors may report simple, loose
* for efficiency</note> * fitting paint volumes for efficiency.
* Return value: the width, in units of @pv's local coordinate system. * 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 * around the volume. It returns the size of that bounding box as
* measured along the y-axis. * 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 * is used to transform a 2D child actor that is 100px wide, 100px
* high and 0px deep into container coordinates then the height might * 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 * not simply be 100px if the child actor has a 3D rotation applied to
* it.</para> * it.
* <para>Remember; after clutter_actor_get_transformed_paint_volume() is *
* Remember: if clutter_actor_get_transformed_paint_volume() is
* used then a transformed child volume will be defined relative to the * used then a transformed child volume will be defined relative to the
* ancestor container actor and so a 2D child actor * 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, * There are no accuracy guarantees for the reported height,
* except that it must always be >= to the true height. This is * except that it must always be greater than, or equal to, the actor's
* because actors may report simple, loose fitting paint-volumes * height. This is because actors may report simple, loose fitting paint
* for efficiency</note> * volumes for efficiency.
* *
* Return value: the height, in units of @pv's local coordinate system. * 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 * around the volume. It returns the size of that bounding box as
* measured along the z-axis. * 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 * is used to transform a 2D child actor that is 100px wide, 100px
* high and 0px deep into container coordinates then the depth might * 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 * not simply be 0px if the child actor has a 3D rotation applied to
* it.</para> * it.
* <para>Remember; after clutter_actor_get_transformed_paint_volume() is *
* Remember: if clutter_actor_get_transformed_paint_volume() is
* used then the transformed volume will be defined relative to the * used then the transformed volume will be defined relative to the
* container actor and in container coordinates a 2D child actor * 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, * There are no accuracy guarantees for the reported depth,
* except that it must always be >= to the true depth. This is * except that it must always be greater than, or equal to, the actor's
* because actors may report simple, loose fitting paint-volumes * depth. This is because actors may report simple, loose fitting paint
* for efficiency.</note> * volumes for efficiency.
* *
* Return value: the depth, in units of @pv's local coordinate system. * 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. * Updates the geometry of @pv to encompass @pv and @another_pv.
* *
* <note>There are no guarantees about how precisely the two volumes * There are no guarantees about how precisely the two volumes
* will be encompassed.</note> * will be unioned.
* *
* Since: 1.6 * Since: 1.6
*/ */
@ -743,9 +746,10 @@ _clutter_paint_volume_complete (ClutterPaintVolume *pv)
* the paint volume into window coordinates before getting * the paint volume into window coordinates before getting
* the 2D bounding box. * the 2D bounding box.
* *
* <note>The coordinates of the returned box are not clamped to * The coordinates of the returned box are not clamped to
* integer pixel values, if you need them to be clamped you can use * integer pixel values; if you need them to be rounded to the
* clutter_actor_box_clamp_to_pixel()</note> * nearest integer pixel values, you can use the
* clutter_actor_box_clamp_to_pixel() function.
* *
* Since: 1.6 * Since: 1.6
*/ */

67
clutter/clutter-path.c
View file

@ -33,32 +33,19 @@
* The path consists of a series of nodes. Each node is one of the * The path consists of a series of nodes. Each node is one of the
* following four types: * following four types:
* *
* <variablelist> * - %CLUTTER_PATH_MOVE_TO, changes the position of the path to the
* <varlistentry><term>%CLUTTER_PATH_MOVE_TO</term> * given pair of coordinates. This is usually used as the first node
* <listitem><para> * of a path to mark the start position. If it is used in the middle
* Changes the position of the path to the given pair of * of a path then the path will be disjoint and the actor will appear
* coordinates. This is usually used as the first node of a path to * to jump to the new position when animated.
* mark the start position. If it is used in the middle of a path then * - %CLUTTER_PATH_LINE_TO, creates a straight line from the previous
* the path will be disjoint and the actor will appear to jump to the * point to the given point.
* new position when animated. * - %CLUTTER_PATH_CURVE_TO, creates a bezier curve. The end of the
* </para></listitem></varlistentry> * last node is used as the first control point and the three
* <varlistentry><term>%CLUTTER_PATH_LINE_TO</term> * subsequent coordinates given in the node as used as the other three.
* <listitem><para> * -%CLUTTER_PATH_CLOSE, creates a straight line from the last node to
* Creates a straight line from the previous point to the given point. * the last %CLUTTER_PATH_MOVE_TO node. This can be used to close a
* </para></listitem></varlistentry> * path so that it will appear as a loop when animated.
* <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>
* *
* The first three types have the corresponding relative versions * The first three types have the corresponding relative versions
* %CLUTTER_PATH_REL_MOVE_TO, %CLUTTER_PATH_REL_LINE_TO and * %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 * coordinates. The coordinates can be separated by spaces or a
* comma. The types are: * comma. The types are:
* *
* <variablelist> * - `M`: Adds a %CLUTTER_PATH_MOVE_TO node. Takes one pair of coordinates.
* <varlistentry><term>M</term> * - `L`: Adds a %CLUTTER_PATH_LINE_TO node. Takes one pair of coordinates.
* <listitem><para> * - `C`: Adds a %CLUTTER_PATH_CURVE_TO node. Takes three pairs of coordinates.
* Adds a %CLUTTER_PATH_MOVE_TO node. Takes one pair of coordinates. * - `z`: Adds a %CLUTTER_PATH_CLOSE node. No coordinates are needed.
* </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>
* *
* The M, L and C commands can also be specified in lower case which * The M, L and C commands can also be specified in lower case which
* means the coordinates are relative to the previous node. * 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 * 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: * 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 * 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 * If the path description isn't valid %FALSE will be returned and no
* nodes will be added. * nodes will be added.

10
clutter/clutter-script.c
View file

@ -756,15 +756,15 @@ clutter_script_get_objects_valist (ClutterScript *script,
* names/return location pairs should be listed, with a %NULL pointer * names/return location pairs should be listed, with a %NULL pointer
* ending the list, like: * ending the list, like:
* *
* <informalexample><programlisting> * |[
* GObject *my_label, *a_button, *main_timeline; * GObject *my_label, *a_button, *main_timeline;
* *
* clutter_script_get_objects (script, * clutter_script_get_objects (script,
* "my-label", &amp;my_label, * "my-label", &my_label,
* "a-button", &amp;a_button, * "a-button", &a_button,
* "main-timeline", &amp;main_timeline, * "main-timeline", &main_timeline,
* NULL); * NULL);
* </programlisting></informalexample> * ]|
* *
* Note: This function does not increment the reference count of the * Note: This function does not increment the reference count of the
* returned objects. * returned objects.

9
clutter/clutter-scroll-actor.c
View file

@ -36,13 +36,8 @@
* #ClutterScrollActor does not provide pointer or keyboard event handling, * #ClutterScrollActor does not provide pointer or keyboard event handling,
* nor does it provide visible scroll handles. * nor does it provide visible scroll handles.
* *
* <informalexample> * See [scroll-actor.c](https://git.gnome.org/browse/clutter/tree/examples/scroll-actor.c?h=clutter-1.18)
* <programlisting> * for an example of how to use #ClutterScrollActor.
* <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>
* *
* #ClutterScrollActor is available since Clutter 1.12. * #ClutterScrollActor is available since Clutter 1.12.
*/ */

24
clutter/clutter-settings.c
View file

@ -600,12 +600,11 @@ clutter_settings_class_init (ClutterSettingsClass *klass)
* *
* The style of the hinting used when rendering text. Valid values * The style of the hinting used when rendering text. Valid values
* are: * are:
* <itemizedlist> *
* <listitem><simpara>hintnone</simpara></listitem> * - hintnone
* <listitem><simpara>hintslight</simpara></listitem> * - hintslight
* <listitem><simpara>hintmedium</simpara></listitem> * - hintmedium
* <listitem><simpara>hintfull</simpara></listitem> * - hintfull
* </itemizedlist>
* *
* Since: 1.4 * Since: 1.4
*/ */
@ -621,13 +620,12 @@ clutter_settings_class_init (ClutterSettingsClass *klass)
* *
* The type of sub-pixel antialiasing used when rendering text. Valid * The type of sub-pixel antialiasing used when rendering text. Valid
* values are: * values are:
* <itemizedlist> *
* <listitem><simpara>none</simpara></listitem> * - none
* <listitem><simpara>rgb</simpara></listitem> * - rgb
* <listitem><simpara>bgr</simpara></listitem> * - bgr
* <listitem><simpara>vrgb</simpara></listitem> * - vrgb
* <listitem><simpara>vbgr</simpara></listitem> * - vbgr
* </itemizedlist>
* *
* Since: 1.4 * Since: 1.4
*/ */

100
clutter/clutter-shader-effect.c
View file

@ -34,35 +34,43 @@
* GLSL shader (after checking whether the compilation and linking were * GLSL shader (after checking whether the compilation and linking were
* successfull) to the buffer before painting it on screen. * successfull) to the buffer before painting it on screen.
* *
* <refsect2 id="ClutterShaderEffect-implementing"> * #ClutterShaderEffect is available since Clutter 1.4
* <title>Implementing a ClutterShaderEffect</title> *
* <para>Creating a sub-class of #ClutterShaderEffect requires the * ## Implementing a ClutterShaderEffect
* overriding of the #ClutterOffscreenEffectClass.paint_target() virtual *
* function from the #ClutterOffscreenEffect class as well as the * Creating a sub-class of #ClutterShaderEffect requires the
* <function>get_static_shader_source()</function> virtual from the * overriding of the #ClutterOffscreenEffectClass.paint_target() virtual
* #ClutterShaderEffect class.</para> * function from the #ClutterOffscreenEffect class. It is also convenient
* <para>The #ClutterShaderEffectClass.get_static_shader_source() * to implement the #ClutterShaderEffectClass.get_static_shader_source()
* function should return a copy of the shader source to use. This * virtual function in case you are planning to create more than one
* function is only called once per subclass of #ClutterShaderEffect * instance of the effect.
* regardless of how many instances of the effect are created. The *
* source for the shader is typically stored in a static const * The #ClutterShaderEffectClass.get_static_shader_source()
* string which is returned from this function via * function should return a copy of the shader source to use. This
* g_strdup().</para> * function is only called once per subclass of #ClutterShaderEffect
* <para>The <function>paint_target()</function> should set the * regardless of how many instances of the effect are created. The
* shader's uniforms if any. This is done by calling * source for the shader is typically stored in a static const
* clutter_shader_effect_set_uniform_value() or * string which is returned from this function via
* clutter_shader_effect_set_uniform(). The sub-class should then * g_strdup().
* chain up to the #ClutterShaderEffect implementation.</para> *
* <example id="ClutterShaderEffect-example-uniforms"> * The #ClutterOffscreenEffectClass.paint_target() should set the
* <title>Setting uniforms on a ClutterShaderEffect</title> * shader's uniforms if any. This is done by calling
* <para>The example below shows a typical implementation of the * clutter_shader_effect_set_uniform_value() or
* <function>get_static_shader_source()</function> and * clutter_shader_effect_set_uniform(). The sub-class should then
* <function>paint_target()</function> phases of a * chain up to the #ClutterShaderEffect implementation.
* #ClutterShaderEffect sub-class.</para> *
* <programlisting> * ## 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 * * static gchar *
* my_effect_get_static_shader_source (ClutterShaderEffect *effect) * my_effect_get_static_shader_source (ClutterShaderEffect *effect)
* { * {
* // shader_source is set elsewhere
* return g_strdup (shader_source); * return g_strdup (shader_source);
* } * }
* *
@ -74,21 +82,19 @@
* ClutterEffectClass *parent_class; * ClutterEffectClass *parent_class;
* gfloat component_r, component_g, component_b; * gfloat component_r, component_g, component_b;
* *
* /&ast; the "tex" uniform is declared in the shader as: * // the "tex" uniform is declared in the shader as:
* &ast; * //
* &ast; uniform int tex; * // uniform int tex;
* &ast; * //
* &ast; and it is passed a constant value of 0 * // and it is passed a constant value of 0
* &ast;/
* clutter_shader_effect_set_uniform (shader, "tex", G_TYPE_INT, 1, 0); * clutter_shader_effect_set_uniform (shader, "tex", G_TYPE_INT, 1, 0);
* *
* /&ast; the "component" uniform is declared in the shader as: * // the "component" uniform is declared in the shader as:
* &ast; * //
* &ast; uniform vec3 component; * // uniform vec3 component;
* &ast; * //
* &ast; and it's defined to contain the normalized components * // and it's defined to contain the normalized components
* &ast; of a #ClutterColor * // of a #ClutterColor
* &ast;/
* component_r = self->color.red / 255.0f; * component_r = self->color.red / 255.0f;
* component_g = self->color.green / 255.0f; * component_g = self->color.green / 255.0f;
* component_b = self->color.blue / 255.0f; * component_b = self->color.blue / 255.0f;
@ -98,15 +104,11 @@
* component_g, * component_g,
* component_b); * 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); * parent_class = CLUTTER_OFFSCREEN_EFFECT_CLASS (my_effect_parent_class);
* return parent_class->paint_target (effect); * return parent_class->paint_target (effect);
* } * }
* </programlisting> * ]|
* </example>
* </refsect2>
*
* #ClutterShaderEffect is available since Clutter 1.4
*/ */
#ifdef HAVE_CONFIG_H #ifdef HAVE_CONFIG_H
@ -805,7 +807,7 @@ add_uniform:
* argument, and by the @gtype argument. For instance, a uniform named * argument, and by the @gtype argument. For instance, a uniform named
* "sampler0" and containing a single integer value is set using: * "sampler0" and containing a single integer value is set using:
* *
* |[ * |[<!-- language="C" -->
* clutter_shader_effect_set_uniform (effect, "sampler0", * clutter_shader_effect_set_uniform (effect, "sampler0",
* G_TYPE_INT, 1, * G_TYPE_INT, 1,
* 0); * 0);
@ -814,7 +816,7 @@ add_uniform:
* While a uniform named "components" and containing a 3-elements vector * While a uniform named "components" and containing a 3-elements vector
* of floating point values (a "vec3") can be set using: * of floating point values (a "vec3") can be set using:
* *
* |[ * |[<!-- language="C" -->
* gfloat component_r, component_g, component_b; * gfloat component_r, component_g, component_b;
* *
* clutter_shader_effect_set_uniform (effect, "components", * clutter_shader_effect_set_uniform (effect, "components",
@ -826,7 +828,7 @@ add_uniform:
* *
* or can be set using: * or can be set using:
* *
* |[ * |[<!-- language="C" -->
* gfloat component_vec[3]; * gfloat component_vec[3];
* *
* clutter_shader_effect_set_uniform (effect, "components", * 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: * Finally, a uniform named "map" and containing a matrix can be set using:
* *
* |[ * |[<!-- language="C" -->
* clutter_shader_effect_set_uniform (effect, "map", * clutter_shader_effect_set_uniform (effect, "map",
* CLUTTER_TYPE_SHADER_MATRIX, 1, * CLUTTER_TYPE_SHADER_MATRIX, 1,
* cogl_matrix_get_array (&matrix)); * cogl_matrix_get_array (&matrix));

50
clutter/clutter-stage.c
View file

@ -2179,9 +2179,9 @@ clutter_stage_class_init (ClutterStageClass *klass)
* It is possible to override the default behaviour by connecting * It is possible to override the default behaviour by connecting
* a new handler and returning %TRUE there. * 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 * 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 * Since: 1.2
*/ */
@ -3194,29 +3194,29 @@ clutter_stage_set_use_fog (ClutterStage *stage,
* ClutterColor stage_color = { 0, }; * ClutterColor stage_color = { 0, };
* CoglColor fog_color = { 0, }; * CoglColor fog_color = { 0, };
* *
* /&ast; set the fog color to the stage background color &ast;/ * // set the fog color to the stage background color
* clutter_stage_get_color (CLUTTER_STAGE (actor), &amp;stage_color); * clutter_stage_get_color (CLUTTER_STAGE (actor), &stage_color);
* cogl_color_init_from_4ub (&amp;fog_color, * cogl_color_init_from_4ub (&fog_color,
* stage_color.red, * stage_color.red,
* stage_color.green, * stage_color.green,
* stage_color.blue, * stage_color.blue,
* stage_color.alpha); * stage_color.alpha);
* *
* /&ast; enable fog &ast;/ * // enable fog //
* cogl_set_fog (&amp;fog_color, * cogl_set_fog (&fog_color,
* COGL_FOG_MODE_EXPONENTIAL, /&ast; mode &ast;/ * COGL_FOG_MODE_EXPONENTIAL, // mode
* 0.5, /&ast; density &ast;/ * 0.5, // density
* 5.0, 30.0); /&ast; z_near and z_far &ast;/ * 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 * unmultiplied alpha colors. By default Cogl will premultiply textures and
* cogl_set_source_color() will premultiply colors, so unless you explicitly * cogl_set_source_color() will premultiply colors, so unless you explicitly
* load your textures requesting an unmultiplied internal format and use * load your textures requesting an unmultiplied internal format and use
* cogl_material_set_color() you can only use fogging with fully opaque actors. * 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 * Support for premultiplied colors will improve in the future when we can
* depend on fragment shaders.</note> * depend on fragment shaders.
* *
* Since: 0.6 * Since: 0.6
* *
@ -3616,8 +3616,8 @@ clutter_stage_ensure_redraw (ClutterStage *stage)
* *
* Queues a redraw for the passed stage. * Queues a redraw for the passed stage.
* *
* <note>Applications should call clutter_actor_queue_redraw() and not * Applications should call clutter_actor_queue_redraw() and not
* this function.</note> * this function.
* *
* Since: 0.8 * 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 * if the stage is always covered - for instance, in a full-screen
* video player or in a game with a background texture. * video player or in a game with a background texture.
* *
* <note><para>This setting is a hint; Clutter might discard this * This setting is a hint; Clutter might discard this hint
* hint depending on its internal state.</para></note> * depending on its internal state.
* *
* <warning><para>If parts of the stage are visible and you disable * If parts of the stage are visible and you disable clearing you
* clearing you might end up with visual artifacts while painting the * might end up with visual artifacts while painting the contents of
* contents of the stage.</para></warning> * the stage.
* *
* Since: 1.4 * Since: 1.4
*/ */
@ -4232,14 +4232,12 @@ clutter_stage_get_accept_focus (ClutterStage *stage)
* *
* The default is %TRUE. * The default is %TRUE.
* *
* If @enable is %FALSE the following events will not be delivered * If @enable is %FALSE the following signals will not be emitted
* to the actors children of @stage. * by the actors children of @stage:
* *
* <itemizedlist> * - #ClutterActor::motion-event
* <listitem><para>#ClutterActor::motion-event</para></listitem> * - #ClutterActor::enter-event
* <listitem><para>#ClutterActor::enter-event</para></listitem> * - #ClutterActor::leave-event
* <listitem><para>#ClutterActor::leave-event</para></listitem>
* </itemizedlist>
* *
* The events will still be delivered to the #ClutterStage. * The events will still be delivered to the #ClutterStage.
* *

2
clutter/clutter-test-utils.c
View file

@ -226,7 +226,7 @@ clutter_test_add_data_full (const char *test_path,
* int * int
* main (int argc, char *argv[]) * 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/foo", unit_foo);
* clutter_test_add ("/unit/bar", unit_bar); * clutter_test_add ("/unit/bar", unit_bar);

2
clutter/clutter-test-utils.h
View file

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

4
clutter/clutter-text.c
View file

@ -3709,10 +3709,10 @@ clutter_text_class_init (ClutterTextClass *klass)
* For more informations about the Pango markup format, see * For more informations about the Pango markup format, see
* pango_layout_set_markup() in the Pango documentation. * 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 * %TRUE and %FALSE. Once a string with markup has been set on
* a #ClutterText actor with :use-markup set to %TRUE, the markup * 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 * Since: 1.0
*/ */

47
clutter/clutter-timeline.c
View file

@ -19,8 +19,6 @@
* *
* You should have received a copy of the GNU Lesser General Public * 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/>. * License along with this library. If not, see <http://www.gnu.org/licenses/>.
*
*
*/ */
/** /**
@ -57,8 +55,8 @@
* its #ClutterTimeline:duration. * its #ClutterTimeline:duration.
* *
* It is possible to connect to specific points in the timeline progress by * It is possible to connect to specific points in the timeline progress by
* adding <emphasis>markers</emphasis> using clutter_timeline_add_marker_at_time() * adding markers using clutter_timeline_add_marker_at_time() and connecting
* and connecting to the #ClutterTimeline::marker-reached signal. * to the #ClutterTimeline::marker-reached signal.
* *
* Timelines can be made to loop once they reach the end of their duration, by * 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 * 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 * Timelines are used in the Clutter animation framework by classes like
* #ClutterAnimation, #ClutterAnimator, and #ClutterState. * #ClutterAnimation, #ClutterAnimator, and #ClutterState.
* *
* <refsect2 id="timeline-script"> * ## Defining Timelines in ClutterScript
* <title>Defining Timelines in ClutterScript</title> *
* <para>A #ClutterTimeline can be described in #ClutterScript like any * A #ClutterTimeline can be described in #ClutterScript like any
* other object. Additionally, it is possible to define markers directly * other object. Additionally, it is possible to define markers directly
* inside the JSON definition by using the <emphasis>markers</emphasis> * inside the JSON definition by using the `markers` JSON object member,
* JSON object member, such as:</para> * such as:
* <informalexample><programlisting><![CDATA[ *
* |[
{ {
"type" : "ClutterTimeline", "type" : "ClutterTimeline",
"duration" : 1000, "duration" : 1000,
@ -91,8 +90,7 @@
{ "name" : "three-quarters", "time" : 750 } { "name" : "three-quarters", "time" : 750 }
] ]
} }
* ]]></programlisting></informalexample> * ]|
* </refsect2>
*/ */
#ifdef HAVE_CONFIG_H #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 * Advance timeline to the requested point. The point is given as a
* time in milliseconds since the timeline started. * 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 * signal for the given time. The first ::new-frame signal after the call to
* clutter_timeline_advance() will be emit the skipped markers. * clutter_timeline_advance() will be emit the skipped markers.
* </para></note>
*/ */
void void
clutter_timeline_advance (ClutterTimeline *timeline, clutter_timeline_advance (ClutterTimeline *timeline,
@ -1423,15 +1420,15 @@ clutter_timeline_is_playing (ClutterTimeline *timeline)
* Create a new #ClutterTimeline instance which has property values * Create a new #ClutterTimeline instance which has property values
* matching that of supplied timeline. The cloned timeline will not * matching that of supplied timeline. The cloned timeline will not
* be started and will not be positioned to the current position of * 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> * The only cloned properties are:
* <itemizedlist> *
* <listitem><simpara>#ClutterTimeline:duration</simpara></listitem> * - #ClutterTimeline:duration
* <listitem><simpara>#ClutterTimeline:loop</simpara></listitem> * - #ClutterTimeline:loop
* <listitem><simpara>#ClutterTimeline:delay</simpara></listitem> * - #ClutterTimeline:delay
* <listitem><simpara>#ClutterTimeline:direction</simpara></listitem> * - #ClutterTimeline:direction
* </itemizedlist></note>
* *
* Return value: (transfer full): a new #ClutterTimeline, cloned * Return value: (transfer full): a new #ClutterTimeline, cloned
* from @timeline * from @timeline
@ -1934,10 +1931,10 @@ clutter_timeline_list_markers (ClutterTimeline *timeline,
* *
* Advances @timeline to the time of the given @marker_name. * 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 * emit the #ClutterTimeline::new-frame for the time where @marker_name
* is set, nor it will emit #ClutterTimeline::marker-reached for * is set, nor it will emit #ClutterTimeline::marker-reached for
* @marker_name.</para></note> * @marker_name.
* *
* Since: 0.8 * Since: 0.8
*/ */

4
clutter/clutter-types.h
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. * 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 * 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 * Deprecated: 1.16
*/ */

6
clutter/clutter-units.c
View file

@ -466,7 +466,7 @@ clutter_units_to_pixels (ClutterUnits *units)
* omg!1!ponies * 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, * Return value: %TRUE if the string was successfully parsed,
* and %FALSE otherwise * 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 * See clutter_units_from_string() for the units syntax and for
* examples of output * 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 * 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 * Return value: a newly allocated string containing the encoded
* #ClutterUnits value. Use g_free() to free the string * #ClutterUnits value. Use g_free() to free the string