2008-02-13 Matthew Allum <mallum@openedhand.com>

* Makefile.am:
        * clutter-docs.sgml:
        Add new appendix + FIXME for building
        * creating-your-own-behaviours.sgml:
        Add new initial doc on custom behaviour creation.
        * subclassing-ClutterActor.sgml:
        Add FIXME notes.

doc/reference/ChangeLog

@@ -1,3 +1,13 @@
+2008-02-13  Matthew Allum  <mallum@openedhand.com>
+
+	* Makefile.am:
+	* clutter-docs.sgml:
+        Add new appendix + FIXME for building
+	* creating-your-own-behaviours.sgml:
+        Add new initial doc on custom behaviour creation.
+	* subclassing-ClutterActor.sgml:
+        Add FIXME notes.
+
 2008-02-08  Emmanuele Bassi  <ebassi@openedhand.com>
 
 	* actor-box.png:

doc/reference/Makefile.am

@@ -92,6 +92,7 @@ HTML_IMAGES=\
 content_files= \
 	subclassing-ClutterActor.sgml \
         clutter-animation.sgml        \
+	creating-your-own-behaviours.sgml \
 	version.xml
 
 # SGML files where gtk-doc abbrevations (#GtkWidget) are expanded
@@ -99,7 +100,8 @@ content_files= \
 # e.g. expand_content_files=running.sgml
 expand_content_files= \
 	subclassing-ClutterActor.sgml \
-        clutter-animation.sgml
+        clutter-animation.sgml \
+	creating-your-own-behaviours.sgml
 
 # CFLAGS and LDFLAGS for compiling gtkdoc-scangobj with your library.
 # Only needed if you are using gtkdoc-scangobj to dynamically query widget

doc/reference/clutter-docs.sgml

@@ -4,6 +4,7 @@
 <!ENTITY version SYSTEM "version.xml">
 <!ENTITY clutter-SubclassingActor SYSTEM "xml/subclassing-ClutterActor.sgml">
 <!ENTITY clutter-animation SYSTEM "xml/clutter-animation.sgml">
+<!ENTITY creating-your-own-behaviours SYSTEM "xml/creating-your-own-behaviours.sgml">
 ]>
 
 <book id="index" xmlns:xi="http://www.w3.org/2003/XInclude">
@@ -106,6 +107,19 @@
     </partintro>
   </part>
 
+  <part id="clutterbuilding">
+    <title>Building Clutter</title>
+
+    <partintro>
+
+    <para>
+    FIXME: Linux, Windows, OSX. Embedded?
+    </para>
+
+    </partintro>
+  </part>
+
+
   <part id="clutterbase">
     <title>Clutter Core Reference</title>
 
@@ -224,6 +238,8 @@
 
     &clutter-animation;
 
+    &creating-your-own-behaviours;
+
   </part>
 
   <index>

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

@@ -0,0 +1,76 @@
+<chapter id="creating-your-own-behaviours">
+  <chapterinfo>
+    <author>
+      <firstname>Matthew</firstname>
+      <surname>Allum</surname>
+      <affiliation>
+        <address>
+          <email>mallum@openedhand.com</email>
+        </address>
+      </affiliation>
+    </author>
+  </chapterinfo>
+
+  <title>Creating You Own Behaviours</title>
+  <para>
+
+  Clutter comes with a number of fairly generic prebuilt behaviour
+  classes which provide a basis for transitions, animations and other
+  visual effects. However even with the ability to combine a number of
+  these behaviours sometimes they are not enough and a custom
+  behaviour is needed to create a spcific animation.
+
+  </para>
+
+  <para>
+
+  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
+  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>
+
+    <programlisting>
+static void
+clutter_behaviour_foo_alpha_notify (ClutterBehaviour *behaviour,
+                                    guint32           alpha_value)
+{
+  ClutterActor     *actor
+  gint              i, n;
+  gdouble           factor;
+
+  /* Normalise alpha value */
+  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++)
+    {
+      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_set_clip (actor,
+                              0,
+                              0,
+                              clutter_actor_get_width (actor),
+                              clip_height);
+     }
+}
+    </programlisting>
+  </example>
+
+  <para>
+  </para>
+</chapter>

doc/reference/subclassing-ClutterActor.sgml

@@ -13,6 +13,21 @@
 
   <title>Implementing a new actor</title>
 
+  <programlisting>
+  A few FIXMES:
+    - note use of units in sizing
+    - more on composite/container actors, when/why to use...
+      + implementaing a composite actor - set_parent() etc
+      + implementing a container - interface etc
+    - Painting
+      + note transform already applied. (including position, scale etc)
+      + 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