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.

As above, when you’re both a collector and a programmer, strange things could happen. I’m a beer coaster collector and my collection now reached 250+ unique items so it became a bit a mess to keep that well organized.

So that’s why a developed BeerCoaster manager. Yes, I done a program that help me to keep my collection organized. It is still a bit rudimentary but does its job pretty well. So, if you’re a beer coaster collector like me, you’ll found this useful.

It’s written in Python and uses sqlite as database to store it’s informations, so it is portable across various platforms (i.e.: you can copy & paste your files from Linux to Windows and it will keep working).

Currently, it can be downloaded only by SVN and it is everything but stable. I hope to release something good within the end of year.

The project homepage is hosted on Google project: http://bcmanager.googlecode.com/

Getting it working under Windows, currently, is really hard: for the final releases, though, I should provide a Windows installer.

I already know that this post will be useful just to me, because I know that someday I’ll forgot how to do this and I’ll be looking for a solution. So here’s how to insert an image in a TreeView ListView using python.

Technically, a ListView widget doesn’t exists, but it is a TreeView with a ListStore model associated in place of a TreeModel. And this “howto” uses a ListView as example as it is easier to set up, but the concept remains the same for all the kind of TreeViews.

First thing: a TreeView (ehm, ListView) in gtk is made up by TreeViewColumns and CellRendererers of various type, according to what you want to display. But the first thing to do is to import the needed pygtk’s modules.

import pygtk
pygtk.require("2.0")
import gtk
import gobject

Then we must set up a model for our ListView and associate it to the newly created TreeView object, before than building it with columns:

treeview = gtk.TreeView()
model = gtk.ListStore(
    gobject.TYPE_STRING, # a column will contain a string
    gtk.gdk.Pixbuf) # and another column will contain our image

treeview.set_model(model)

After we done this, we must create the columns and the cells. A cell, under the gtk point of view, is every single place in the TreeView where a value can be inserted, that is every intersection of a row with a column. While the column are created using nearly always the same funtion (gtk.TreeViewColumn()), the cells aren’t. They have a different function according to the type of data you intend to show.

In our example we’ll use two functions: gtk.CellRendererText() and gtk.CellRendererPixbuf(). The former is used to render text items, while the latter for “images”.

So, after we created the model, we must create the columns and associate the cells to them. This is done by using the following code (in this example we’ll create a text column):

cell_text = gtk.CellRendererText()
col_text = gtk.TreeViewColumn("A text column", cell_text, text = 0)
treeview.append_column(col_text)

In this way we created a text-rendered column. The important part of the example is on the second line, when we set the text attribute with text = 0. Doing this we said to gtk to render a text column on the first column (0, not 1, because the numbering starts from 0). Now it’s time to show how to show an image, instead. This is done in a very similar way:

cell_img = gtk.CellRendererPixbuf()
col_img = gtk.TreeViewColumn("An image!", cell_img, pixbuf = 1)
treeview.append_column(col_img)

The only different thing is that, this time, we specified a pixbuf attribute in place of a text one.

Now that we created our treeview, we must add rows to it:

item = model.append(None)
model.set_value(item, 0, "Hey, I'm text!")
model.set_value(item, 1, gtk.gdk.pixbuf_new_from_file("/path/to/image.jpg")

The important thing to remember is that we must pass a gtk.gdk.Pixbuf object as image. That’s all :)