mutter/doc/cookbook/actors.xml

<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
  "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">

<chapter id="actors">
  <title>Actors</title>

  <epigraph>
    <attribution>Edmon Gween, actor, on his deathbed</attribution>
    <para>An actor's a guy who if you ain't talkin' about him, ain't
    listening.</para>
  </epigraph>

  <section id="actors-introduction">
    <title>Introduction</title>

    <para>When building a User Interface with Clutter, the visible part
    of the UI &mdash; that is, what is displayed on the screen &mdash; is
    commonly referred to as "the scene graph". Like every graph, a scene
    graph is composed by nodes.</para>

    <para>Every node on the Clutter scene graph is an
    <emphasis>actor</emphasis>. Every actor has a single relationship
    with the others: it can be the parent of another actor, or a child of
    another actor.</para>

    <note><para>The stage is an actor that can have children but cannot have
    any parent.</para></note>

    <para>Actors have different attributes: a position, a size, a
    scale factor, a rotation angle on each axis (relative to a specific
    center on the normal plane for that axis), an opacity factor.</para>

    <para>The scene graph is not fixed: it can be changed, not only
    by adding or removing actors, but also by changing the parent-child
    relationship: it is possible, for instance, to move an entire
    section of the scene graph from one parent actor to another.</para>

  </section>

  <section id="actors-allocation-notify">
    <title>Knowing when an actor's position or size changes</title>

    <section>
      <title>Problem</title>

      <para>You want to know when the position or the size, or
      both, of an actor change, for instance to update an unrelated
      actor or some internal state.</para>
    </section>

    <section>
      <title>Solution</title>

      <para>You can use the <emphasis>notify</emphasis> signal,
      detailed with the coordinate or the dimension you want
      to know has changed:</para>

      <informalexample>
        <programlisting>
g_signal_connect (actor, "notify::x",
                  G_CALLBACK (on_x_changed),
                  NULL);
g_signal_connect (actor, "notify::height",
                  G_CALLBACK (on_height_changed),
                  NULL);
g_signal_connect (actor, "notify::depth",
                  G_CALLBACK (on_depth_changed),
                  NULL);
        </programlisting>
      </informalexample>

      <para>If you want to know if any of the coordinates or dimensions of
      an actor have been changed, except for depth, you can use the
      <emphasis>allocation-changed</emphasis> signal:</para>

      <informalexample>
        <programlisting>
g_signal_connect (actor, "allocation-changed",
                  G_CALLBACK (on_allocation_changed),
                  NULL);
        </programlisting>
      </informalexample>

      <para>The signature for the handler of the "notify" signal is:</para>

      <informalexample>
        <programlisting>
void
on_notify (GObject    *gobject,
           GParamSpec *pspec,
           gpointer    user_data);
        </programlisting>
      </informalexample>

      <para>While the signature for the handler of the "allocation-changed"
      signal is:</para>

      <informalexample>
        <programlisting>
void
on_allocation_changed (ClutterActor           *actor,
                       const ClutterActorBox  *allocation,
                       ClutterAllocationFlags  flags,
                       gpointer                user_data);
        </programlisting>
      </informalexample>

    </section>

    <section>
      <title>Discussion</title>

      <para>Any change the position and size of an actor will cause a
      change in the allocation of the actor itself. This will update the
      values of the <property>x</property>, <property>y</property>,
      <property>width</property> and <property>height</property>
      properties as well.</para>

      <para>The first technique allows a greater deal of granularity,
      allowing you to know what exactly changed. Inside the callback
      for the signal you can query the value of the property:</para>

      <informalexample>
        <programlisting>
void
on_x_changed (GObject    *gobject,
              GParamSpec *pspec,
              gpointer    user_data)
{
  gint x_value = 0;

  /* Round the X coordinate to the nearest pixel */
  x_value = floorf (clutter_actor_get_x (CLUTTER_ACTOR (gobject))) + 0.5;

  g_print ("The new X coordinate is '%d' pixels\n", x_value);
}
        </programlisting>
      </informalexample>

      <para>The second technique is more indicated if you want to
      get notification that any of the positional or dimensional
      attributes changed, except for the depth:</para>

      <informalexample>
        <programlisting>
