brl/mutter
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

[docs] Update the Actor subclassing documentation

Browse Source 
Mention map/unmap and fix the examples code.

Update the Container virtual functions.
This commit is contained in:
Emmanuele Bassi 2009-07-21 14:13:31 +01:00
parent ea436a20b3
commit 2e38730eb1
1 changed files with 34 additions and 22 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

56
doc/reference/clutter/subclassing-ClutterActor.xml
View File

@ -77,6 +77,19 @@ foo_actor_init (FooActor *actor)
done to determine the actors that received events</para></listitem> done to determine the actors that received events</para></listitem>
</varlistentry> </varlistentry>
<varlistentry>
<term>realization and visibility</term>
<listitem><para>used by containers and composite actors to
determine whether their children should allocate (and deallocate)
specific resources associated with being added to the #ClutterStage,
and whether their children should be painted or not. A
#ClutterContainer implementation should not care about overriding
the ClutterActor::realize(), ClutterActor::unrealize(),
ClutterActor::map() and ClutterActor::unmap() virtual functions, but
composite actors with private children MUST implement at least
ClutterActor::map() and ClutterActor::unmap().</para></listitem>
</varlistentry>
</variablelist> </variablelist>
</para> </para>
@ -349,8 +362,8 @@ static void
foo_actor_paint (ClutterActor *actor) foo_actor_paint (ClutterActor *actor)
{ {
FooActor *foo_actor = FOO_ACTOR (actor); FooActor *foo_actor = FOO_ACTOR (actor);
ClutterUnit w, h, r; ClutterActorBox allocation = { 0, };
gfloat width, height;
/* FooActor has a specific background color /* FooActor has a specific background color
* *
@ -364,19 +377,15 @@ foo_actor_paint (ClutterActor *actor)
priv-&gt;fgcol.blue, priv-&gt;fgcol.blue,
clutter_actor_get_paint_opacity (actor)); clutter_actor_get_paint_opacity (actor));
/* get the size of the actor with sub-pixel precision */ clutter_actor_get_allocation_box (actor, &amp;allocation);
w = CLUTTER_UNITS_TO_FIXED (clutter_actor_get_widthu (actor)); clutter_actor_box_get_size (&amp;allocation &amp;width, &amp;height);
h = CLUTTER_UNITS_TO_FIXED (clutter_actor_get_heightu (actor));
/* this is the arc radius for the rounded rectangle corners */
r = CLUTTER_UNITS_TO_FIXED (foo_actor->radius);
/* paint a rounded rectangle using GL primitives; the area of /* paint a rounded rectangle using GL primitives; the area of
* paint is (0, 0) - (width, height), which means the whole * paint is (0, 0) - (width, height), which means the whole
* allocation or, if the actor has a fixed size, the size that * allocation or, if the actor has a fixed size, the size that
* has been set. * has been set.
*/ */
cogl_path_round_rectangle (0, 0, w, h, r, 5); cogl_path_round_rectangle (0, 0, width, height, foo_actor-&gt;radius, 5);
/* and fill it with the current color */ /* and fill it with the current color */
cogl_path_fill (); cogl_path_fill ();
@ -410,9 +419,7 @@ foo_actor_paint (ClutterActor *actor)
{ {
ClutterActor *child_actor = child-&gt;data; ClutterActor *child_actor = child-&gt;data;
/* paint only visible children */ clutter_actor_paint (child_actor);
if (CLUTTER_ACTOR_IS_VISIBLE (child_actor))
clutter_actor_paint (child_actor);
} }
} }
</programlisting> </programlisting>
@ -436,8 +443,8 @@ foo_actor_pick (ClutterActor *actor,
const ClutterColor *pick_color) const ClutterColor *pick_color)
{ {
FooActor *foo_actor = FOO_ACTOR (actor); FooActor *foo_actor = FOO_ACTOR (actor);
ClutterUnit width, height; ClutterActorBox allocation = { 0, };
ClutterFixed radius; gfloat width, height;
/* it is possible to avoid a costly paint by checking whether the /* it is possible to avoid a costly paint by checking whether the
* actor should really be painted in pick mode * actor should really be painted in pick mode
@ -445,10 +452,8 @@ foo_actor_pick (ClutterActor *actor,
if (!clutter_actor_should_pick_paint (actor)) if (!clutter_actor_should_pick_paint (actor))
return; return;
clutter_actor_get_sizeu (actor, &amp;width, &amp;height); clutter_actor_get_allocation_box (actor, &amp;allocation);
clutter_actor_box_get_size (&amp;allocation, &amp;width, &amp;height);
/* this is the arc radius for the rounded rectangle corners */
radius = CLUTTER_UNITS_TO_FIXED (foo_actor-&amp;radius);
/* use the passed color to paint ourselves */ /* use the passed color to paint ourselves */
cogl_set_source_color4ub (pick_color-&gt;red, cogl_set_source_color4ub (pick_color-&gt;red,
@ -457,10 +462,10 @@ foo_actor_pick (ClutterActor *actor,
pick_color-&gt;alpha); pick_color-&gt;alpha);
/* paint a round rectangle */ /* paint a round rectangle */
cogl_round_rectangle (0, 0, width, height, radius, 5); cogl_path_round_rectangle (0, 0, width, height, foo_actor-&gt;radius, 5);
/* and fill it with the current color */ /* and fill it with the current color */
cogl_fill (); cogl_path_fill ();
} }
</programlisting> </programlisting>
</example> </example>
@ -486,8 +491,7 @@ foo_actor_pick (ClutterActor *actor,
/* clutter_actor_paint() is context-sensitive, and will perform /* clutter_actor_paint() is context-sensitive, and will perform
* a pick paint if the scene graph is in pick mode * a pick paint if the scene graph is in pick mode
*/ */
if (CLUTTER_ACTOR_IS_VISIBLE (foo_actor-&gt;child)) clutter_actor_paint (foo_actor-&gt;child);
clutter_actor_paint (foo_actor-&gt;child);
} }
</programlisting> </programlisting>
</example> </example>
@ -586,6 +590,14 @@ foo_actor_add_baz (FooActor *foo_actor,
child it is holding.</para> child it is holding.</para>
</listitem> </listitem>
</varlistentry> </varlistentry>
<varlistentry>
<term>ClutterContainer::foreach_with_internals</term>
<listitem>
<para>The contained should invoke the callback on every
child it is holding, including eventual private children
that should not be handled by the #ClutterContainer API.</para>
</listitem>
</varlistentry>
<varlistentry> <varlistentry>
<term>ClutterContainer::raise</term> <term>ClutterContainer::raise</term>
<listitem> <listitem>