+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:
content_files= \
subclassing-ClutterActor.sgml \
clutter-animation.sgml \
+ creating-your-own-behaviours.sgml \
version.xml
# SGML files where gtk-doc abbrevations (#GtkWidget) are expanded
# 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
<!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">
</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>
&clutter-animation;
+ &creating-your-own-behaviours;
+
</part>
<index>
--- /dev/null
+<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<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>
<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