This tutorial is outdated: it refers to version 0.4 of clutter that now is VERY old.

Last time we have seen how to draw the (maybe) most basic shape of clutter: the rectangles. We also positioned them together in the stage, and said (in part one) that the stage is a special kind of container.

Today it’s time to explain better what groups are and how to use them, so I’ll introduce to you the ClutterGroup and the ClutterHBox/ClutterVBox.

In the first part of this tutorial we said that the stage is a top level “window” on which child actors are placed and manipulated. That’s correct, but we also said that a stage is a special kind of container. Container, but it is self explanatory, contains objects: in the clutter’s case, these objects can be other containers or actors.

If you have some experience with GTK, you know that GTK uses HBox and VBox for placing the widgets respectively horizontally and vertically. Clutter has the same concept with ClutterHBox and ClutterVBox but, since clutter uses 3D effects, we also have a depth dimension, and we must be able to handle it in some way. Here comes the ClutterGroup: it contains objects exactly like HBox/VBox, but they’re not added sequentially horizontally or vertically, they’re added one up the other. Additionally, with ClutterGroups, we can use the relative positioning (we’ll see how later).

But before to talk about groups, it’s better to talk about HBox/VBox. I already said that HBox or VBox are used to place actors (or even other containers) sequentially. That said, if we add a label to a HBox and then we add a rectangle, the label and the rectangle will be placed sequentially starting from left.

Maybe it’s better to see this behaviour directly in action:

import clutter

def main():
    stage = clutter.stage_get_default()
    stage.set_size(420, 200)
    stage.set_color(clutter.color_parse("#FFF"))

    hbox = clutter.HBox()
    hbox.set_position(10, 10)
    rect_h1 = clutter.Rectangle()
    rect_h1.set_size(200, 50)
    rect_h1.set_color(clutter.color_parse("#FF0000"))
    rect_h2 = clutter.Rectangle()
    rect_h2.set_size(200, 50)
    rect_h2.set_color(clutter.color_parse("#800000"))
    rect_h2.set_border_width(1)
    rect_h2.set_border_color(clutter.color_parse("#000000"))

    vbox = clutter.VBox()
    vbox.set_position(10, 80)
    rect_v1 = clutter.Rectangle()
    rect_v1.set_size(200, 50)
    rect_v1.set_color(clutter.color_parse("#00FF00"))
    rect_v2 = clutter.Rectangle()
    rect_v2.set_size(200, 50)
    rect_v2.set_color(clutter.color_parse("#008000"))
    rect_v2.set_border_width(1)
    rect_v2.set_border_color(clutter.color_parse("#000000"))

    rect_h1.show()
    rect_h2.show()
    rect_v1.show()
    rect_v2.show()
    hbox.add(rect_h1, rect_h2)
    vbox.add(rect_v1, rect_v2)
    stage.add(hbox, vbox)

    hbox.show_all()
    vbox.show_all()
    stage.show_all()

    stage.connect("key-press-event", clutter.main_quit)
    clutter.main()

if __name__ == '__main__':
    main()

The above code will produce this:

You may ask yourself why we use multiple show() instead of having a single show_all() on the stage. The reason is that show_all() doesn’t recurse inside a Group because you might be hiding some of the actors inside that group for a later use. Anyway, it’s possible to subclass a clutter.Group and override the show_all() method so it recurse inside all its children, but that’s a bit more advanced topic that I hope I’ll be able to cover in another part of the tutorial.

As you can see, the rectangles have been placed sequentially in horizontal (for the HBox) or vertical (for the VBox) direction. In this way we can build a basic interface, since we can have nested boxes, that said HBoxes that contains other HBoxes or VBoxes (this is true for VBox too, obviously):

import clutter

