Features/GTK3/Porting

=Porting an existing activity to GTK3= This is a guide to porting an existing activity from GTK2 to GTK3. It also shows the changes to use the new Sugar toolkit that also now uses GTK3. This guide uses the hello-world activity as a simple example.

There is another guide written from scratch that uses this one as reference. I was done porting GetBooks Activity Features/GTK3/Porting/GetBooks

Preparation
Before you start porting your activity you are encouraged to branch off a stable branch. This will allow you to keep on doing stable releases on the stable branch and new releases on the master branch. We highly recommend that you use the 'sugar-0.94' as the stable branch name because this will keep the repositories consistent and eases the development work. Let's step through this with a real life example:

The latest release of hello-world was version 3 (commit 04fb9beb708f1078aae93995da3ec06bac7aa433). We want to branch off at that point. If you did not do any changes after the last stable commit simply create a branch with: git branch sugar-0.94

If you have already made commits after that, you need to go to that commit first and create a branch at that specific point in our case commit 04fb9beb708f1078aae93995da3ec06bac7aa433, there is a command to do that in one go: git checkout -b sugar-0.94 04fb9beb708f1078aae93995da3ec06bac7aa433 In both cases this has created a local branch, as you can see by running 'git branch'; you should see the following (if you did the second command you will have sugar-0.94 already selected):

[erikos@T61 helloworld]$ git branch sugar-0.94
 * master

The 'sugar-0.94' branch is only available locally, as you can see by running 'git branch -r' which shows the remote branches:

[erikos@T61 helloworld]$ git branch -r origin/HEAD -> origin/master origin/master origin/sucrose-0.84

The only branch available besides the master branch is the 'sucrose-0.84' branch. Let's push now our new branch to the remote repository to make it available for others: git push origin sugar-0.94

The branch is now listed as a remote branch. You can verify as well on your gitorious page. [erikos@T61 helloworld]$ git branch -r origin/HEAD -> origin/master origin/master origin/sucrose-0.84 origin/sugar-0.94

You can switch now between those branches using 'git checkout '. And you can use 'git branch' to see which branch you are on (the one with the * before is the branch you are currently on). git checkout sugar-0.94 git checkout master

Cleanup, adopt to API changes in sugar-toolkit-gtk3
This should be done only on the master branch! In the new sugar-toolkit-gtk3 we have removed old API, you should adjust your activity accordingly:
 * the keep button has been removed completely
 * the old-style toolbar has been removed
 * do not use set_toolbox anymore use set_toolbar_box instead (see in Abacus)
 * remove import of deprecated ActivityToolbox (see hello-world)
 * support for 'service_name' and 'class' has been removed from the activity.info make sure you are using: 'bundle_id' instead of 'service_name' and 'exec' instead of 'class' (see in Record)

Port the activity from GTK2 to GTK3
To start, change the importing instruction for GTK from import gtk to from gi.repository import Gtk Then you have to change each call that involves Gtk, for example creating a button will look now like this: button = Gtk.Button

A simple hello world program in GTK3 looks like this: from gi.repository import Gtk

def _destroy_cb(widget, data=None): Gtk.main_quit

w = Gtk.Window w.connect("destroy", _destroy_cb) label = Gtk.Label('Hello World!') w.add(label) w.show_all

Gtk.main

For porting your activity you do have to change your calls for accessing widgets and services in the new GTK3 sugar-toolkit as well. The new namespace is called sugar3, trying to reflect that GTK3 is the underlying technology. For example the import of the base activity class has to be changed from from sugar.activity import activity to from sugar3.activity import activity

Make sure you change the setup.py in your activity to point to the new toolkit as well: from sugar3.activity import bundlebuilder

The changes that were needed to port the hello-world activity can be seen in this commit.

Ok, let's do these changes now for your activity. Make sure you are in your master branch using the 'git branch' command (the master branch should have a '*' before it). Make your changes, commit them ('git commit -a') and push them to the remote repository ('git push origin master').

Tools
There are tools to help you do the porting. There is a script in the pygobject repository for porting called pygi-convert.sh, more info about the script can be found in the PyGObject Introspection Porting guide.

Here is a script to automate the rename of the imports sugar to sugar3: sugar-convert.sh.

If you are having trouble finding how a particular GTK class/method/constant has been named in PyGI, run pygi-enumerate.py and grep the output. (this app lists all identified methods and constants). Usage example:

$ python pygi-enumerate.py | grep get_selection Gtk.AccelLabel.get_selection_bounds (instance method) Gtk.Editable.get_selection_bounds (instance method) Gtk.Entry.get_selection_bounds (instance method) Gtk.IconView.get_selection_mode (instance method) Gtk.Label.get_selection_bounds (instance method) Gtk.SelectionData.get_selection (instance method) Gtk.SpinButton.get_selection_bounds (instance method) Gtk.TextBuffer.get_selection_bound (instance method) Gtk.TextBuffer.get_selection_bounds (instance method) Gtk.TreeView.get_selection (instance method)

