Chapter 4. The Stage

Table of Contents

Stage Basics

Each Clutter application contains at least one ClutterStage. This stage contains Actors such as rectangles, images, or text. We will talk more about the actors in the next chapter, but for now let's see how a stage can be created and how we can respond to user interaction with the stage itself.

First make sure that you have called clutter_init() to initialize Clutter. You may then get the application's stage with clutter_stage_get_default(). This function always returns the same instance, with its own window. You could instead use a GtkClutterEmbed widget inside a more complicated GTK+ window - see the Stage Widget section.

ClutterStage is derived from the ClutterActor object so many of that object's functions are useful for the stage. For instance, call clutter_actor_show() to make the stage visible.

ClutterStage also implements the ClutterContainer interface, allowing it to contain child actors via calls to clutter_container_add().

Call clutter_main() to start a main loop so that the stage can animate its contents and respond to user interaction.

Reference

Example

The following example shows a ClutterStage and handles clicks on the stage. There are no actors yet so all you will see is a black rectangle.

You can create an executable from this code like so, being careful to use backticks around the call to pkg-config. See also the Header Files And Linking section.

gcc -Wall -g example.c -o example `pkg-config clutter-0.8 --cflags  --libs`

Figure 4.1. Stage

Source Code

File: main.c

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

static gboolean
on_stage_button_press (ClutterStage *stage, ClutterEvent *event, gpointer data)
{
  gint x = 0;
  gint y = 0;
  clutter_event_get_coords (event, &x, &y);

  g_print ("Stage clicked at (%d, %d)\n", x, y);

  return TRUE; /* Stop further handling of this event. */
}

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

  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);

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

  /* Connect a signal handler to handle mouse clicks and key presses on the stage: */ 
  g_signal_connect (stage, "button-press-event",
    G_CALLBACK (on_stage_button_press), NULL);

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

  return EXIT_SUCCESS;

}