def main():
    stage = clutter.stage_get_default()
    stage.set_size(420, 200)
    stage.set_color(clutter.color_parse("#FFF"))

    hbox = clutter.HBox()
    hbox.set_position(10, 10)
    rect_h1 = clutter.Rectangle()
    rect_h1.set_size(200, 50)
    rect_h1.set_color(clutter.color_parse("#FF0000"))

    vbox = clutter.VBox()
    vbox.set_position(10, 80)
    rect_v1 = clutter.Rectangle()
    rect_v1.set_size(200, 50)
    rect_v1.set_color(clutter.color_parse("#00FF00"))
    rect_v2 = clutter.Rectangle()
    rect_v2.set_size(200, 50)
    rect_v2.set_color(clutter.color_parse("#008000"))
    rect_v2.set_border_width(1)
    rect_v2.set_border_color(clutter.color_parse("#000000"))

    rect_h1.show()
    rect_v1.show()
    rect_v2.show()
    vbox.add(rect_v1, rect_v2)
    hbox.add(rect_h1, vbox)
    stage.add(hbox)

    hbox.show_all()
    vbox.show_all()
    stage.show_all()

    stage.connect("key-press-event", clutter.main_quit)
    clutter.main()

if __name__ == '__main__':
    main()

It works in this way:

Let do a step back: we introduced the set_position method previously, but we didn’t explained extensively how this method works. The set_position set the specified actor’s position to the coordinates relatives to its father container. So, if we don’t have any container it reverts to the stage, that is the father of all the childs in a window (and we have absolute positioning), otherwise it will set the actor’s position to the first father it finds. Let see this scheme to clarify a bit:

Groups shares most of the properties of HBox and VBox, but instead of placing the elements horizontally or vertically, it positions them on the z-axis (it put the actors one up the other). In this way we can also have a container that help us in achieving the relative positioning:

import clutter

def main():
    stage = clutter.stage_get_default()
    stage.set_size(500, 500)
    stage.set_color(clutter.color_parse("#FFF"))

    rect1, rect2, rect3 = clutter.Rectangle(), clutter.Rectangle(), clutter.Rectangle()
    group1, group2, group3 = clutter.Group(), clutter.Group(), clutter.Group()

    group1.add(rect1, group2)
    group2.add(rect2, group3)
    group3.add(rect3)

    group1.set_position(100, 100)
    group2.set_position(100, 100)
    group3.set_position(100, 100)

    rect1.set_position(0, 0)
    rect2.set_position(0, 0)
    rect3.set_position(0, 0)

    rect1.set_size(150, 150)
    rect2.set_size(150, 150)
    rect3.set_size(150, 150)

    rect1.set_color(clutter.color_parse("#FF000090"))
    rect2.set_color(clutter.color_parse("#00FF0090"))
    rect3.set_color(clutter.color_parse("#0000FF90"))

    stage.add(group1)

    stage.show_all()
    group1.show_all()
    group2.show_all()
    group3.show_all()

    stage.connect("key-press-event", clutter.main_quit)
    clutter.main()

if __name__ == '__main__':
    main()

With the above code, we’ll position each group relatively to its father. Only the first group will have the stage as father, all the others are relative positioned to the previous stage.

That’s all for today :)

This tutorial is outdated: it refers to version 0.4 of clutter that now is VERY old.

Last time we learned how to have our first stage drawn, so now it’s time to begin to insert something into that stage.

Let do a summary of what we are going to do in this “lesson”:

• change the stage’s color
• add a rectangle to the stage
• add another rectangle to the stage

The first thing we want to do is to change the stage’s color. This can be done by using the set_color() method of the stage object:

    stage.set_color(clutter.color_parse("#00000"))

