From 6cddd697475cfd0610622b21a970f7c755968b0f Mon Sep 17 00:00:00 2001 From: Emmanuele Bassi Date: Wed, 1 Feb 2012 19:26:15 +0000 Subject: [PATCH] docs: Update documentation on the paint sequence --- clutter/clutter-actor.c | 77 +++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 77 insertions(+) diff --git a/clutter/clutter-actor.c b/clutter/clutter-actor.c index 8f9da94..aaad7f0 100644 --- a/clutter/clutter-actor.c +++ b/clutter/clutter-actor.c @@ -115,6 +115,83 @@ * * * + * + * Painting an actor + * There are three ways to paint an actor: + * + * set a delegate #ClutterContent as the value for the + * #ClutterActor:content property of the actor; + * subclass #ClutterActor and override the + * #ClutterActorClass.paint_node() virtual function; + * subclass #ClutterActor and override the + * #ClutterActorClass.paint() virtual function. + * + * + * Setting the Content property + * A #ClutterContent is a delegate object that takes over the + * painting operation of one, or more actors. The #ClutterContent + * painting will be performed on top of the #ClutterActor:background-color + * of the actor, and before calling the #ClutterActorClass.paint_node() + * virtual function. + * + * ClutterActor *actor = clutter_actor_new (); + * + * /* set the bounding box */ + * clutter_actor_set_position (actor, 50, 50); + * clutter_actor_set_size (actor, 100, 100); + * + * /* set the content; the image_content variable is set elsewhere */ + * clutter_actor_set_content (actor, image_content); + * + * + * + * Overriding the paint_node virtual function + * The #ClutterActorClass.paint_node() virtual function is invoked + * whenever an actor needs to be painted. The implementation of the + * virtual function must only paint the contents of the actor itself, + * and not the contents of its children, if the actor has any. + * The #ClutterPaintNode passed to the virtual function is the + * local root of the render tree; any node added to it will be + * rendered at the correct position, as defined by the actor's + * #ClutterActor:allocation. + * + * static void + * my_actor_paint_node (ClutterActor *actor, + * ClutterPaintNode *root) + * { + * ClutterPaintNode *node; + * ClutterActorBox box; + * + * /* where the content of the actor should be painted */ + * clutter_actor_get_allocation_box (actor, &box); + * + * /* the cogl_texture variable is set elsewhere */ + * node = clutter_texture_node_new (cogl_texture, CLUTTER_COLOR_White); + * + * /* paint the content of the node using the allocation */ + * clutter_paint_node_add_rectangle (node, &box); + * + * /* add the node, and transfer ownership */ + * clutter_paint_node_add_child (root, node); + * clutter_paint_node_unref (node); + * } + * + * + * + * Overriding the paint virtual function + * The #ClutterActorClass.paint() virtual function is invoked + * when the #ClutterActor::paint signal is emitted, and after the other + * signal handlers have been invoked. Overriding the paint virtual + * function gives total control to the paint sequence of the actor + * itself, including the children of the actor, if any. + * It is strongly discouraged to override the + * #ClutterActorClass.paint() virtual function, as well as connecting + * to the #ClutterActor::paint signal. These hooks into the paint + * sequence are considered legacy, and will be removed when the Clutter + * API changes. + * + * + * * * Handling events on an actor * A #ClutterActor can receive and handle input device events, for -- 2.7.4