43
edits
Changes
Jump to navigation
Jump to search
Line 1:
Line 1: − + − + Line 8:
Line 8: − + Line 17:
Line 17: + Line 24:
Line 25: − + Line 32:
Line 33: − + Line 39:
Line 40: − + − + Line 57:
Line 58: − − 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 [https://developer.sugarlabs.org/sugar3/ 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 − Line 145:
Line 140: − + Line 169:
Line 164: − + Line 198:
Line 193: − + Line 206:
Line 201: − + − + Line 271:
Line 266: − + Line 399:
Line 394: − + − + Line 496:
Line 491: − + − + − + − +
Standardise names, and remove redundancy
=Porting an existing activity to GTK3=
=Porting an existing activity to GTK+ 3=
This is a guide to porting an existing activity from GTK2 to [http://developer.gnome.org/gtk3/stable/ GTK3]. It also shows the changes to use the new Sugar toolkit that also now uses [[Features/GTK3|GTK3]]. This guide uses the [https://github.com/sugarlabs/hello-world hello-world] activity as a simple example.
This is a guide to porting an existing activity from GTK+ 2 to [http://developer.gnome.org/gtk3/stable/ GTK+ 3]. It also shows the changes to use the new Sugar toolkit that also now uses [[Features/GTK3|GTK+ 3]]. This guide uses the [https://github.com/sugarlabs/hello-world hello-world] activity as a simple example.
Here are some instances of porting activities, for reference:
Here are some instances of porting activities, for reference:
* [https://github.com/sugarlabs/iknowMadagascar/commit/44ba42645ac4fcd9e06b4add7fa3b6ce2e0d9c3d Port of I-know-Madagascar]
* [https://github.com/sugarlabs/iknowMadagascar/commit/44ba42645ac4fcd9e06b4add7fa3b6ce2e0d9c3d Port of I-know-Madagascar]
=Steps to Port an Activity to Gtk3=
=Steps to Port an Activity to GTK+ 3=
#Read the [http://wiki.sugarlabs.org/go/Features/GTK3 Sugar Official Wiki]
#Read the [http://wiki.sugarlabs.org/go/Features/GTK3 Sugar Official Wiki]
#Resolve any existing pull requests before porting to avoid conflicts at a later stage.
#Resolve any existing pull requests before porting to avoid conflicts at a later stage.
==API changes in sugar-toolkit ==
==API changes in sugar-toolkit ==
* The namespace is changed from <code>sugar</code> to <code>sugar3</code>, trying to reflect that GTK+ 3 is the underlying technology.
* The keep button has been removed
* The keep button has been removed
* The old-style toolbar has been removed
* The old-style toolbar has been removed
* <code>sugar3.activity.Activity</code> does not have the ''window'' attribute. Use the <code>.get_window()</code> method instead.
* <code>sugar3.activity.Activity</code> does not have the ''window'' attribute. Use the <code>.get_window()</code> method instead.
==Port the activity from GTK2 to GTK3==
==Port the activity from GTK+ 2 to GTK+ 3==
To start, change the importing instruction for GTK from
To start, change the importing instruction for GTK from
import gtk
import gtk
from gi.repository import Gtk
from gi.repository import Gtk
Note that <code>require_version</code> needs to called only the first time when Gtk is being imported.
Note that <code>require_version</code> needs to called only the first time when GTK is being imported.
Similar imports that may be used are:
Similar imports that may be used are:
</pre>
</pre>
Then you have to change each call that involves Gtk, for example creating a button will look now like this:
Then you have to change each call that involves GTK, for example creating a button will look now like this:
button = Gtk.Button()
button = Gtk.Button()
A simple hello world program in GTK3 looks like this:
A simple hello world program in GTK+ 3 looks like this:
<pre>
<pre>
from gi.repository import Gtk
from gi.repository import Gtk
Gtk.main()
Gtk.main()
</pre>
</pre>
The changes that were needed to port the hello-world activity can be seen in [https://github.com/sugarlabs/hello-world/commit/508e1c518b56cbde5508e560c8a2ff38a3518583 this commit.]
The changes that were needed to port the hello-world activity can be seen in [https://github.com/sugarlabs/hello-world/commit/508e1c518b56cbde5508e560c8a2ff38a3518583 this commit.]
====Simple example on creating a toolbar====
====Simple example on creating a toolbar====
One of Sugar's activity most unique user interface includes the toolbar. In order to reference the relevant modules and graphics, the sugar3 library has to be imported. These are the relevant ones that would enable us to create a simple toolbar containing the activity button and the stop button.
One of Sugar's activity most unique user interface includes the toolbar. In order to reference the relevant modules and graphics, the sugar3 library has to be imported. These are the relevant ones that would enable us to create a simple toolbar containing the activity button and the stop button.
=== HBox, VBox, pack_start and pack_end ===
=== 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:
GtkHBox and GtkVBox, commonly used containers in GTK+ 2 code, have pack_start and pack_end methods. These take 4 parameters:
# The widget to pack into the container
# The widget to pack into the container
# '''expand''': Whether the child should receive extra space when the container grows (default True)
# '''expand''': Whether the child should receive extra space when the container grows (default True)
<pre>box.add(widget)</pre>
<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 GTK3. The replacement is to use GtkBox directly, and you may wish to make this change now. e.g.:
This is as far as you need to go for now. However, in GTK+ 3, GtkVBox and GtkHBox have been deprecated, which means they might be removed in GTK+ 3. 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>
<pre>vbox = Gtk.Box(orientation=Gtk.Orientation.VERTICAL)</pre>
<pre>hbox = Gtk.Box(orientation=Gtk.Orientation.HORIZONTAL, homogeneous=True, spacing=8)</pre>
<pre>hbox = Gtk.Box(orientation=Gtk.Orientation.HORIZONTAL, homogeneous=True, spacing=8)</pre>
The user supplied positioning function now takes different parameters. These are menu, x, y, push_in and user_data.
The user supplied positioning function now takes different parameters. These are menu, x, y, push_in and user_data.
=== Gdk ===
=== Gdk ===
Previously, gdk was an attribute of the gtk module, which means that it can be called through gtk. For example, if we want to use color_parse():
Previously, gdk was an attribute of the GTK module, which means that it can be called through GTK. For example, if we want to use color_parse():
gtk.gdk.color_parse(color)
gtk.gdk.color_parse(color)
However, what we have to do now is:
However, what we have to do now is:
=== Pango ===
=== Pango ===
Following the release of Gtk3, we should not be importing pango like this:
Following the release of GTK+ 3, we should not be importing pango like this:
import pango
import pango
In fact, we can now import pango as an attribute within the gtk3 library:
In fact, we can now import pango as an attribute within the GTK+ 3 library:
from gi.repository import Pango as pango
from gi.repository import Pango as pango
=== Gio.Settings from GConf ===
=== Gio.Settings from GConf ===
===Going from Drawable to Cairo===
===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.
GTK+ 3 does not support GTK Drawable objects, so the first step is to get your activity running under Cairo.
<pre>
<pre>
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.
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.
Note that the <samp>cairo.Region</samp> will no longer work in Gtk+3
Note that the <samp>cairo.Region</samp> will no longer work in GTK+3
==== Replacing pixmaps with Cairo ====
==== Replacing pixmaps with Cairo ====
You need to replace your pixmaps with Cairo in GTK3. For an example on how this is done, see: http://developer.gnome.org/gtk3/3.5/ch24s02.html#idp129615008
You need to replace your pixmaps with Cairo in GTK+ 3. For an example on how this is done, see: http://developer.gnome.org/gtk3/3.5/ch24s02.html#idp129615008
===Taking a screenshot and making a thumbnail===
===Taking a screenshot and making a thumbnail===
=Resources=
=Resources=
*PyGI Documentation: https://lazka.github.io/pgi-docs/
*PyGI Documentation: https://lazka.github.io/pgi-docs/
*PyGtk documentation
*PYGTK documentation
**Gtk3: [http://python-gtk-3-tutorial.readthedocs.org/ http://python-gtk-3-tutorial.readthedocs.org]
**GTK+ 3: [http://python-gtk-3-tutorial.readthedocs.org/ http://python-gtk-3-tutorial.readthedocs.org]
**gtk2: http://www.pygtk.org/docs/pygtk/
**GTK+ 2: http://www.pygtk.org/docs/pygtk/
*Reference Manual
*Reference Manual
**Gtk3: http://developer.gnome.org/gtk3/3.4/
**GTK+ 3: http://developer.gnome.org/gtk3/3.4/
*Gdk documentation:
*Gdk documentation:
**Gdk3: http://developer.gnome.org/gdk/2.24/
**Gdk3: http://developer.gnome.org/gdk/2.24/