2007-06-16 Emmanuele Bassi <ebassi@openedhand.com>

	* subclassing-ClutterActor.sgml: Add a chapter about how to
	correctly subclass the actor base class.

	* clutter-docs.sgml: Include the new chapter about subclassing
	ClutterActor; add a description for some of the API reference
	parts.

diff --git a/doc/reference/ChangeLog b/doc/reference/ChangeLog
index 1ec9e69..25528e5 100644 (file)
--- a/doc/reference/ChangeLog
+++ b/doc/reference/ChangeLog
@@ -1,3 +1,12 @@
+2007-06-16  Emmanuele Bassi  <ebassi@openedhand.com>
+
+       * subclassing-ClutterActor.sgml: Add a chapter about how to
+       correctly subclass the actor base class.
+
+       * clutter-docs.sgml: Include the new chapter about subclassing
+       ClutterActor; add a description for some of the API reference
+       parts.
+
 2007-06-14  Emmanuele Bassi  <ebassi@openedhand.com>
 
        * clutter-sections.txt:

diff --git a/doc/reference/Makefile.am b/doc/reference/Makefile.am
index e1f39be..126b443 100644 (file)
--- a/doc/reference/Makefile.am
+++ b/doc/reference/Makefile.am
@@ -71,12 +71,15 @@ HTML_IMAGES=
 
 # Extra SGML files that are included by $(DOC_MAIN_SGML_FILE).
 # e.g. content_files=running.sgml building.sgml changes-2.0.sgml
-content_files= version.xml
+content_files= \
+       subclassing-ClutterActor.sgml \
+       version.xml
 
 # SGML files where gtk-doc abbrevations (#GtkWidget) are expanded
 # These files must be listed here *and* in content_files
 # e.g. expand_content_files=running.sgml
-expand_content_files=
+expand_content_files= \
+       subclassing-ClutterActor.sgml
 
 # CFLAGS and LDFLAGS for compiling gtkdoc-scangobj with your library.
 # Only needed if you are using gtkdoc-scangobj to dynamically query widget

diff --git a/doc/reference/clutter-docs.sgml b/doc/reference/clutter-docs.sgml
index f21870a..360eedf 100644 (file)
--- a/doc/reference/clutter-docs.sgml
+++ b/doc/reference/clutter-docs.sgml
@@ -2,6 +2,7 @@
 <!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN" 
                "http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd" [
 <!ENTITY version SYSTEM "version.xml">
+<!ENTITY clutter-SubclassingActor SYSTEM "xml/subclassing-ClutterActor.sgml">
 ]>
 
 <book id="index" xmlns:xi="http://www.w3.org/2003/XInclude">
@@ -93,6 +94,10 @@
 
     <chapter>
       <title>Container Actors</title>
+
+      <partintro>
+        <para>Actors containing other actors.</para>
+      </partintro>
       <xi:include href="xml/clutter-group.xml"/>
       <xi:include href="xml/clutter-hbox.xml"/>
       <xi:include href="xml/clutter-vbox.xml"/>
@@ -105,6 +110,11 @@
     
     <chapter>
       <title>Base Classes</title>
+
+      <partintro>
+        <para>Clutter base animation objects</para>
+      </partintro>
+
       <xi:include href="xml/clutter-timeline.xml"/>
       <xi:include href="xml/clutter-alpha.xml"/>
       <xi:include href="xml/clutter-behaviour.xml"/>
@@ -112,6 +122,11 @@
 
     <chapter>
       <title>Clutter Behaviours</title>
+
+      <partintro>
+        <para>Classes implementing ClutterBehaviour</para>
+      </partintro>
+
       <xi:include href="xml/clutter-behaviour-bspline.xml"/>
       <xi:include href="xml/clutter-behaviour-ellipse.xml"/>
       <xi:include href="xml/clutter-behaviour-opacity.xml"/>
@@ -122,6 +137,11 @@
 
     <chapter>
       <title>Simple Effects</title>
+
+      <partintro>
+        <para>Simple animation API</para>
+      </partintro>
+
       <xi:include href="xml/clutter-effects.xml"/>
     </chapter>
 
@@ -141,12 +161,30 @@
 
   <part>
     <title>Clutter Backends</title>
+
+    <partintro>
+      <para>Clutter is usually compiled against a specific drawing backend.
+      All backends have a common API for querying the underlying platform,
+      and some of them might have specific API exposed by Clutter.</para>
+    </partintro>
     
     <xi:include href="xml/clutter-backend.xml"/>
     <xi:include href="xml/clutter-glx.xml"/>
 
   </part>
 