void
on_allocation_changed (ClutterActor           *actor,
                       const ClutterActorBox  *allocation,
                       ClutterAllocationFlags  flags,
                       gpointer                user_data)
{
  g_print ("The bounding box is now: (%.2f, %.2f) (%.2f x %.2f)\n",
           clutter_actor_box_get_x (allocation),
           clutter_actor_box_get_y (allocation),
           clutter_actor_box_get_width (allocation),
           clutter_actor_box_get_height (allocation));
}
        </programlisting>
      </informalexample>

      <para>All actors will update these properties when their size
      or position change.</para>

      <para>Note that the stage, on the other hand, will not notify on
      position changes, so it is not possible to use the
      <property>x</property> and <property>y</property>
      properties to know that the platform-specific window embedding the
      stage has been moved &mdash; if the platform supports a windowing
      system. In order to achieve that you will have to use backend-specific
      API to extract the surface used by the stage and then platform-specific
      API to retrieve its coordinates.</para>

    </section>

  </section>

  <section id="actors-paint-wrappers">
    <title>Overriding the paint sequence</title>

    <section>
      <title>Problem</title>

      <para>You want to override the way an actor paints itself
      without creating a subclass.</para>
    </section>

    <section>
      <title>Solution</title>

      <para>You can use the <emphasis>paint</emphasis> signal to
      invoke a callback that will be executed before the actor's
      paint implementation:</para>

      <informalexample>
        <programlisting>
g_signal_connect (actor, "paint", G_CALLBACK (on_paint), NULL);
        </programlisting>
      </informalexample>

      <para>You can paint something after the actor's paint implementation
      by using the <function>g_signal_connect_after()</function> function
      instead of <function>g_signal_connect()</function>:</para>

      <informalexample>
        <programlisting>
g_signal_connect_after (actor, "paint", G_CALLBACK (on_paint_after), NULL);
        </programlisting>
      </informalexample>

      <para>The signature for the handler of the "paint" signal is:</para>

      <informalexample>
        <programlisting>
void on_paint (ClutterActor *actor, gpointer user_data);
        </programlisting>
      </informalexample>

    </section>

    <section>
      <title>Discussion</title>

      <para>The paint cycle in Clutter works its way recursively from the
      stage through every child.</para>

      <para>Whenever an Actor is going to be painted it will be positioned in
      a new frame of reference according to the list of transformations
      (scaling, rotation and additional translations). After that, the "paint"
      signal will be emitted.</para>

      <para>The "paint" signal is defined as <emphasis>run-last</emphasis>,
      that is the signal handlers connected to it using
      <function>g_signal_connetc()</function> will be called first; then the
      default handler defined by the Actor's sub-class will be called;
      finally, all the signal handlers connected to the signal using
      <function>g_signal_connect_after()</function> will be called.</para>

      <para>This allows pre- and post-default paint handlers, and it also
      allows completely overriding the way an Actor draws itself by default;
      for instance:</para>

      <informalexample>
        <programlisting>
void
on_paint (ClutterActor *actor)
{
  do_my_paint (actor);

  g_signal_stop_emission_by_name (actor, "paint");
}
        </programlisting>
      </informalexample>

      <para>The code above will prevent the default paint implementation of
      the actor from running.</para>
    </section>

  </section>

  <section id="actors-opacity">
      <title>Making an actor transparent by changing its opacity</title>

      <section>
        <title>Problem</title>

        <para>You want an actor to be transparent so that other
        actors are visible through it.</para>
      </section>

      <section>
        <title>Solution</title>

        <para>Change the actor's <emphasis>opacity</emphasis> so that
        it is partially (or even fully) transparent:</para>

        <informalexample>
          <programlisting>
/* 25% transparency */
clutter_actor_set_opacity (actor, 191.25);

/* 50% transparency */
clutter_actor_set_opacity (actor, 122.5);