Constructor considerations
With PyGI it is possible to use Python-like constructors, or "new" functions e.g. the following are (usually) equivalent: label = Gtk.Button label = Gtk.Button.new

However, the first form is preferred: it is more Python-like. Internally, the difference is that Gtk.Label.new translates to a call to gtk_label_new, whereas Gtk.Label (the preferred form) will directly construct an instance of GtkLabel at the GObject level.

If the constructor takes parameters, they must be named. The parameters correspond to GObject properties in the API documentation which are usually marked as "Construct". For example, the following code will not work:

expander = Gtk.Expander("my expander")

The (confusing) error is: TypeError: GObject.__init__ takes exactly 0 arguments (1 given)

The solution is to go to the GtkExpander API documentation and find the appropriate property that we wish to set. In this case it is label (which is a Construct property, further increasing our confidence of success), so the code should be:

expander = Gtk.Expander(label="my expander")

Combining the two points above, if you wish to call a construct-like function such as gtk_button_new_with_label, you do have the option of calling Gtk.Button.new_with_label, however if we check the GtkButton properties we see one called "label" which is equivalent. Therefore gtk_button_new_with_label("foo") should be called as: button = Gtk.Button(label="foo")

HBox, VBox, pack_start and pack_end
GtkHBox and GtkVBox, commonly used containers in GTK2 code, have pack_start and pack_end methods. These take 4 parameters:
 * 1) The widget to pack into the container
 * 2) expand: Whether the child should receive extra space when the container grows (default True)
 * 3) fill: True if space given to child by the expand option is actually allocated to child, rather than just padding it. This parameter has no effect if expand is set to False. A child is always allocated the full height of a gtk.HBox and the full width of a gtk.VBox. This option affects the other dimension. (default True)
 * 4) padding: extra space in pixels to put between child and its neighbor (default 0)

In PyGTK, the expand, fill and padding parameters were optional: if unspecified, the default values above were used. In PyGI, these parameters are not optional: all 4 must be specified. Hence the rules for adding in the extra parameters are:


 * 1) If expand was not set, use value True
 * 2) If fill was not set, use value True. (however, if expand is False, this parameter gets ignored so False is an equally acceptable option when expand=False)
 * 3) If padding was not set, use value 0.

These parameters can be specified either as positional arguments or as named keyword arguments, however all 4 must always be specified. Some developers prefer keyword arguments, arguing that the following: box.pack_start(widget, expand=True, fill=False, padding=4) is much more readable than: box.pack_start(widget, True, False, 4)

However, these functions are called extremely often; any mildly seasoned GTK developer will have memorized the order and meaning of the parameters. Some developers therefore prefer to avoid the extra work of dropping in hundreds of keyword arguments throughout the code and just use the positional ones. This is really up to you.

If you are using pack_start with the default values (expand=True, fill=True and padding=0), you can avoid using pack_start (and the parameter pain that it brings with it) by just using .add for some added cleanliness, e.g. box.pack_start(widget, True, True, 0) can be replaced with: box.add(widget)

This is as far as you need to go for now. However, in GTK3, GtkVBox and GtkHBox have been deprecated, which means they might be removed in GTK4. The replacement is to use GtkBox directly, and you may wish to make this change now. e.g.: vbox = Gtk.Box(orientation=Gtk.Orientation.VERTICAL) hbox = Gtk.Box(orientation=Gtk.Orientation.HORIZONTAL, homogeneous=True, spacing=8) However, it must be noted that if GtkBox is used directly (instead of using GtkHBox/GtkVBox), the default value of expand is now False. The implications of this are:
 * 1) You need to check your .add calls, as previously they would behave as pack_start with expand=True, but now they will behave as expand=False (you need to change them to use pack_start with expand=True to retain the old behaviour)
 * 2) Every single pack_start call that has expand=False and padding=0 (and any value of fill) can be converted to .add for cleanliness

GtkAlignment considerations
In PyGTK, the gtk.Alignment constructor takes four optional parameters:
 * 1) xalign: the fraction of horizontal free space to the left of the child widget. Ranges from 0.0 to 1.0. Default value 0.0.
 * 2) yalign: the fraction of vertical free space above the child widget. Ranges from 0.0 to 1.0. Default value 0.0.
 * 3) xscale: the fraction of horizontal free space that the child widget absorbs, from 0.0 to 1.0. Default value 0.0.
 * 4) yscale: the fraction of vertical free space that the child widget absorbs, from 0.0 to 1.0. Default value 0.0