In this way we have a black stage. But how does it works? The set_color() method needs a ClutterColor object in input, and we can have it by calling the color_parse() function. The color_parse() has the same syntax of pango_color_parse() (a built-in GTK function), so it accepts both hexadecimal specifications of the color (i.e.: #000000 or #000 for black, #FF0000 or #F00 for red) and literal color values like “black” or “red”. Additionally, we can specify a pixel alpha value (the object’s opacity level) by using a hexadecimal specification like #000000FF, where FF is the alpha value. We can specify an alpha value for the stage but it won’t work since the stage hasn’t a alpha layer.

After this, our window will look like this:

Note that now the window became black as we specified. Now that we completed the first goal, it’s time for us to introduce a new clutter object: the rectangle.

A rectangle is made up by the rectangle itself and a border. That said, if we tell clutter to draw a 100x100px rectangle with a 2px border, the resulting rectangle will be 2px + 100px + 2px large.

Now that we had enough theory, we can begin to draw our first rectangle:

import clutter

def main():
    stage = clutter.stage_get_default()
    stage.set_size(500, 500)
    stage.set_color(clutter.color_parse("#000000"))

    rect = clutter.Rectangle()
    rect.set_position(20, 20)
    rect.set_size(200, 300)
    rect.set_color(clutter.color_parse("#A02020"))

    stage.add(rect)

    rect.show()
    stage.show()

    stage.connect("key-press-event", clutter.main_quit)
    clutter.main()

if __name__ == '__main__':
    main()

This code will give us this output:

And now it’s time to analyze what we done by looking at the code line per line (I’ll skip the lines that we already seen):

    rect = clutter.Rectangle()

In order to draw a rectangle we need an instance of the rectangle object, right? We can get this instance by calling the Rectangle constructor function.

Once we have our rectangle instance, we can make operations like positioning and coloring on it:

    rect.set_position(20, 20)
    rect.set_size(200, 300)
    rect.set_color(clutter.color_parse("#A02020"))

The first line moves the upper left corner of the rectangle at position (20, 20) in the stage. The second and the third line, instead, are functions that we have already seen: both the rectangle’set_size() and set_color() functions works exactly as the stage’s one (we’ll see further in another part of this tutorial why the name and the implementation is the same). Indeed, in this way we can specify both a size and a color for our rectangle.

    stage.add(rect)

We drawn our rectangle, but now we need to tell clutter where to put it: this is done by using the add() method of the stage object (if this operation looks useless to you it’s because we still didn’t talked about Groups and Box; we’ll do that another time, now just take this line as is).

The last line of interest is this one:

    rect.show()

We’ve already explained in the previous part how the show() method works for the stage: here’s is exactly the same thing.

Now that we have our first rectangle, is time to draw the second one:

import clutter

def main():
    stage = clutter.stage_get_default()
    stage.set_size(500, 500)
    stage.set_color(clutter.color_parse("#000000"))

    rect1 = clutter.Rectangle()
    rect2 = clutter.Rectangle()

    rect1.set_position(20, 20)
    rect1.set_size(200, 300)
    rect1.set_color(clutter.color_parse("#A02020"))

    rect2.set_position(50, 100)
    rect2.set_size(350, 300)
    rect2.set_color(clutter.color_parse("#FFFFFF50"))
    rect2.set_border_width(20)
    rect2.set_border_color(clutter.color_parse("blue"))

    stage.add(rect1, rect2)

    rect1.show()
    rect2.show()
    stage.show()

    stage.connect("key-press-event", clutter.main_quit)
    clutter.main()

if __name__ == '__main__':
    main()

We’ll obtain this:

(if you see the second rectangle’s border partially drawn, or not drawn at all, you are probably using a version of clutter older than 0.4.2, where a bug in the border generation deny you from having the rectangle shown correctly)

We’ve already discussed many of the functions in the code above, so I’ll quickly jump to the more complex part. First of all, let do a resume of what we do in this script:

1. we create the first rectangle named rect1
2. we create the second rectangle named rect2
3. we set up properties for both rectangles (please note that for the second rectangle we specified a pixel alpha value too)
4. then we add the rectangle to the stage and show them

The only thing I should explain is the point number four: the add method of a container (a stage, in this case), can have multiple arguments. Indeed, we can tell clutter to add multiple elements to a container. So in our example, we added both rect1 and rect2 in a single line of code instead of having two separate add statements.

After having the actors added to the stage, we show them by calling the show() method on every single actor. This approach works, but sometimes could be more useful (and time saving) to call a special show method on the parent. We’ll discuss this behaviour better when we’ll talk about groups, but by now on I’ll use the show_all() method on the stage in order to show all its children in one line of code.

See you for the next part of this tutorial :)

