diff --git a/doc/reference/ChangeLog b/doc/reference/ChangeLog index 1ec9e69d5..25528e553 100644 --- a/doc/reference/ChangeLog +++ b/doc/reference/ChangeLog @@ -1,3 +1,12 @@ +2007-06-16 Emmanuele Bassi + + * 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 * clutter-sections.txt: diff --git a/doc/reference/Makefile.am b/doc/reference/Makefile.am index e1f39bede..126b44333 100644 --- 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 f21870aea..360eedf2f 100644 --- a/doc/reference/clutter-docs.sgml +++ b/doc/reference/clutter-docs.sgml @@ -2,6 +2,7 @@ + ]> @@ -93,6 +94,10 @@ Container Actors + + + Actors containing other actors. + @@ -105,6 +110,11 @@ Base Classes + + + Clutter base animation objects + + @@ -112,6 +122,11 @@ Clutter Behaviours + + + Classes implementing ClutterBehaviour + + @@ -122,6 +137,11 @@ Simple Effects + + + Simple animation API + + @@ -141,12 +161,30 @@ Clutter Backends + + + 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. + + + Additional Documentation + + + This section contains additional useful documentation for + developing with Clutter. + + + &clutter-SubclassingActor; + + + Index diff --git a/doc/reference/subclassing-ClutterActor.sgml b/doc/reference/subclassing-ClutterActor.sgml new file mode 100644 index 000000000..3ef2e5217 --- /dev/null +++ b/doc/reference/subclassing-ClutterActor.sgml @@ -0,0 +1,112 @@ + + + + Emmanuele + Bassi + +
+ ebassi@openedhand.com +
+ + + + + Implementing a new actor + + 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. + + 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. + + + 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 FooActor children. + + +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); +} + + + + 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. + + 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: + + + +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 (); +} + + + +