Chapter 5. Actors

Table of Contents

Actor Basics

As mentioned in the introduction, Clutter is a canvas API for 2D surfaces in 3D space. Standard Clutter actors have 2D shapes and can be positioned and rotated in all three dimensions, but they have no depth. Theoretically, therefore, most actors would be invisible if they were exactly rotated so that only their edge faced the screen. When complex 3D objects are needed, you may use the full OpenGL ES API, as mentioned in the Implementing Actors appendix, but let's look at the standard actors for now:

ClutterStage: The stage itself, mentioned already
ClutterRectangle: A rectangle.
ClutterLabel: Displays text.
ClutterEntry: Text that may be edited by the user.
ClutterTexture: An image.

Each actor should be added to the stage with clutter_container_add() and its positions should then be specified. All actors derive from ClutterActor so you can call clutter_actor_set_position() to set the x and y coordinates, and the z coordinate can be set with clutter_actor_set_depth(), with larger values placing the actor further away from the observer. clutter_actor_set_size() sets the width and height.

The actor's position is relative to the top-left (0, 0) of the parent container (such as the stage), but this origin can be changed by calling clutter_actor_set_anchor_point().

By default, actors are hidden, so remember to call clutter_actor_show(). You may later call clutter_actor_hide() to temporarily hide the object again.

Like GTK+ widgets, Clutter actors have a "floating reference" when they are first instantiated with a function such as clutter_rectangle_new(). This reference is then taken when the actor is added to a container, such as the stage. This means that you do not need to unreference the actor after creating it.

Actors may also be transformed by scaling or rotation, and may be made partly transparent.

Reference

Example

The following example demonstrates two unmoving actors in a stage:

Figure 5.1. Actor

Source Code

File: main.c

#include <clutter/clutter.h>
#include <stdlib.h>


int main(int argc, char *argv[])
{
  ClutterColor stage_color = { 0x00, 0x00, 0x00, 0xff };
  ClutterColor actor_color = { 0xff, 0xff, 0xff, 0x99 };

  clutter_init (&argc, &argv);

  /* Get the stage and set its size and color: */
  ClutterActor *stage = clutter_stage_get_default ();
  clutter_actor_set_size (stage, 200, 200);
  clutter_stage_set_color (CLUTTER_STAGE (stage), &stage_color);

  /* Add a rectangle to the stage: */
  ClutterActor *rect = clutter_rectangle_new_with_color (&actor_color);
  clutter_actor_set_size (rect, 100, 100);
  clutter_actor_set_position (rect, 20, 20);
  clutter_container_add_actor (CLUTTER_CONTAINER (stage), rect);
  clutter_actor_show (rect);

  /* Add a label to the stage: */
  ClutterActor *label = clutter_label_new_full ("Sans 12", "Some Text", &actor_color);
  clutter_actor_set_size (label, 500, 500);
  clutter_actor_set_position (label, 20, 150);
  clutter_container_add_actor (CLUTTER_CONTAINER (stage), label);
  clutter_actor_show (label);

  /* Show the stage: */
  clutter_actor_show (stage);

  /* Start the main loop, so we can respond to events: */
  clutter_main ();

  return EXIT_SUCCESS;

}


Stage Widget		Transformations