This tutorial is outdated: it refers to version 0.4 of clutter that now is VERY old.

This tutorial is the first of a series that will try to learn to you how to use clutter with the help of python, or better: a tutorial about pyclutter.

But before to begin, it’s better to give an overview on what clutter is. Citing the clutter’s homepage:

Clutter is an open source software library for creating fast, visually rich and animated graphical user interfaces. Clutter uses OpenGL (and optionally OpenGL ES) for rendering but with an API which hides the underlying GL complexity from the developer. The Clutter API is intended to be easy to use, efficient and flexible.

That said, while clutter is the main library (written in C), there are bindings to other languages like perl, vala, ruby, C# and python. The python binding is commonly named pyclutter.

The requirements needed to better follow the tutorial are:

• a good python knowledge (of course); if you don’t know it, you can always learn it by following the excellent dive into python
• some basic knowledge of how the GTK environment works; although it isn’t really needed since we won’t use GTK functions, it is very useful since, under a certain point of view, clutter inherits many things from GTK
• clutter 0.4.2 or newer

In clutter we have mainly two kind of objects: actors and containers. Stages, additionally, are a special kind of container. We can see the clutter actors like the GTK widgets and the stages like the GTK windows. A stage, as the documentation says, is a top level “window” on which child actors are placed and manipulated.

Let see the stage as our workspace: in it we will place all the objects as we do with a GTK Window. So, let build our first clutter window:

import clutter

def main():
    stage = clutter.stage_get_default()
    stage.set_size(500, 500)
    stage.show()
    stage.connect("key-press-event", clutter.main_quit)

    clutter.main()

if __name__ == '__main__':
    main()

The above code will produce this:

Well, that’s our first window :)
Now let analyze every single line of the script:

import clutter

The line above is, probably, the most important one in the script because without that line nothing will run. If you know Python you’ll already know what that line does, but if you’re a python newbie you need to understand that the import statement import the specified namespace into the current script. That said, with that line, we can use clutter.

Let jump the main() for a while and let go to:

if __name__ == '__main__':
    main()

Apart from the main() call that is pretty obvious, the line that could create some problem is the one with the if statement. What it does is to call the main() only if __name__ is equal to __main__. So the question is: “when __name__ is ‘__main__’”? Every module has a built-in attribute __name__, but it assumes the value __main__ only when you execute that script: if the script is imported, instead, it will contain the module’s name.

Now jump into the main():

    stage = clutter.stage_get_default()

It’s better to spend some more time over the stage_get_default() method. We said that a stage is like a GTK window, but we didn’t created any window or stage because we don’t need to do so since clutter does it for us when we call clutter.main(). So we need a pointer to the newly created stage, and this pointer is a ClutterStage object that we can retrieve calling clutter.stage_get_default().

Now that we have a reference to our stage and we have initialized everything, we can begin to set properties on our stage/window:

    stage.set_size(500, 500)

With the set_size method, we say that our stage should be 500x500px big. Pay attention that we specify the stage dimensions, that doesn’t includes the width and height of the decorators that the window manager adds (like the title bar). Then we have:

    stage.show()

We call the show() method of the stage object because, by default, visual object like containers and actors are hidden and we have explicitly tell clutter to show them by using the actor’s show() method. If we don’t call this method we won’t see anything.

    stage.connect("key-press-event", clutter.main_quit)

Pay attention to the above line. With that line we say to clutter to quit when some key on the keyboard is pressed. That said, we connected an “event” to a “callback function” where, in this case, the event is key-press-event (that indicates that a key has been pressed) and the callback is clutter.main_quit (without parenthesis because we are NOT calling it but, instead, we’re just giving it’s address so it can be called later by the clutter event handler). The clutter.main_quit() function is the function that clutter uses to stop the program’s execution and, with

    clutter.main()

starts and stop the program flow (clutter.main(), as the name says, is the function that starts the program).

We did our first clutter program, and I think is enough for now. So let see you on the part two of this tutorial where I’ll begin to explain how to begin to insert something into our stage.