Features/GTK3/Porting - Revision history

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

2018-05-17T07:16:12Z

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

Chimosky at 17:47, 6 April 2018

2018-04-06T17:47:55Z

← Older revision		Revision as of 13:47, 6 April 2018
Line 233:		Line 233:
	=== Pixbufs ===		=== Pixbufs ===

	The pixbuf ~~libraies~~ are in their own repository		The pixbuf libraries are in their own repository

	from gi.repository import GdkPixbuf		from gi.repository import GdkPixbuf

Pro-panda at 17:15, 6 April 2018

2018-04-06T17:15:42Z

← Older revision		Revision as of 13:15, 6 April 2018
Line 508:		Line 508:
	[[Category:Developer]]		[[Category:Developer]]

	= More porting ~~wiki pages~~ =		= More porting examples =

	{{Special:PrefixIndex/Features/GTK3/Porting}}		{{Special:PrefixIndex/Features/GTK3/Porting}}

Pro-panda: Standardise names, and remove redundancy

2018-04-06T14:01:44Z

Standardise names, and remove redundancy

← Older revision		Revision as of 10:01, 6 April 2018
Line 1:		Line 1:
	=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:
Line 8:		Line 8:
	* [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.
Line 17:		Line 17:

	==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
Line 24:		Line 25:
	* <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
Line 32:		Line 33:
	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:
Line 39:		Line 40:
	</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
Line 57:		Line 58:
	Gtk.main()		Gtk.main()
	</pre>		</pre>

	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~~

	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.
Line 145:		Line 140:
	=== 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)
Line 169:		Line 164:
	<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>
Line 198:		Line 193:
	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:
Line 206:		Line 201:

	=== 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 ===
Line 271:		Line 266:
	===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>
Line 399:		Line 394:
	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===
Line 496:		Line 491:
	=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/

Pro-panda at 05:33, 5 April 2018

2018-04-05T05:33:50Z

