Difference between revisions of "Features/GTK3/Porting"

Latest revision as of 02:16, 17 May 2018

Replaced with https://github.com/sugarlabs/sugar-docs/blob/master/src/gtk3-porting-guide.md

@@ Line 1: / Line 1: @@
-=Porting an exisiting activity to GTK3=
+Replaced with
-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.
+https://github.com/sugarlabs/sugar-docs/blob/master/src/gtk3-porting-guide.md
-==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 marked as "Construct" in the API documentation. 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 "Construct" property that we wish to set. In this case it is <b>label</b>, 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 Construct parameters] we see one called "label" which is equivalent. Therefore gtk_button_new_with_label("foo") should be called as:
- button = Gtk.Button(label="foo")
-==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

Difference between revisions of "Features/GTK3/Porting"

Latest revision as of 02:16, 17 May 2018

Navigation menu

Search