Chapter 4. Actors

Table of Contents

Actor Basics

As mentioned in the introduction, PyClutter is a canvas API for 2D surfaces in 3D space. Standard PyClutter 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:

Stage: The stage itself, mentioned already
Rectangle: A rectangle.
Text: Displays and edits text.
Texture: An image.

Each actor should be added to the stage with stage.add() and its positions should then be specified. All actors derive from clutter.Actor so you can call actor.set_position() to set the x and y coordinates, and the z coordinate can be set with actor.set_depth(), with larger values placing the actor further away from the observer. 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 actor.set_anchor_point().

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

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 4.1. Actor

Source Code

File: main.py

import sys

import clutter


def main():
    stage_color = clutter.Color(0, 0, 0, 255)
    actor_color = clutter.Color(255, 255, 255, 153)

    # Get the stage and set its size and color
    stage = clutter.Stage()
    stage.set_size(200, 200)
    stage.set_color(stage_color)

    # Add a rectangle to the stage
    rect = clutter.Rectangle(actor_color)
    rect.set_size(100, 100)
    rect.set_position(20, 20)
    stage.add(rect)
    rect.show()

    # Add a label to the stage
    label = clutter.Text("Sans 12", "Some Text", actor_color)
    label.set_size(500, 500)
    label.set_position(20, 150)
    stage.add(label)
    label.show()

    # Show the stage
    stage.connect("destroy", clutter.main_quit)
    stage.show_all()

    # Start the main loop, so we can respond to events:
    clutter.main()

    return 0


if __name__ == '__main__':
    sys.exit(main())


Stage Widget Scrolling		Transformations