← Older revision		Revision as of 01:33, 5 April 2018
Line 12:		Line 12:
	#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.
	#Run this [http://git.gnome.org/browse/pygobject/tree/pygi-convert.sh 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'' :)		#Run this [http://git.gnome.org/browse/pygobject/tree/pygi-convert.sh 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'' :)
	~~#Convert all the <code>from sugar.* import</code> to <code>from sugar</code>'''3'''<code>.* import</code> using [http://dev.laptop.org/~manuq/sugar-convert.sh this script]~~
	#Follow the [[Development Team/Code guidelines\|Code Guidelines]] during all the porting process		#Follow the [[Development Team/Code guidelines\|Code Guidelines]] during all the porting process
	#Make the API changes in sugar-toolkit-gtk3		#Make the API changes in sugar-toolkit-gtk3
	#Write comments on the code, by adding '''# README:''', '''# TODO:''' and '''# FIXME:''' explaining what are the problems that you are having with that chunk of code. Put a link if it's necessary		#Write comments on the code, by adding '''# README:''', '''# TODO:''' and '''# FIXME:''' explaining what are the problems that you are having with that chunk of code. Put a link if it's necessary
	Note: If you are considering to fix some ''pep8'' or ''pylint'' errors/warnings, please create two separate patch files (one for the port and one for the pylint/pep8 changes). If we follow this way it is easier to check the port patches, if not the information about the port itself it's difficult to follow

	==~~Cleanup, adopt to~~ API changes in sugar-toolkit~~-gtk3~~ ==		==API changes in sugar-toolkit ==
	* ~~the~~ keep button has been removed ~~completely~~		* The keep button has been removed
	* ~~the~~ old-style toolbar has been removed		* The old-style toolbar has been removed
	* set_toolbar_box is used instead of set_toolbox (see in [http://git.sugarlabs.org/~walter/abacus/walter-cairo/commit/6871dd340a89ade3b5361457e1bd1d58276a8efc Abacus])		*<code>set_toolbar_box</code> is used instead of <code>set_toolbox</code> (see in [http://git.sugarlabs.org/~walter/abacus/walter-cairo/commit/6871dd340a89ade3b5361457e1bd1d58276a8efc Abacus])
	* ~~remove~~ import of deprecated ActivityToolbox (see [http://git.sugarlabs.org/hello-world/mainline/commit/22060a3063b2d6fd38d6b1cd8d44946170255af3 hello-world])		* Remove import of deprecated ActivityToolbox (see [http://git.sugarlabs.org/hello-world/mainline/commit/22060a3063b2d6fd38d6b1cd8d44946170255af3 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 [http://git.sugarlabs.org/record/mainline/commit/6e8968c71e474e2d8d86886badf5cf7d70217dc5 Record])		* Support for <code>service_name</code> and <code>class</code> tags in activity.info has been removed. Use <code>bundle_id</code> instead of <code>service_name</code> and <code>exec</code> instead of <code>class</code> (see in [http://git.sugarlabs.org/record/mainline/commit/6e8968c71e474e2d8d86886badf5cf7d70217dc5 Record])
	* <code>sugar3.activity.Activity</code> ~~doesn't~~ 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 GTK2 to GTK3==
Line 34:		Line 32:
	from gi.repository import Gtk		from gi.repository import Gtk

	Note that require_version 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.

	~~Here are some more examples of~~ imports that may be used:		Similar imports that may be used are:
	<pre>		<pre>
	from gi.repository import Gdk, Pango, Gobject		from gi.repository import Gdk, Pango, Gobject
Line 65:		Line 63:
	from sugar3.activity import activity		from sugar3.activity import activity

	~~Make sure you change the setup.py in your activity to point to the new toolkit as well:~~		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.]
	~~from sugar3.activity import bundlebuilder~~

	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').

	====Simple example on creating a toolbar====		====Simple example on creating a toolbar====

Pro-panda: Merge useful content from https://wiki.sugarlabs.org/go/Features/GTK3/Porting/GetBooks

2018-04-04T15:42:39Z

Merge useful content from https://wiki.sugarlabs.org/go/Features/GTK3/Porting/GetBooks

Show changes

Pro-panda at 14:43, 4 April 2018

2018-04-04T14:43:23Z

Show changes

Quozl: /* Pango */

2018-04-04T06:19:40Z

Pango

← Older revision		Revision as of 02:19, 4 April 2018
Line 258:		Line 258:
	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 gtk3 library:
	from gi.repository import Pango as pango		from gi.repository import Pango as pango
			=== Gio.Settings from GConf ===
			Any use of GConf should be ported to Gio.Settings.

	=== Other considerations ===		=== Other considerations ===

Kipply: /* Porting an existing activity to GTK3 */Added more extra information

2017-12-31T00:14:51Z

Porting an existing activity to GTK3: Added more extra information

← Older revision		Revision as of 20:14, 30 December 2017
Line 6:		Line 6:
	If you would like to reference other examples of GTK3 port:		If you would like to reference other examples of GTK3 port:
	* [https://github.com/sugarlabs/biorhythm/commit/c16de3b70cce2cc6f8af933e2b062c844a47c144/ Biorhythm]		* [https://github.com/sugarlabs/biorhythm/commit/c16de3b70cce2cc6f8af933e2b062c844a47c144/ Biorhythm]
			* [https://github.com/sugarlabs/peru-learns-english-activity/commit/caa2cde526b3823a5a1f7d200a76ad5bc3502b0e Peru Learns English, includes GStreamer and GST update]

	==Preparation==		==Preparation==
Line 72:		Line 73:
	gi.require_version('Gtk', '3.0')		gi.require_version('Gtk', '3.0')
	from gi.repository import Gtk		from gi.repository import Gtk
			</pre>

			Here are some more examples of imports that may be used:
			<pre>
			from gi.repository import Gdk, Pango, Gobject
	</pre>		</pre>

Line 233:		Line 239:

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

			=== Gtk Menu Popup ===
			The Gtk.Menu.popup function now works slightly differently.
			The user supplied positioning function now takes different parameters. These are menu, x, y, push_in and user_data.


	=== Gdk ===		=== Gdk ===
Line 266:		Line 277:
	Most of the constants have slightly different formats, e.g.,		Most of the constants have slightly different formats, e.g.,

	Gtk.StateFlags.NORMAL		gtk.STATE_NORMAL became Gtk.StateFlags.NORMAL
	Gtk.~~PolicyType~~.~~NEVER~~		gtk.RESPONSE_ACCEPT became Gtk.ResponseType.ACCEPT
	Gtk.Justification.~~LEFT~~		gtk.JUSTIFY_CENTER became Gtk.Justification.CENTER
			gtk.RELIEF_NONE became Gtk.ReliefStyle.NONE


	=== Pixbufs ===		=== Pixbufs ===
Line 361:		Line 374:

	# Handle the expose event		# Handle the expose event
			# "expose" became "draw" for the cairo signal
	def do_expose_event(self, event):		def do_expose_event(self, event):
	# Create the cairo context		# Create the cairo context
Line 457:		Line 471:

	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

	==== Replacing pixmaps with Cairo ====		==== Replacing pixmaps with Cairo ====

Emilyo11: edit grammar

2017-12-23T07:08:40Z

edit grammar

← Older revision		Revision as of 03:08, 23 December 2017
Line 245:		Line 245:
	Following the release of Gtk3, we should not be importing pango like this:		Following the release of Gtk3, we should not be importing pango like this:
	import pango		import pango
	In fact, we ca now import pango as an attribute within the gtk3 library:		In fact, we can now import pango as an attribute within the gtk3 library:
	from gi.repository import Pango as pango		from gi.repository import Pango as pango