2008-02-15 Emmanuele Bassi <ebassi@openedhand.com>

* clutter-animation.sgml: Fix some of the grammar; add a timeout-based
	animation example.

	* creating-your-own-behaviours.sgml: Fix some of the linking.

	* subclassing-ClutterActor.sgml: Remove the FIXMEs; add the initial
	structure of a section about containers.

doc/reference/ChangeLog

@@ -1,3 +1,13 @@
+2008-02-15  Emmanuele Bassi  <ebassi@openedhand.com>
+
+	* clutter-animation.sgml: Fix some of the grammar; add a timeout-based
+	animation example.
+
+	* creating-your-own-behaviours.sgml: Fix some of the linking.
+
+	* subclassing-ClutterActor.sgml: Remove the FIXMEs; add the initial
+	structure of a section about containers.
+
 2008-02-15  Emmanuele Bassi  <ebassi@openedhand.com>
 
 	* clutter-docs.sgml: Fix varlistentry usage.

doc/reference/clutter-animation.sgml

@@ -17,7 +17,7 @@
 
   With Clutter using hardware accelration for graphics rendering,
   complex and fast animations are possible. This chapter describes basic
-  techniques and the utilitys Clutter provides in aiding animation
+  techniques and the utilities Clutter provides in aiding animation
   creation.
 
   </para>
@@ -28,9 +28,9 @@
   <para>
 
    The most basic way to create animations with Clutter is via the use of
-   the <code>g_timeout_add</code>. This enables a callback function to be
+   g_timeout_add(). This enables a callback function to be called at a
-   called at a definefine interval. The callback function can then modify
+   defined interval. The callback function can then modify actors visual
-   actors visual properties as to produce an animation.
+   properties as to produce an animation.
 
   </para>
 
@@ -39,23 +39,46 @@
   Simple Rotation...
   </para>
   <programlisting>
+struct RotationClosure {
+  ClutterActor *actor;
+  ClutterFixed final_angle;
+  ClutterFixed current_angle;
+};
 
-  FIXME
+static gboolean
+rotate_actor (gpointer data)
+{
+  RotationClosure *clos = data;
 
-  guint g_timeout_add  (guint interval,
+  clutter_actor_set_rotationx (clos-&gt;actor, clos-&gt;current_angle, 0, 0, 0);
-                        GSourceFunc function,
-                        gpointer data);
 
+  clos-&gt;current_angle += CFX_ONE;
 
+  if (clos-&gt;current_angle == clos-&gt;final_angle)
+    return FALSE;
+
+  return TRUE;
+}
+
+...
+  RotationClosure clos = { NULL, }
+
+  clos.actor = an_actor;
+  clos.final_angle = CLUTTER_FLOAT_TO_FIXED (360.0);
+  clos.current_angle = 0;
+
+  g_timeout_add (1000 / 360, /* fps to interval in milliseconds */
+                 rotate_actor,
+                 &amp;clos);
   </programlisting>
   </example>
 
-  <note><title>Prioritys</title>
+  <note><title>Priorities</title>
   <para>
 
-  G_PRIORITY_DEFAULT should always be used as the timeouts priority
+  %G_PRIORITY_DEFAULT should always be used as the timeouts priority
-  (in case of g_timeout_add_full) as not to intefere with Clutters
+  (in case of g_timeout_add_full()) as not to intefere with Clutter's
-  schueduling of repaints and input event handling.
+  scheduling of repaints and input event handling.
 
   </para>
   </note>
@@ -214,7 +237,7 @@ main (int argc, char *argv[])
 
   </section>
   <section id="clutter-animation-behaviours">
-  <title>Timelines</title>
+  <title>Behaviours</title>
   <para>
 
   With a large application containing many animations, the use of just

doc/reference/creating-your-own-behaviours.sgml

@@ -27,46 +27,47 @@
   In order to implement a new #ClutterBehaviour subclass the usual
   machinery for subclassing a GObject should be used. The new subclass
   then just overides the ClutterBehaviour::alpha_notify() method. This
-  method is passed an alpha_value which is then used to computer
+  method is passed an alpha value which is then used to compute
   modifications to any actors the behaviour is applied to.
 
   </para>
 
   <example id="clutter-actor-query-coords-example">