+  <part>
+    <title>Additional Documentation</title>
+
+    <partintro>
+      <para>This section contains additional useful documentation for
+      developing with Clutter.</para>
+    </partintro>
+
+    &clutter-SubclassingActor;
+
+  </part>
+
   <index>
     <title>Index</title>
   </index>

diff --git a/doc/reference/subclassing-ClutterActor.sgml b/doc/reference/subclassing-ClutterActor.sgml
new file mode 100644 (file)
index 0000000..3ef2e52
--- /dev/null
+++ b/doc/reference/subclassing-ClutterActor.sgml
@@ -0,0 +1,112 @@
+<chapter id="clutter-subclassing-ClutterActor">
+  <chapterinfo>
+    <author>
+      <firstname>Emmanuele</firstname>
+      <surname>Bassi</surname>
+      <affiliation>
+        <address>
+          <email>ebassi@openedhand.com</email>
+        </address>
+      </affiliation>
+    </author>
+  </chapterinfo>
+
+  <title>Implementing a new actor</title>
+
+  <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
+  functions should be overidden. Optionally, also the ClutterActor::paint()
+  virtual functions should be overridden.</para>
+
+  <para>The ClutterActor::query_coords() method of a #ClutterActor is
+  invoked when clutter_actor_query_coords() is called on an instance
+  of that actor class. It is used to return a #ClutterActorBox containing
+  the coordinates of the bounding box for the actor (the coordinates
+  of the top left corner and of the bottom right corner of the rectangle
+  that fully contains the actor). Container actors, or composite actors
+  with internal children, should call clutter_actor_query_coords() on
+  each visible child. Remember: the returned coordinates must be relative
+  to the parent actor.</para>
+
+  <example id="clutter-actor-query-coords-example">
+    <para>This example shows how an actor class should override the
+    query_coords() virtual function of #ClutterActor. In this case,
+    the returned bounding box is the sum of the bounding boxes of all
+    the <structname>FooActor</structname> children.</para>
+
+    <programlisting>
+static void
+foo_actor_query_coords (ClutterActor    *actor,
+                        ClutterActorBox *box)
+{
+  FooActor *foo_actor = FOO_ACTOR (actor);
+  GList *child;
+  guint width, height;
+
+  /* initialize our size */
+  width = height = 0;
+
+  for (l = foo_actor-&gt;children; l != NULL; l = l-&gt;next)
+    {
+      ClutterActor *child_actor = child-&gt;data;
+
+      /* we return only visible actors */
+      if (CLUTTER_ACTOR_IS_VISIBLE (child_actor))
+        {
+          ClutterActorBox child_box;
+
+          clutter_actor_query_coords (child_actor, &amp;child_box);
+          
+          width += child_box.x2 - child_box.x2;
+          height += child_box.y2 - child_box.y1;
+        }
+    }
+
+  /* internally, the coordinates are all expressed in generic
+   * "units", but the public API converts them into pixels,
+   * so we need to juggle around with conversions
+   */ 
+  box-&gt;x2 = box-&gt;x1 + CLUTTER_UNITS_FROM_INT (width);
+  box-&gt;y2 = box-&gt;y1 + CLUTTER_UNITS_FROM_INT (height);
+}
+    </programlisting>
+  </example>
+  
+  <para>The ClutterActor::request_coords() method of a #ClutterActor
+  is invoked when clutter_actor_request_coords() is called on an instance
+  of that actor class. It is used to set the coordinates of the bounding
+  box for the actor. Container actors, or composite actors with internal
+  children, should call clutter_actor_request_coords() on each visible
+  child.</para>
+
+  <para>The ClutterActor::paint() method should be overridden if the
+  actor needs to control its drawing process, by using the GL API
+  directly. Actors performing transformations should push the GL matrix
+  first and then pop the GL matrix before returning. Container actors
+  or composite actors with internal children should do the same, and call
+  clutter_actor_paint() on every visible child:</para>
+
+  <example id="clutter-actor-paint-example">
+    <programlisting>
+static void
+foo_actor_paint (ClutterActor *actor)
+{
+  FooActor *foo_actor = FOO_ACTOR (actor);
+  GList *child;
+
+  glPushMatrix ();
+
+  for (child = foo_actor-&gt;children; child != NULL; child = child-&gt;next)
+    {
+      ClutterActor *child_actor = child-&gt;data;
+
+      clutter_actor_paint (child_actor);
+    }
+
+  glPopMatrix ();
+}
+    </programlisting>
+  </example>
+
+</chapter>