/* completely transparent */
clutter_actor_set_opacity (actor, 0);
          </programlisting>
        </informalexample>

        <para>Any actor covered or overlapped by the transparent actor
        should be visible through it; the Discussion section gives
        some examples of how visible you can expect the covered or
        overlapped actor to be.</para>

      </section>

      <section>
        <title>Discussion</title>

        <para>Opacity is a property of every <type>ClutterActor</type>.
        It is a float on a scale from 0 (invisible) to 255 (completely
        opaque). Actors with <code>0 &lt; opacity &lt; 255</code> will
        have a varying amount of solidity on the stage, so other actors
        may be visible through them.</para>

        <para>For example, below are 4 yellow rectangles overlapping
        a white rectangle on a blue stage:</para>

        <screenshot>
          <mediaobject>
            <imageobject>
              <imagedata format="PNG"
                         fileref="images/actors-opacity.png" />
            </imageobject>
            <alt>
              <para>The effect of different opacities levels on
              an actor's appearance</para>
            </alt>
          </mediaobject>
        </screenshot>

        <para>The rectangles have the following opacities:</para>

        <itemizedlist>
          <listitem>
            <para>top-left: <code>255</code> (0% transparency)</para>
          </listitem>
          <listitem>
            <para>top-right: <code>191.25</code> (25% transparency)</para>
          </listitem>
          <listitem>
            <para>bottom-right: <code>122.5</code> (50% transparency)</para>
          </listitem>
          <listitem>
            <para>bottom-left: <code>61.25</code> (75% transparency)</para>
          </listitem>
        </itemizedlist>

        <para>Notice how both the stage and the white rectangle are
        visible through the yellow rectangles.</para>

        <para>As opacity is a property of every actor, it can
        be animated like any other GObject property, using any of
        the approaches in the animation API.</para>

        <para>The following sections cover some other considerations
        when working with actor opacity.</para>

        <section>
          <title>Container and color opacity</title>

          <para>If a container has its opacity set, any children of the
          container have their opacity combined with their parent's opacity.
          For example, if a parent has an opacity of <code>122.5</code>
          (50% transparent) and the child also has an opacity of
          <code>122.5</code>, the child's <emphasis>effective</emphasis>
          opacity is 25% (<code>opacity = 61.25</code>, and it is
          75% transparent).</para>

          <para>To demonstrate the visual effect of this, here are
          three rectangles with the same color but different opacity settings,
          inside parents which also have different opacity settings:</para>

          <screenshot>
            <mediaobject>
              <imageobject>
                <imagedata format="PNG"
                           fileref="images/actors-opacity-container-affects-opacity.png" />
              </imageobject>
              <alt>
                <para>How a container's opacity affects the opacity of
                its children</para>
              </alt>
            </mediaobject>
          </screenshot>

          <itemizedlist>
            <listitem>
              <para>The left-hand rectangle has <code>opacity = 255</code>
              and is in a <type>ClutterGroup</type> with
              <code>opacity = 255</code>. This means it is fully opaque.</para>
            </listitem>
            <listitem>
              <para>The middle rectangle has <code>opacity = 255</code>
              and is in a <type>ClutterGroup</type> with
              <code>opacity = 122.5</code>. Notice that the parent opacity
              makes the rectangle appear darker, as the stage colour is showing
              through from behind.</para>
            </listitem>
            <listitem>
              <para>The right-hand rectangle has <code>opacity = 122.5</code>
              and is in a <type>ClutterGroup</type> with
              <code>opacity = 122.5</code>. Notice that the rectangle appears
              to be even darker, as the stage colour is showing
              through both the rectangle and its parent.</para>
            </listitem>
          </itemizedlist>

          <para>Similarly, <type>ClutterColor</type> also contains an
          <varname>alpha</varname> property which governs the transparency
          of the color. Where an actor can have a color set (e.g.
          <type>ClutterRectangle</type>) the alpha value of the color also
          affects the transparency of the actor, for example:</para>

          <informalexample>
            <programlisting>
<![CDATA[
/* color with 50% transparency */
ClutterColor half_transparent_color = { 255, 0, 0, 122.5 };

ClutterRectangle *actor = clutter_rectangle_new ();

/* set actor's transparency to 50% */
clutter_actor_set_opacity (actor, 122.5);

/* rectangle will be 25% opaque/75% transparent */
clutter_rectangle_set_color (CLUTTER_RECTANGLE (actor),
                             &half_transparent_color);
]]>
            </programlisting>
          </informalexample>

        </section>

        <section>
          <title>Depth and depth order</title>

          <para>Each actor has two more aspects which affect its
          apparent opacity:</para>

          <itemizedlist>
            <listitem>
              <para>An actor's <emphasis>depth</emphasis> can have an
              effect if the stage has fog (a depth cueing effect) turned on.
              As an actor's depth increases, the actor apparently "recedes" from
              view and gradually blends into the colour of the stage. This
              produces an effect similar to making the actor transparent.
              See the <type>ClutterStage</type> documentation for
              more details about fog.</para>

              <para>Depth also needs to be considered if you want
              one actor to be visible through another: the actor you want
              to see through a transparent actor must be "deeper" than (or at
              the same depth as) the transparent actor.</para>
            </listitem>
            <listitem>
              <para>The <emphasis>depth order</emphasis> governs how
              actors within a <type>ClutterContainer</type> implementation
              are placed with respect to each other.</para>

              <note>
                <para>Depth ordering is not the same thing as depth: depth
                ordering records relationships between actors at the same
                depth.</para>
              </note>

              <para>If you have two overlapping actors <code>actorA</code> and
              <code>actorB</code> in a container, and you want <code>actorA</code>
              (opaque) to be visible through <code>actorB</code> (transparent),
              you should ensure that <code>actorB</code> is "above" <code>actorA</code>
              in the depth ordering. You could do this as follows:</para>

              <informalexample>
                <programlisting>
/*
 * raise actorB so it is above actorA in the depth order;
 * NB actorA and actorB both need to be in the same container
 * for this to work
 */
clutter_actor_raise (actorB, actorA);
                </programlisting>
              </informalexample>

              <para><function>clutter_actor_raise()</function>,
              <function>clutter_actor_lower()</function> and related
              <type>ClutterActor</type> functions set
              depth ordering on actors; see also <type>ClutterContainer</type>'s
              <function>clutter_container_raise_child()</function> and
              <function>clutter_container_lower_child()</function>
              functions.</para>
            </listitem>
          </itemizedlist>

        </section>

      </section>

    </section>

</chapter>