Features/GTK3/Porting/GetBooks

This page is being performed while I'm porting Get Books Activity to Gtk3.

There is a ticket with some useful information that I'm using on the porting and to keep tracking this port. Besides, this wiki page will be useful to write some code snippets about what are the difficulties that I'm having on the port and maybe can be useful for someone else.

Steps that you should follow to Port an Activity to Gtk3

1. Read the Sugar Official Wiki
2. Read the specific Sugar Wiki Page that talks about how to porting. Please, follow those steps and if you have a suggestion about the process you can contact with us and let us know.
3. Comment on IRC about the Activity that you are going to Port (#sugar on irc.freenode.net)
4. Run this script that will convert automatically things as much as it can. This is to avoid some stressful manually conversions that a "simple script" can do using sed :)

Tips and Tricks

Create a "new" activity from the git version

It's really useful to keep the "original" version of the Activity that we are porting to know how it was working before the port. Sometimes you find an strange behaviour on the ported version of the activity and you think that you don't touch that part of the code or that the change shouldn't affect it. In these cases it's good to run the "original" version and test how it worked before the port.

I ask to the Sugar Developers mailing list about how to do this and they told me that I should change the bundle_id. In fact, we have to change the bundle_id and the name from the activity/activity.info file. I used:

name = Get Books Gtk3
bundle_id = git.GetBooksActivity

After this, you should run the build and dev setup commands:

cd get-books
python setup.py dev
python setup.py build

Now, you will see two Get Books activities: one called just "Get Books" and another one called "Get Books Gtk3".

Script to list all the enumeration

There is an script that list all the Gtk methods and it's useful to know the new name and from where it comes from. For example:

[humitos@michifus get-books]$ 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)
[humitos@michifus get-books]$

Use the same keyboard and mouse

If you have an XO, I'm sure you want to take a look at this...

Code Snippets

On this section I will explain all the things that I had to do manually and took me some time to find out. Some of them are really simple but time-consuming so the idea is to reduce that time as much as we can.

Migrate custom signals

If you have defined custom gtk objects with custom signal you should migrate them to the new way to do this.

You should replace this:

from gobject import signal_new, TYPE_INT, TYPE_STRING, TYPE_BOOLEAN, \
TYPE_PYOBJECT, TYPE_NONE, SIGNAL_RUN_LAST

signal_new('extlistview-modified', gtk.TreeView, SIGNAL_RUN_LAST, TYPE_NONE,
            ())

by adding the signal definition inside the object that you are creating using the __gsignals__ dictionary like this (in this case Gtk.TreeView is the class that our object inherits):

from gi.repository import GObject

class ExtListViewColumn(Gtk.TreeViewColumn):
    __gsignals__ = {
      'extlistview-modified': (GObject.SignalFlags.RUN_LAST, None,
                             ()),
       }

The last argument of the signal definition are the argument types that the callback will receive. For example, that tuple could be (str, int) if the callback receives two arguments, a string and an integer (first and second argument position)

References / Useful links

• Guide you should follow: http://wiki.sugarlabs.org/go/Features/GTK3/Porting
• 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/
• OLPC Documentation: http://wiki.laptop.org/go/Activities/PortingToGtk3