2011-12-09T20:39:07Z

DanielDrake:

This page includes repo details and how to get sugar-jhbuild set up with the GTK3 work.

== Repos ==

* http://git.sugarlabs.org/~erikos/sugar-toolkit/sugar-toolkit-gtk3 - branch 'master': this is the GTK3 port of sugar-toolkit
* http://git.sugarlabs.org/~erikos/sugar-toolkit/sugar-toolkit-gtk3 - branch 'sucrose-0.94': the GTK2 version of sugar-toolkit needs a handful of structure changes prompted by our GTK3 work. They are being committed here.
* http://git.sugarlabs.org/~erikos/sugar/sugar-gtk3 - branch 'master': we are not (yet) porting the sugar shell to GTK3, but a handful of structural changes are needed.
* <s>http://git.sugarlabs.org/sugar-artwork - branch 'gtk3': mainline sugar-artwork repo containing the new theme work (folder GTK3)</s>
* http://git.sugarlabs.org/~erikos/sugar-artwork/gtk3 - branch gtk3: now being used instead of the above artwork repo
* http://git.sugarlabs.org/~dsd/browse/browse-gtk3 - branch 'master': Browse port to GTK3
* http://git.sugarlabs.org/hello-world - branch 'master': hello-world ported to GTK3
* http://cgit.collabora.com/git/user/rgs/abacus-gtk3/ - branch 'master': Abacus ported to GTK3 and to use cairo for drawing

== jhbuild setup ==

Start with a working "normal" sugar-jhbuild installation.