In PyGI/GTK3, these parameters are still optional when used in the Gtk.Alignment constructor (as keyword arguments, as explained above). However, the default values have changed. They are now:
 * 1) xalign: default value 0.5
 * 2) yalign: default value 0.5
 * 3) xscale: default value 1
 * 4) yscale: default value 1

If your code was relying on the default value of 0 for any of these parameters in PyGTK, you will now need to explicitly specify that in your constructor. Similarly, if you were previously using construction parameters to select the now-default values, those parameters can be dropped.

Additionally, PyGTK accepted these construction parameters as positional arguments. As explained above, they must now be converted to keyword arguments.

Other considerations
self.allocation property is no longer available. Please search your code for "self.allocation" and replace it for "self.get_allocation".

So to get the allocation size:

self.allocation.width self.allocation.height

should be replaced by:

self.get_allocated_width self.get_allocated_height

Constants
Most of the constants have slightly different formats, e.g.,

Gtk.StateFlags.NORMAL Gtk.PolicyType.NEVER Gtk.Justification.LEFT

Pixbufs
The pixbuf libraies are in their own repository

from gi.repository import GdkPixbuf

GdkPixbuf.Pixbuf.new_from_file

Versioning
If you do new releases the versioning of the GTK2 and GTK3 release should be different. For GTK2 releases you should use dotted versions for new development releases major versions. Let's have a look at hello-world as an example. The latest release of hello-world was version 3. Bug fix releases should be named 3.1 then 3.2 and so on. The new releases for the new development branch should be starting with a major number, in the case of hello-world version 4.

To minimise the maintainer overload we highly encourage you to only do bug-fix releases for the GTK2 branch. New features should only go into the new branch that is based on gobject-introspection and GTK3.

Note that some older versions of Sugar don't know how to parse dotted version numbers. An alternative to the above is to simply ensure that the version number of the GTK3 branch is always greater than (>) the version number of the GTK2 version.

GIT conventions
We've agreed that the GTK3 version should be in the master branch on gitorious.sugarlabs.org. The GTK2 version should be in a branch called gtk2.

Some helpful git foo:

From your repository, first create the GTK2 branch with: git branch gtk2

Then pull in all GTK3 changes on top of the master branch: git pull git://path/to/gtk3/repo

To move the gtk2 to gitorious.sugarlabs.org: git checkout gtk2 git push -u origin gtk2

Changes to the Clipboard
Two things to note:

1. You need to specify a clipboard using get clipboard = Gtk.Clipboard.get(Gdk.SELECTION_CLIPBOARD) 2. You need to pass a length to set_text clipboard.set_text(string, len(string))

See for more details.

Changes to Drag-and-Drop
Slightly different syntax: self.drag_dest_set(Gtk.DestDefaults.ALL, [],                          Gdk.DragAction.COPY) self.drag_dest_set_target_list(Gtk.TargetList.new([])) self.drag_dest_add_text_targets self.connect('drag_data_received', self._drag_data_received)

and: data.get_text or: data.get_image

See for more details.

Going from Drawable to Cairo
GTK-3 does not support gtk Drawable objects, so the first step is to get your activity running under Cairo.

import cairo

cairo_context = self.canvas.get_window.cairo_create
 * 1) From activity.Activity, you inherit a canvas.
 * 2) Create a Cairo context from the window.

xlib_surface = surface.create_similar(cairo.CONTENT_COLOR,                                     gtk.gdk.screen_width,                                      gtk.gdk.screen_height)
 * 1) Create an XLib surface to be used for drawing

cairo_context = cairo.Context(xlib_surface) cairo_context = gtk.gdk.CairoContext(cairo_context)
 * 1) You'll need a Cairo context from which you'll build a GTK Cairo context

cairo_context.move_to(0, 0) cairo_context.line_to(100, 100) cairo_context.set_source_rgb(r, g, b) cairo_context.rectangle(x, y, w, h) cairo_context.fill
 * 1) Use this context as you would a Drawable, substituting Cairo commands
 * 2) for gtk commands, e.g.,
 * 1) Cairo uses floats from 0 to 1 for RGB values

self.canvas.queue_draw_area(x, y, w, h)
 * 1) To invalidate a region to force a refresh, use:

def do_expose_event(self, event): # Create the cairo context cairo_context = self.canvas.get_window.cairo_create cairo_context.rectangle(event.area.x, event.area.y,                           event.area.width, event.area.height) cairo_context.clip cairo_context.set_source_surface(xlib_surface) cairo_context.paint
 * 1) Handle the expose event

Pango is a bit different when used with Cairo:

import pango, pangocairo

cairo_context = cairo.Context(xlib_surface)
 * 1) Again, from the xlib_surface...

cairo_context = pangocairo.CairoContext(cairo_context)
 * 1) Create a PangoCairo context

pango_layout = cairo_context.create_layout
 * 1) The pango layout is created from the Cairo context

