mirror of
https://github.com/brl/mutter.git
synced 2025-03-03 03:48:11 +00:00
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.
This commit is contained in:
parent
46baa44daf
commit
31efd346bd
@ -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:
|
||||
|
@ -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
|
||||
|
@ -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>
|
||||
|
112
doc/reference/subclassing-ClutterActor.sgml
Normal file
112
doc/reference/subclassing-ClutterActor.sgml
Normal file
@ -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->children; l != NULL; l = l->next)
|
||||
{
|
||||
ClutterActor *child_actor = child->data;
|
||||
|
||||
/* we return only visible actors */
|
||||
if (CLUTTER_ACTOR_IS_VISIBLE (child_actor))
|
||||
{
|
||||
ClutterActorBox child_box;
|
||||
|
||||
clutter_actor_query_coords (child_actor, &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->x2 = box->x1 + CLUTTER_UNITS_FROM_INT (width);
|
||||
box->y2 = box->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->children; child != NULL; child = child->next)
|
||||
{
|
||||
ClutterActor *child_actor = child->data;
|
||||
|
||||
clutter_actor_paint (child_actor);
|
||||
}
|
||||
|
||||
glPopMatrix ();
|
||||
}
|
||||
</programlisting>
|
||||
</example>
|
||||
|
||||
</chapter>
|
Loading…
x
Reference in New Issue
Block a user