Compile/install a fixed pygobject with [https://bugzilla.gnome.org/show_bug.cgi?id=662994 this chain-up fix]. F16 build available from http://koji.fedoraproject.org/koji/taskinfo?taskID=3473257

Apply this patch to sugar-jhbuild: http://dev.laptop.org/~dsd/20111029/sugar-jhbuild-sugar-toolkit-gtk3.patch and build the new GTK3 based sugar toolkit:

<pre>
./sugar-jhbuild build sugar-toolkit-gtk3
</pre>

The sugar-toolkit gtk2 version needs some modifications for some restructuring that gtk3 work has prompted. Check out our branch where this happens;

<pre>
cd source/sugar-toolkit
git remote add -f gtk2-mods-for-gtk3 git://git.sugarlabs.org/~erikos/sugar-toolkit/sugar-toolkit-gtk3.git
git checkout -b gtk2-mods-for-gtk3 gtk2-mods-for-gtk3/sucrose-0.94
make install
cd ../..
</pre>

And similarly for sugar:

<pre>
cd source/sugar
git remote add -f erikos-gtk3 git://git.sugarlabs.org/~erikos/sugar/sugar-gtk3.git
git checkout -b gtk3 erikos-gtk3/master
make install
cd ../..
</pre>

And for sugar-artwork:

<pre>
cd source/sugar-artwork
git remote add -f erikos-gtk3 git://git.sugarlabs.org/~erikos/sugar-artwork/gtk3.git
git checkout -b gtk3 erikos-gtk3/master
make install
cd ../..
</pre>

== Pending upstream work ==

All of these have been worked around (or will be worked around) for now, at the sugar level.

* gobject introspection bindings for librsvg: https://bugzilla.gnome.org/show_bug.cgi?id=663049 ''Solved: fix has been pushed to librsvg master in http://git.gnome.org/browse/librsvg/'', is in 2.35.0
** related gobject-introspection fix for libxml2 https://bugzilla.gnome.org/show_bug.cgi?id=663048 ''Solved: fix has been pushed to gobject introspection 42e9ea858c454646ecf5d4b9579ea7a2ce4192fd''
* enable GDK introspection access to X11 window properties: https://bugzilla.gnome.org/show_bug.cgi?id=663261. [http://git.sugarlabs.org/~erikos/sugar-toolkit/sugar-toolkit-gtk3/commit/c22ec39980f47e78f2341da54f13324333e3d2f0 current workaround patch in sugar-toolkit ] (Raul)
* extend gio mime type API so that we can drop our xdgmime copy (e.g. need to be able to get default file extension for a given mime type)
* chaining up in vfuncs: https://bugzilla.gnome.org/show_bug.cgi?id=662994 ''Solved: fix has been pushed to pygobject master http://git.gnome.org/browse/pygobject/commit/?id=2fd3aa9d4ca0906a5e609845ee500ba72e358f94''
* implementing GtkContainer::forall: https://bugzilla.gnome.org/show_bug.cgi?id=644926, also needs https://bugzilla.gnome.org/show_bug.cgi?id=663052
* missing parts in pango introspection, [https://bugzilla.gnome.org/show_bug.cgi?id=646788 646788] does contain what we need (there are quite a few introspection related pango bugs open atm, from a quick look I found https://bugzilla.gnome.org/show_bug.cgi?id=660070, https://bugzilla.gnome.org/show_bug.cgi?id=627973, https://bugzilla.gnome.org/show_bug.cgi?id=645792, https://bugzilla.gnome.org/show_bug.cgi?id=645871, https://bugzilla.gnome.org/show_bug.cgi?id=646788 even with patches attached already for a while)

Features/GTK3/Porting

2011-11-10T18:03:19Z

DanielDrake:

=Porting an exisiting activity to GTK3=
In this guide we will handle the porting of the an existing activity from using GTK2 to use GTK3. Furthermore we will show you what changes you need to do to make usage of the new sugar toolkit that uses now GTK3 as well. In this guide we will use the [http://git.sugarlabs.org/hello-world hello-world] activity as a simple example.

==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.

The latest release was version 3. 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. In git you can create a branch like this:

<pre>
git branch sugar-0.94
</pre>

This has created a local branch. You can show the result by running 'git branch', you should see the following:

<pre>
[erikos@T61 helloworld]$ git branch
* master
sugar-0.94
</pre>

The 'sugar-0.94' branch is only locally available so far which can be seen by running 'git branch -r' which shows the remote branches:

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

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:
<pre>
git push origin sugar-0.94
</pre>

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

You can switch now between those branches using 'git checkout <branch>'. 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).
<pre>
git checkout sugar-0.94
git checkout master
</pre>

==Cleanup, adopt to API changes in the sugar-toolkit==
''This should be done only on the master branch''! In the new sugar-toolkit 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

==Port the activity from GTK-2 to GTK-3==
The first thing that changes is the importing instruction for GTK,
<pre>import gtk</pre>
has to be replaced by
<pre>from gi.repository import Gtk</pre>
Then you have to change each call that involves Gtk, for example creating a button will look now like this:
<pre>button = Gtk.Button()</pre>

A simple hello world program in GTK-3 does look like this:
<pre>
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()
</pre>

For porting your activity you do have to change your calls for accesing 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
<pre>from sugar.activity import activity</pre>
to
<pre>from sugar3.activity import activity</pre>

The changes that were needed to port the hello-world activity can be seen in [http://git.sugarlabs.org/hello-world/mainline/commit/508e1c518b56cbde5508e560c8a2ff38a3518583 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 [http://git.gnome.org/browse/pygobject/tree/pygi-convert.sh pygi-convert.sh], more info about the script can be found in [http://live.gnome.org/PyGObject/IntrospectionPorting the PyGObject Introspection Porting guide].

If you are having trouble finding how a particular GTK class/method/constant has been named in PyGI, run [http://dev.laptop.org/~dsd/20110806/pygi-enumerate.py pygi-enumerate.py] and grep the output. (this app lists all identified methods and constants).

=== 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 [http://developer.gnome.org/gtk3/3.2/GtkExpander.html#GtkExpander.properties 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 [http://developer.gnome.org/gtk3/3.2/GtkButton.html#GtkButton.properties 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:
# The widget to pack into the container
# '''expand''': Whether the child should receive extra space when the container grows (default True)
# '''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)
# '''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:

# If '''expand''' was not set, use value True
# 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)
# 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:
<pre>box.pack_start(widget, expand=True, fill=False, padding=4)</pre>
is much more readable than:
<pre>box.pack_start(widget, True, False, 4)</pre>

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.
<pre>box.pack_start(widget, True, True, 0)</pre>
can be replaced with:
<pre>box.add(widget)</pre>

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.:
<pre>vbox = Gtk.Box(orientation=Gtk.Orientation.VERTICAL)</pre>

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:
# 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)
# 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:
# 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.
# yalign: the fraction of vertical free space above the child widget. Ranges from 0.0 to 1.0. Default value 0.0.
# xscale: the fraction of horizontal free space that the child widget absorbs, from 0.0 to 1.0. Default value 0.0.
# 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:
# xalign: default value 0.5
# yalign: default value 0.5
# xscale: default value 1
# 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.

==Make a release==
===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 this case 4.

== Tips to Activity Developers ==

'''this is just a stub'''

* GTK-3 does not support Drawable, so the first step is to get your activity running under Cairo.
:* Example: abacus-cairo
:* Example: abacus-gtk3
* The conversion script (here) leaves a few things to be done by hand:
:* Notes from conversion from abacus-cairo to abacus-gtk3

* Notes from the TurtleArt conversion
* Removing Hippo

===Taking a screenshot and making a thumbnail===
To make a screenshot of the window:
<pre>
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)
</pre>

Features/GTK3/Porting

2011-11-10T18:02:50Z

DanielDrake: /* HBox, VBox, pack_start and pack_end */

=Porting an exisiting activity to GTK3=
In this guide we will handle the porting of the an existing activity from using GTK2 to use GTK3. Furthermore we will show you what changes you need to do to make usage of the new sugar toolkit that uses now GTK3 as well. In this guide we will use the [http://git.sugarlabs.org/hello-world hello-world] activity as a simple example.

==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.

The latest release was version 3. 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. In git you can create a branch like this:

<pre>
git branch sugar-0.94
</pre>

This has created a local branch. You can show the result by running 'git branch', you should see the following:

<pre>
[erikos@T61 helloworld]$ git branch
* master
sugar-0.94
</pre>

The 'sugar-0.94' branch is only locally available so far which can be seen by running 'git branch -r' which shows the remote branches:

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

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:
<pre>
git push origin sugar-0.94
</pre>

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

You can switch now between those branches using 'git checkout <branch>'. 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).
<pre>
git checkout sugar-0.94
git checkout master
</pre>

==Cleanup, adopt to API changes in the sugar-toolkit==
''This should be done only on the master branch''! In the new sugar-toolkit 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

==Port the activity from GTK-2 to GTK-3==
The first thing that changes is the importing instruction for GTK,
<pre>import gtk</pre>
has to be replaced by
<pre>from gi.repository import Gtk</pre>
Then you have to change each call that involves Gtk, for example creating a button will look now like this:
<pre>button = Gtk.Button()</pre>

A simple hello world program in GTK-3 does look like this:
<pre>
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()
</pre>

For porting your activity you do have to change your calls for accesing 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
<pre>from sugar.activity import activity</pre>
to
<pre>from sugar3.activity import activity</pre>

The changes that were needed to port the hello-world activity can be seen in [http://git.sugarlabs.org/hello-world/mainline/commit/508e1c518b56cbde5508e560c8a2ff38a3518583 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 [http://git.gnome.org/browse/pygobject/tree/pygi-convert.sh pygi-convert.sh], more info about the script can be found in [http://live.gnome.org/PyGObject/IntrospectionPorting the PyGObject Introspection Porting guide].

If you are having trouble finding how a particular GTK class/method/constant has been named in PyGI, run [http://dev.laptop.org/~dsd/20110806/pygi-enumerate.py pygi-enumerate.py] and grep the output. (this app lists all identified methods and constants).

=== 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 [http://developer.gnome.org/gtk3/3.2/GtkExpander.html#GtkExpander.properties 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 [http://developer.gnome.org/gtk3/3.2/GtkButton.html#GtkButton.properties 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:
# The widget to pack into the container
# '''expand''': Whether the child should receive extra space when the container grows (default True)
# '''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)
# '''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:

# If '''expand''' was not set, use value True
# 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)
# 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:
<pre>box.pack_start(widget, expand=True, fill=False, padding=4)</pre>
is much more readable than:
<pre>box.pack_start(widget, True, False, 4)</pre>

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.
<pre>box.pack_start(widget, True, True, 0)</pre>
can be replaced with:
<pre>box.add(widget)</pre>

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.:
<pre>vbox = Gtk.Box(orientation=Gtk.Orientation.VERTICAL)</pre>

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:
# 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)
# 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:
# 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.
# yalign: the fraction of vertical free space above the child widget. Ranges from 0.0 to 1.0. Default value 0.0.
# xscale: the fraction of horizontal free space that the child widget absorbs, from 0.0 to 1.0. Default value 0.0.
# 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:
# xalign: default value 0.5
# yalign: default value 0.5
# xscale: default value 1
# 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.

==Make a release==
===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 this case 4.

==Info for merging==
To document:
* Gtk.Alignment() no longer has default parameters - specify all 4

Conversion script badness:

<pre>
- if self.orientation == gtk.ORIENTATION_HORIZONTAL:
+ if self.orientation == Gtk.ORIENTATION_HORIZONTAL:
</pre>

should be Orientation.HORIZONTAL

== Tips to Activity Developers ==

'''this is just a stub'''

* GTK-3 does not support Drawable, so the first step is to get your activity running under Cairo.
:* Example: abacus-cairo
:* Example: abacus-gtk3
* The conversion script (here) leaves a few things to be done by hand:
:* Notes from conversion from abacus-cairo to abacus-gtk3

* Notes from the TurtleArt conversion
* Removing Hippo

===Taking a screenshot and making a thumbnail===
To make a screenshot of the window:
<pre>
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)
</pre>

Features/GTK3/Porting

2011-11-10T17:47:12Z

DanielDrake: /* Constructor considerations */

=Porting an exisiting activity to GTK3=
In this guide we will handle the porting of the an existing activity from using GTK2 to use GTK3. Furthermore we will show you what changes you need to do to make usage of the new sugar toolkit that uses now GTK3 as well. In this guide we will use the [http://git.sugarlabs.org/hello-world hello-world] activity as a simple example.

==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.

The latest release was version 3. 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. In git you can create a branch like this:

<pre>
git branch sugar-0.94
</pre>

This has created a local branch. You can show the result by running 'git branch', you should see the following:

<pre>
[erikos@T61 helloworld]$ git branch
* master
sugar-0.94
</pre>

The 'sugar-0.94' branch is only locally available so far which can be seen by running 'git branch -r' which shows the remote branches:

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

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:
<pre>
git push origin sugar-0.94
</pre>

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

You can switch now between those branches using 'git checkout <branch>'. 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).
<pre>
git checkout sugar-0.94
git checkout master
</pre>

==Cleanup, adopt to API changes in the sugar-toolkit==
''This should be done only on the master branch''! In the new sugar-toolkit 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

==Port the activity from GTK-2 to GTK-3==
The first thing that changes is the importing instruction for GTK,
<pre>import gtk</pre>
has to be replaced by
<pre>from gi.repository import Gtk</pre>
Then you have to change each call that involves Gtk, for example creating a button will look now like this:
<pre>button = Gtk.Button()</pre>

A simple hello world program in GTK-3 does look like this:
<pre>
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()
</pre>

For porting your activity you do have to change your calls for accesing 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
<pre>from sugar.activity import activity</pre>
to
<pre>from sugar3.activity import activity</pre>

The changes that were needed to port the hello-world activity can be seen in [http://git.sugarlabs.org/hello-world/mainline/commit/508e1c518b56cbde5508e560c8a2ff38a3518583 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 [http://git.gnome.org/browse/pygobject/tree/pygi-convert.sh pygi-convert.sh], more info about the script can be found in [http://live.gnome.org/PyGObject/IntrospectionPorting the PyGObject Introspection Porting guide].

If you are having trouble finding how a particular GTK class/method/constant has been named in PyGI, run [http://dev.laptop.org/~dsd/20110806/pygi-enumerate.py pygi-enumerate.py] and grep the output. (this app lists all identified methods and constants).

=== 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 [http://developer.gnome.org/gtk3/3.2/GtkExpander.html#GtkExpander.properties 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 [http://developer.gnome.org/gtk3/3.2/GtkButton.html#GtkButton.properties 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:
# The widget to pack into the container
# '''expand''': Whether the child should receive extra space when the container grows (default True)
# '''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)
# '''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:

# If '''expand''' was not set, use value True
# 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)
# 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:
<pre>box.pack_start(widget, expand=True, fill=False, padding=4)</pre>
is much more readable than:
<pre>box.pack_start(widget, True, False, 4)</pre>

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.
<pre>box.pack_start(widget, True, True, 0)</pre>
can be replaced with:
<pre>box.add(widget)</pre>

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.:
<pre>vbox = Gtk.Box(orientation=Gtk.Orientation.VERTICAL)</pre>

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:
# 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)
# Every single pack_start call that has expand=False and padding=0 (and any value of fill) can be converted to .add() for cleanliness

==Make a release==
===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 this case 4.

==Info for merging==
To document:
* Gtk.Alignment() no longer has default parameters - specify all 4

Conversion script badness:

<pre>
- if self.orientation == gtk.ORIENTATION_HORIZONTAL:
+ if self.orientation == Gtk.ORIENTATION_HORIZONTAL:
</pre>

should be Orientation.HORIZONTAL

== Tips to Activity Developers ==

'''this is just a stub'''

* GTK-3 does not support Drawable, so the first step is to get your activity running under Cairo.
:* Example: abacus-cairo
:* Example: abacus-gtk3
* The conversion script (here) leaves a few things to be done by hand:
:* Notes from conversion from abacus-cairo to abacus-gtk3

* Notes from the TurtleArt conversion
* Removing Hippo

===Taking a screenshot and making a thumbnail===
To make a screenshot of the window:
<pre>
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)
</pre>

Features/GTK3/Porting

2011-11-09T22:58:01Z

DanielDrake: /* Constructor considerations */

Features/GTK3/Porting

2011-11-09T22:53:44Z

DanielDrake: /* Constructor considerations */

Features/GTK3/Porting

2011-11-09T22:47:47Z

DanielDrake: /* Port the activity from GTK-2 to GTK-3 */

Features/GTK3/Development

2011-10-30T21:52:54Z

DanielDrake:

This page includes repo details and how to get sugar-jhbuild set up with the GTK3 work.

== Repos ==

* http://git.sugarlabs.org/~erikos/sugar-toolkit/sugar-toolkit-gtk3 - this is the GTK3 port of sugar-toolkit
* http://git.sugarlabs.org/~erikos/sugar-toolkit/sugar-toolkit-gtk3 branch sucrose-0.94 - the GTK2 version of sugar-toolkit needs a handful of structure changes prompted by our GTK3 work. They are being committed here.
* http://git.sugarlabs.org/~erikos/sugar/sugar-gtk3 - we are not (yet) porting the sugar shell to GTK3, but a handful of structural changes are needed.
* Mainline sugar-artwork repo, branch 'gtk3'
* Browse port to GTK3: http://git.sugarlabs.org/~dsd/browse/browse-gtk3

== jhbuild setup ==

Start with a working "normal" sugar-jhbuild installation.

Compile/install a fixed pygobject with [https://bugzilla.gnome.org/show_bug.cgi?id=662994 this chain-up fix]. F16 build available from http://koji.fedoraproject.org/koji/taskinfo?taskID=3473257

Apply this patch to sugar-jhbuild: http://dev.laptop.org/~dsd/20111029/sugar-jhbuild-sugar-toolkit-gtk3.patch

Select gtk3 brach of sugar-artwork for the new theme:

<pre>
cd source/sugar-artwork
git pull
git checkout gtk3
make install
cd ../..
</pre>

The sugar-toolkit gtk2 version needs some modifications for some restructuring that gtk3 work has prompted. Check out our branch where this happens;

<pre>
cd source/sugar-toolkit
git remote add -f gtk2-mods-for-gtk3 git://git.sugarlabs.org/~erikos/sugar-toolkit/sugar-toolkit-gtk3.git
git checkout -b gtk2-mods-for-gtk3 gtk2-mods-for-gtk3/sucrose-0.94
make install
cd ../..
</pre>

And similarly for sugar:

<pre>
cd source/sugar
git remote add -f erikos-gtk3 git://git.sugarlabs.org/~erikos/sugar/sugar-gtk3.git
git checkout -b gtk3 erikos-gtk3/master
make install
cd ../..
</pre>

== Pending upstream work ==

All of these have been worked around (or will be worked around) for now, at the sugar level.

* gobject introspection bindings for librsvg: https://bugzilla.gnome.org/show_bug.cgi?id=663049
* enable GDK introspection access to X11 window properties (Raul)
* extend gio mime type API so that we can drop our xdgmime copy (e.g. need to be able to get default file extension for a given mime type)
* chaining up in vfuncs: https://bugzilla.gnome.org/show_bug.cgi?id=662994
* implementing GtkContainer::forall: https://bugzilla.gnome.org/show_bug.cgi?id=644926, also needs https://bugzilla.gnome.org/show_bug.cgi?id=663052

Features/GTK3/Development

2011-10-30T15:24:09Z

DanielDrake:

This page includes repo details and how to get sugar-jhbuild set up with the GTK3 work.

== Repos ==

* http://git.sugarlabs.org/~erikos/sugar-toolkit/sugar-toolkit-gtk3 - this is the GTK3 port of sugar-toolkit
* http://git.sugarlabs.org/~erikos/sugar-toolkit/sugar-toolkit-gtk3 branch sucrose-0.94 - the GTK2 version of sugar-toolkit needs a handful of structure changes prompted by our GTK3 work. They are being committed here.
* http://git.sugarlabs.org/~erikos/sugar/sugar-gtk3 - we are not (yet) porting the sugar shell to GTK3, but a handful of structural changes are needed.
* Mainline sugar-artwork repo, branch 'gtk3'

== jhbuild setup ==

Start with a working "normal" sugar-jhbuild installation.

Compile/install a fixed pygobject with [https://bugzilla.gnome.org/show_bug.cgi?id=662994 this chain-up fix]. F16 build available from http://koji.fedoraproject.org/koji/taskinfo?taskID=3473257

Apply this patch to sugar-jhbuild: http://dev.laptop.org/~dsd/20111029/sugar-jhbuild-sugar-toolkit-gtk3.patch

Select gtk3 brach of sugar-artwork for the new theme:

<pre>
cd source/sugar-artwork
git pull
git checkout gtk3
make install
cd ../..
</pre>

The sugar-toolkit gtk2 version needs some modifications for some restructuring that gtk3 work has prompted. Check out our branch where this happens;

<pre>
cd source/sugar-toolkit
git remote add -f gtk2-mods-for-gtk3 git://git.sugarlabs.org/~erikos/sugar-toolkit/sugar-toolkit-gtk3.git
git checkout -b gtk2-mods-for-gtk3 gtk2-mods-for-gtk3/sucrose-0.94
make install
cd ../..
</pre>

And similarly for sugar:

<pre>
cd source/sugar
git remote add -f erikos-gtk3 git://git.sugarlabs.org/~erikos/sugar/sugar-gtk3.git
git checkout -b gtk3 erikos-gtk3/master
make install
cd ../..
</pre>

== Pending upstream work ==

All of these have been worked around (or will be worked around) for now, at the sugar level.

* gobject introspection bindings for librsvg: https://bugzilla.gnome.org/show_bug.cgi?id=663049
* enable GDK introspection access to X11 window properties (Raul)
* extend gio mime type API so that we can drop our xdgmime copy (e.g. need to be able to get default file extension for a given mime type)

Features/GTK3/Development

2011-10-30T11:35:35Z

DanielDrake:

This page includes repo details and how to get sugar-jhbuild set up with the GTK3 work.

== Repos ==

* http://git.sugarlabs.org/~erikos/sugar-toolkit/sugar-toolkit-gtk3 - this is the GTK3 port of sugar-toolkit
* http://git.sugarlabs.org/~erikos/sugar-toolkit/sugar-toolkit-gtk3 branch sucrose-0.94 - the GTK2 version of sugar-toolkit needs a handful of structure changes prompted by our GTK3 work. They are being committed here.
* http://git.sugarlabs.org/~erikos/sugar/sugar-gtk3 - we are not (yet) porting the sugar shell to GTK3, but a handful of structural changes are needed.
* Mainline sugar-artwork repo, branch 'gtk3'

== jhbuild setup ==

Start with a working "normal" sugar-jhbuild installation.

Compile/install a fixed pygobject with [https://bugzilla.gnome.org/show_bug.cgi?id=662994 this chain-up fix]. F16 build available from http://koji.fedoraproject.org/koji/taskinfo?taskID=3473257

Apply this patch to sugar-jhbuild: http://dev.laptop.org/~dsd/20111029/sugar-jhbuild-sugar-toolkit-gtk3.patch

Select gtk3 brach of sugar-artwork for the new theme:

<pre>
cd source/sugar-artwork
git pull
git checkout gtk3
make install
cd ../..
</pre>

The sugar-toolkit gtk2 version needs some modifications for some restructuring that gtk3 work has prompted. Check out our branch where this happens;

<pre>
cd source/sugar-toolkit
git remote add -f gtk2-mods-for-gtk3 git://git.sugarlabs.org/~erikos/sugar-toolkit/sugar-toolkit-gtk3.git
git checkout -b gtk2-mods-for-gtk3 gtk2-mods-for-gtk3/sucrose-0.94
make install
cd ../..
</pre>

And similarly for sugar:

<pre>
cd source/sugar
git remote add -f erikos-gtk3 git://git.sugarlabs.org/~erikos/sugar/sugar-gtk3.git
git checkout -b gtk3 erikos-gtk3/master
make install
cd ../..
</pre>

Features/GTK3/Porting

2011-10-30T07:01:22Z

DanielDrake:

To port PyGTK to PyGI, read this: https://live.gnome.org/PyGObject/IntrospectionPorting (especially the section abouut pygi-convert.sh)

If you are having trouble finding how a particular GTK class/method/constant has been named in PyGI, run [http://dev.laptop.org/~dsd/20110806/pygi-enumerate.py pygi-enumerate.py] and grep the output. (this app lists all identified methods and constants)

To document:
* Gtk.Alignment() no longer has default parameters - specify all 4

Conversion script badness:

<pre>
- if self.orientation == gtk.ORIENTATION_HORIZONTAL:
+ if self.orientation == Gtk.ORIENTATION_HORIZONTAL:
</pre>

should be Orientation.HORIZONTAL

Features/GTK3/Porting

2011-10-30T06:50:49Z

DanielDrake:

Features/GTK3/Development

2011-10-29T10:46:54Z

DanielDrake:

2011-08-06T14:26:28Z

DanielDrake: Created page with "To port PyGTK to PyGI, read this: https://live.gnome.org/PyGObject/IntrospectionPorting (especially the section abouut pygi-convert.sh) If you are having trouble finding how a p..."