-    <para>This example demonstrates a behaviour that produces a vertical 'wipe' like affect by modifying the actors clip region</para>
+    <para>This example demonstrates a behaviour that produces a vertical
+    'wipe' like affect by modifying the actors clip region</para>
 
     <programlisting>
 static void
 clutter_behaviour_foo_alpha_notify (ClutterBehaviour *behaviour,
                                     guint32           alpha_value)
 {
-  ClutterActor     *actor
+  ClutterActor *actor
-  gint              i, n;
+  gint          i, n;
-  gdouble           factor;
+  gdouble       factor;
 
   /* Normalise alpha value */
-  factor = (gdouble)alpha_value / CLUTTER_ALPHA_MAX_ALPHA;
+  factor = (gdouble) alpha_value / CLUTTER_ALPHA_MAX_ALPHA;
 
   n = clutter_behaviour_get_n_actors (behaviour);
 
   /* Change clip height of each applied actor. Note usually better to use
    * clutter_behaviour_actors_foreach () for performance reasons.
    */
-  for (i=0; i&lt;n; i++)
+  for (i = 0; i&lt;n; i++)
     {
       int clip_height;
 
       actor = clutter_behaviour_get_nth_actor (behaviour, i);
 
       clip_height = clutter_actor_get_height (actor)
-                      - (clutter_actor_get_height (actor) * factor);
+                    - (clutter_actor_get_height (actor) * factor);
 
       clutter_actor_set_clip (actor,
                               0,
                               0,
                               clutter_actor_get_width (actor),
                               clip_height);
-     }
+   }
 }
     </programlisting>
   </example>

doc/reference/subclassing-ClutterActor.sgml

@@ -13,19 +13,6 @@
 
   <title>Implementing a new actor</title>
 
-  <programlisting>
-  A few FIXMES:
-    - more on composite/container actors, when/why to use...
-      + implementaing a composite actor - set_parent() etc
-      + implementing a container - interface etc
-    - Painting
-      + note on cogl_enable if painting texture or blended item
-        (should at least call cogl_enable(0) - to reset state cache)
-      + fine to use regular GL but then wont be portable
-      + avoid further transforms ?     
-
-  </programlisting>
-
   <para>In order to implement a new #ClutterActor subclass the usual
   machinery for subclassing a GObject should be used. After that, the
   ClutterActor::query_coords() and ClutterActor::request_coords() virtual
@@ -138,6 +125,10 @@ foo_actor_paint (ClutterActor *actor)
     </programlisting>
   </example>
 
+  <para>When painting a blended actor, cogl_enable() should be called with
+  the %CGL_BLEND flag; or, alternatively, glEnable() with %GL_BLEND on
+  OpenGL.</para>
+
   <para>If the actor has a non-rectangular shape, or it has internal childrens
   that needs to be distinguished by the events delivery mechanism, the
   ClutterActor::pick() method should also be overridden. The ::pick() method
@@ -184,6 +175,96 @@ foo_actor_pick (ClutterActor       *actor,
     </programlisting>
   </example>
 
-  <para></para>
+  <section id="implementing-clutter-container">
+    <title>Implementing Containers</title>
+
+    <para>
+    The #ClutterContainer interface should be implemented by subclasses
+    of #ClutterActor who wants to provide a general API for adding child
+    actors.
+    </para>
+
+    <para>
+    If the #ClutterActor subclass only handles internal children, or it's
+    not suitable for having generic actors added to it, it should not
+    implement the #ClutterContainer interface, but simply use
+    clutter_actor_set_parent():
+    </para>
+
+    <example id="clutter-actor-set-parent-example">
+      <programlisting>
+void
+foo_actor_add_baz (FooActor *foo_actor,
+                   BazActor *baz_actor)
+{
+  g_return_if_fail (FOO_IS_ACTOR (foo_actor));
+  g_return_if_fail (BAZ_IS_ACTOR (baz_actor));
+
+  /* unparent the previous BazActor; this will automatically call
+   * g_object_unref() on the actor
+   */
+  if (foo_actor-&gt;baz)
+    clutter_actor_unparent (foo_actor-&gt;baz);
+
+  foo_actor->baz = baz_actor;
+
+  /* this will cause the initial floating reference to disappear,
+   * and add a new reference on baz_actor. foo_actor has now taken
+   * ownership of baz_actor
+   */
+  clutter_actor_set_parent (CLUTTER_ACTOR (baz_actor),
+                            CLUTTER_ACTOR (foo_actor));
+
+  g_signal_emit (foo_actor, foo_actor_signals[BAZ_CHANGED], 0, baz_actor);
+}
+      </programlisting>
+    </example>
+
+    <para>
+    In order to implement the #ClutterContainer interface, these virtual
+    functions must be defined:
+
+      <variablelist>
+        <varlistentry>
+          <term>ClutterContainer::add</term>
+          <listitem>
+            <para></para>
+          </listitem>
+        </varlistentry>
+        <varlistentry>
+          <term>ClutterContainer::remove</term>
+          <listitem>
+            <para></para>
+          </listitem>
+        </varlistentry>
+        <varlistentry>
+          <term>ClutterContainer::foreach</term>
+          <listitem>
+            <para></para>
+          </listitem>
+        </varlistentry>
+        <varlistentry>
+          <term>ClutterContainer::raise</term>
+          <listitem>
+            <para></para>
+          </listitem>
+        </varlistentry>
+        <varlistentry>
+          <term>ClutterContainer::lower</term>
+          <listitem>
+            <para></para>
+          </listitem>
+        </varlistentry>
+        <varlistentry>
+          <term>ClutterContainer::sort_depth_order</term>
+          <listitem>
+            <para></para>
+          </listitem>
+        </varlistentry>
+      </variablelist>
+
+    </para>
+
+  </section>
 
 </chapter>