diff --git a/doc/cookbook/actors.xml b/doc/cookbook/actors.xml index d590fce02..5d944fcae 100644 --- a/doc/cookbook/actors.xml +++ b/doc/cookbook/actors.xml @@ -1,7 +1,8 @@ - + Actors @@ -37,6 +38,193 @@ +
+ Implementing a simple custom actor + +
+ Problem + + You want to implement your own ClutterActor. For + example, a widget (button, scrollbar, checkbox etc.) composed of + several Clutter primitives. +
+ +
+ Solution + + Implement a custom actor composed from a ClutterBox + packed with other ClutterActors. The custom actor + effectively provides a facade for these internal actors, simplifying + access to their properties and behavior. + + In this recipe, we make the simplest possible button widget + (CbButton) to demonstrate the basic principles of + implementing a ClutterActor. It is not a complete + button implementation: see + MxButton + for a more + comprehensive example (and the basis for this recipe). But + it does cover the most important parts of a ClutterActor + implementation, as well some useful GObject-related + code. + + The code for this solution is structured like standard GObject + C library code: + + + + The header file cb-button.h + declares the class' public API (function prototypes, macros, + structs). + + + The code file cb-button.c + contains the class implementation. + + + + One more example file, actors-composite-main.c, + shows how to use CbButton in an application. + + Each of these files is described in more detail below. + + + As Clutter is a GObject-based library, it relies + heavily on GObject concepts and idioms. If you are unfamiliar with GObject, + please read + the GObject + Reference Manual before proceeding. + + +
+ <filename>cb-button.h</filename> + + The header file defines the public API for the class, + including GObject type macros, class and object structures, and + function prototypes. + + + + a code sample should be here... but isn't + + + +
+ +
+ <filename>cb-button.c</filename> + + This is the main C code file which implements both + the GObject and Clutter parts of CbButton. + The example below is commented liberally, and gives some samples + of gtk-doc annotations to generate API docs for the + widget. The discussion section + comments more specifically about the Clutter-specific parts + of it. + + + enum for signals ???why do we need these + + enum for properties ???why do we need these + + array for signals ???is it an array + + + + + and Clutter stuff (private to the class): + + allocate (required) + paint (required) + you could get away with just these two + but if you're not composing your actor, or are creating a container, + you need to do more + + + + + then more GObject stuff (it should come after the Clutter method + implementations, i.e. allocate and paint): + + class_init + - where we wire together our functions + - we can also do things like adding properties and signals + + init + - where we create the private structure + - where we compose the actors together inside our ClutterActor + subclass + + + + + + Then normally some public API: + + typically you want a new() function + + for our class, we'll put some wrappers around functions + on the composed actors + + + +
+ +
+ <filename>actors-composite-main.c</filename> + + + The cb-button-main.c file shows how to use the new + actor inside a Clutter application. Note how any of the + ClutterActor functions (like set_size, + add_constraint) can be applied to instance + of our ClutterActor implementation. + + +
+ +
+ +
+ Discussion + + Explain about GObject a bit??? + + The actor implemented here is put together through + simple composition. This has the advantage of simplifying the + code for the subclass: we can just wrap a facade round + existing Clutter classes, rather than writing code to implement + everything ourselves. In the example here, we make use of a + ClutterLayoutManager to handle positioning of + the ClutterText; we change the background color of + the button by changing the color of the + ClutterBox; we use a ClutterClickAction + to simplify implementation of a click signal. + + On the other hand, it puts some constraints on the outline of + the actor: it makes it harder to use a custom outline, for + example, to round the corners of the button. This approach may + not be suitable where you need to do a lot of custom animation + and drawing. + + This isn't the whole story: if you aren't using this simple + composition approach, you may need to do more: see the notes in + the Clutter reference manual. Also, if you're implementing a + container, you'll need to do more. + + use Mx for inspiration??? + + GObject implementation parts vs. Clutter implementation??? + + something about how the ClutterBox is parented onto the + ClutterActor subclass we are implementing; we just create + an allocation for the ClutterBox based on the allocation of its + parent??? + +
+ +
+
Knowing when an actor's position or size changes