fd = pango.FontDescription('Sans') fd.set_size(12 * pango.SCALE)
 * 1) You still use pango to set up font descriptions.

pango_layout.set_font_description(fd)
 * 1) Tell your pango layout about your font description

pango_layout.set_text('Hello world', -1)
 * 1) Write text to your pango layout

cairo_context.save cairo_context.translate(x, y) cairo_context.rotate(pi / 3) # You can rotate text and images in Cairo cairo_context.set_source_rgb(1, 0, 0)
 * 1) Position it within the Cairo context

cairo_context.update_layout(pango_layout) cairo_context.show_layout(pango_layout) cairo_context.restore
 * 1) Finally, draw the text

To draw a bitmap...

cairo_context = cairo.Context(xlib_surface)
 * 1) Again, from the xlib_surface...

cairo_context = gtk.gdk.CairoContext(cairo_context) cairo_context.set_source_pixbuf(pixbuf, x, y) cairo_context.rectangle(x, y, w, h) cairo_context.fill
 * 1) Create a gtk context

To read a pixel from the xlib surface...

cairo_surface = cairo.ImageSurface(cairo.FORMAT_RGB24, 1, 1); cairo_context = cairo.Context(cairo_surface) cairo_context.set_source_surface(xlib_surface, -x, -y) cairo_context.rectangle(0,0,1,1) cairo_context.set_operator(cairo.OPERATOR_SOURCE) cairo_context.fill cairo_surface.flush # ensure all writing is done return (ord(pixels[2]), ord(pixels[1]), ord(pixels[0]), 0)
 * 1) create a new 1x1 cairo surface
 * 1) translate xlib_surface so that target pixel is at 0, 0
 * 1) Read the pixel

Going from Cairo in GTK-2 to Cairo in GTK-3
(See http://developer.gnome.org/pangomm/2.28/annotated.html for more details) Not much changes, but...

The Cairo/Pango interaction is a little different: from gi.repository import Pango, PangoCairo

cairo_context = ... pango_layout = PangoCairo.create_layout(cairo_context) fd = Pango.FontDescription('Sans') fd.set_size(12 * Pango.SCALE) pango_layout.set_font_description(fd) pango_layout.set_text('Hello World', -1) cairo_context.set_source_rgb(1, 0, 0) PangoCairo.update_layout(cairo_context, pango_layout) PangoCairo.show_layout(cairo_context, pango_layout)

The get_extents method if different in PangoCairo. It calculates an extent as a Rectangle, but doesn't return anything. There is a method, get_logical_extents that returns a Rectangle. Alas, it is not necessarily available after v1.16. Note that Rectangle is not a list but a class with methods for get_x, get_y, get_width, and get_height, so you cannot iter over it.

Replacing pixmaps with Cairo
You need to replace your pixmaps with Cairo in GTK3. See http://developer.gnome.org/gtk3/3.5/ch24s02.html#idp129615008 for example code.

Taking a screenshot and making a thumbnail
To make a screenshot of the window: width, height = window.get_width, window.get_height thumb_surface = Gdk.Window.create_similar_surface(window,                                                 cairo.CONTENT_COLOR,                                                  width, height)

thumb_width, thumb_height = style.zoom(100), style.zoom(80) cairo_context = cairo.Context(thumb_surface) thumb_scale_w = thumb_width * 1.0 / width thumb_scale_h = thumb_height * 1.0 / height cairo_context.scale(thumb_scale_w, thumb_scale_h) Gdk.cairo_set_source_window(cairo_context, window, 0, 0) cairo_context.paint thumb_surface.write_to_png(png_path_or_filelike_object)

Creating a video widget
Haven't gotten this working yet, but some necessary changes include:

Instead of window.xid use get_property('window').get_xid

Instead of unset_flags(gtk.DOUBLE_BUFFERED) set_flags(gtk.APP_PAINTABLE) use set_double_buffered(False) set_app_paintable(True)

A more basic question is whether or not we migrate to gstreamer-1.0. If we do, some helpful documentation is found here.

Resources

 * PyGtk documentation
 * Gtk3: http://python-gtk-3-tutorial.readthedocs.org
 * gtk2: http://www.pygtk.org/docs/pygtk/


 * Reference Manual
 * Gtk3: http://developer.gnome.org/gtk3/3.4/


 * Gdk documentation:
 * Gdk3: http://developer.gnome.org/gdk/2.24/


 * Pango documentation:
 * GTK3: http://developer.gnome.org/pangomm


 * Gst-1.0 documentation
 * Gst-1: http://gstreamer.freedesktop.org/data/doc/gstreamer/head/gstreamer/html/index.html


 * Gst-1.0 porting hints
 * https://wiki.ubuntu.com/Novacut/GStreamer1.0

= More porting wiki pages =