Table of Contents
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:
Clutter::Stage: The stage itself, mentioned already
Clutter::Rectangle: A rectangle.
Clutter::Text: Displays and edits text.
Clutter::Texture: An image.
Each actor should be added to the stage with Clutter::Container::add_actor()
and its positions should then be specified. All actors derive from Clutter::Actor
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 all objects of the Glib::Object
class, Cluttermm actors are
reference counted. The reference count starts at one when they are first instantiated with a method
such as Clutter::Rectangle::create()
. This reference is then managed by the
Glib::RefPtr<Clutter::Rectangle>
smart pointer returned by the method.
If the smart pointer goes out of scope, the reference count is decremented again, and the actor will
be destroyed if the reference count reached zero. However, if the actor is added to a container such
as the stage, the container will obtain another reference to the actor, which is not released until
the actor has been removed again from the container. This means you do not need to keep around the
Glib::RefPtr<Clutter::Rectangle>
after the actor was added to a
container, and neither do you have to manually reference or unreference any Cluttermm
object.
Actors may also be transformed by scaling or rotation, and may be made partly transparent.
Clutter::Actor
class reference
The following example demonstrates two unmoving actors in a stage:
File: main.cc
#include <cluttermm.h> int main(int argc, char** argv) { Clutter::init(&argc, &argv); // Get the stage and set its size and color: const Glib::RefPtr<Clutter::Stage> stage = Clutter::Stage::get_default(); stage->set_size(200, 200); stage->set_color(Clutter::Color(0, 0, 0, 255)); // black Clutter::Color actor_color (0xff, 0xff, 0xff, 0x99); // Add a rectangle to the stage: const Glib::RefPtr<Clutter::Rectangle> rect = Clutter::Rectangle::create(actor_color); rect->set_size(100, 100); rect->set_position(20, 20); stage->add_actor(rect); rect->show(); // Add a label to the stage: const Glib::RefPtr<Clutter::Actor> label = Clutter::Text::create("Sans 12", "Some Text", actor_color); label->set_size(500, 500); label->set_position(20, 150); stage->add_actor(label); label->show(); // Show the stage: stage->show(); // Start the main loop, so we can respond to events: Clutter::main(); return 0; }