Chapter 4. The Stage

Table of Contents

Stage Basics

Each Cluttermm application contains at least one Clutter::Stage. 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 Cluttermm. You may then get the application's stage with Clutter::Stage::get_default(). This method always returns the same instance, with its own window. You could instead use a Clutter::Gtk::Embed widget inside a more complicated GTK+ window -- see the Stage Widget section.

Clutter::Stage is derived from the Clutter::Actor class so many of that class' methods are useful for the stage. For instance, call Clutter::Actor::show() to make the stage visible.

Clutter::Stage also implements the Clutter::Container interface, allowing it to contain child actors via calls to Clutter::Container::add_actor().

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

Clutter::Stage class reference

Example

The following example shows a Clutter::Stage 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.

c++ -Wall -g `pkg-config --cflags --libs cluttermm-1.0` -o example main.cc

Figure 4.1. Stage

Stage

Source Code

File: main.cc

#include <cluttermm.h>
#include <iostream>

namespace
{

bool on_stage_button_press(Clutter::ButtonEvent* event)
{
  float x = 0;
  float y = 0;
  // TODO: Wrap properly
  clutter_event_get_coords(reinterpret_cast<Clutter::Event*>(event), &x, &y);

  std::cout << "Stage clicked at (" << x << ", " << y << ")\n";

  return true; // stop further handling of this event
}

} // anonymous namespace

int main(int argc, char** argv)
{
  try
  {
    Clutter::init(&argc, &argv);

    // Get the stage and set its size and color:
    Glib::RefPtr<Clutter::Stage> stage = Clutter::Stage::get_default();
    stage->set_size(200, 200);
    stage->set_color(Clutter::Color(0, 0, 0)); // black

    stage->show();

    // Connect a signal handler to handle mouse clicks:
    stage->signal_button_press_event().connect(&on_stage_button_press);

    // Start the main loop, so we can respond to events:
    Clutter::main();
  }
  catch (const Glib::Error& error)
  {
    std::cerr << "Exception: " << error.what() << std::endl;
    return 1;
  }

  return 0;
}