<commit_before><!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><NAME>, 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);<commit_msg>docs: Add recipe for creating a custom ClutterActor with composition<commit_after><!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
  "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">

<chapter id="actors"
         xmlns:xi="http://www.w3.org/2003/XInclude">
  <title>Actors</title>

  <epigraph>
    <attribution><NAME>, 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-composite">
    <title>Implementing a simple custom actor</title>

    <section id="actors-composite-problem">
      <title>Problem</title>

      <para>You want to implement your own <type>ClutterActor</type>. For
      example, a widget (button, scrollbar, checkbox etc.) composed of
      several Clutter primitives.</para>
    </section>

    <section id="actors-composite-solution">
      <title>Solution</title>

      <para>Implement a custom actor composed from a <type>ClutterBox</type>
      packed with other <type>ClutterActors</type>. The custom actor
      effectively provides a facade for these internal actors, simplifying
      access to their properties and behavior.</para>

      <para>In this recipe, we make the simplest possible button widget
      (<type>CbButton</type>) to demonstrate the basic principles of
      implementing a <type>ClutterActor</type>. It is not a complete
      button implementation: see
      <ulink url="http://git.clutter-project.org/mx/tree/mx/mx-button.c"><type>MxButton</type></ulink>
      for a more
      comprehensive example (and the basis for this recipe). But
      it does cover the most important parts of a <type>ClutterActor</type>
      implementation, as well some useful <type>GObject</type>-related
      code.</para>

      <para>The code for this solution is structured like standard GObject
      C library code:</para>

      <itemizedlist>
        <listitem>
          <para>The header file <filename>cb-button.h</filename>
          declares the class' public API (function prototypes, macros,
          structs).</para>
        </listitem>
        <listitem>
          <para>The code file <filename>cb-button.c</filename>
          contains the class implementation.</para>
        </listitem>
      </itemizedlist>

      <para>One more example file, <filename>actors-composite-main.c</filename>,
      shows how to use <type>CbButton</type> in an application.</para>

      <para>Each of these files is described in more detail below.</para>

      <tip>
        <para>As Clutter is a GObject-based library, it relies
        heavily on GObject concepts and idioms. If you are unfamiliar with GObject,
        please read
        <ulink url="http://library.gnome.org/devel/gobject/unstable/">the GObject
        Reference Manual</ulink> before proceeding.</para>
      </tip>

      <section>
        <title><filename>cb-button.h</filename></title>

        <para>The header file defines the public API for the class,
        including GObject type macros, class and object structures, and
        function prototypes.</para>

        <programlisting>
<xi:include href="examples/cb-button.h" parse="text">
  <xi:fallback>a code sample should be here... but isn't</xi:fallback>
</xi:include>
        </programlisting>

      </section>

      <section>
        <title><filename>cb-button.c</filename></title>

        <para>This is the main C code file which implements both
        the GObject and Clutter parts of <type>CbButton</type>.
        The example below is commented liberally, and gives some samples
        of gtk-doc annotations to generate API docs for the
        widget. The <link linkend="">discussion section</link>
        comments more specifically about the Clutter-specific parts
        of it.</para>

        <para>
        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

        </para>

      </section>

      <section>
        <title><filename>actors-composite-main.c</filename></title>

        <para>
        The cb-button-main.c file shows how to use the new
        actor inside a Clutter application. Note how any of the
        <type>ClutterActor</type> functions (like set_size,
        add_constraint) can be applied to instance
        of our <type>ClutterActor</type> implementation.
        </para>

      </section>

    </section>

    <section id="actors-composite-discussion">
      <title>Discussion</title>

      <para>Explain about GObject a bit???</para>

      <para>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
      <type>ClutterLayoutManager</type> to handle positioning of
      the <type>ClutterText</type>; we change the background color of
      the button by changing the color of the
      <type>ClutterBox</type>; we use a <type>ClutterClickAction</type>
      to simplify implementation of a click signal.</para>

      <para>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.</para>

      <para>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.</para>

      <para>use Mx for inspiration???</para>

      <para>GObject implementation parts vs. Clutter implementation???</para>

      <para>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???</para>

    </section>

  </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);
{'fraction_non_alphanumeric': 0.08801827125790583, 'fraction_numerical': 0.0011419536191145468, 'mean_word_length': 2.791208791208791, 'pattern_counts': {'":': 0, '<': 229, '<?xml version=': 0, '>': 229, 'https://': 0, 'lorem ipsum': 0, 'www.': 3, 'xml': 3}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 0, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '319812', 'n_tokens_mistral': 3172, 'n_tokens_neox': 2984, 'n_words': 1259}