GTK GUI with PyGObject (1)

Date: 2021/07/12 (initial publish), 2023/05/21 (last update)

Source: en/

Previous Post Top Next Post


Now that GTK4 is used in Debian/Bookworm in 2023, this section is getting outdated. The followings may be interesting to read:

My objective here is to learn efficient GUI programming with Glade and Python using Gtk.Builder class instead of calling widget classes directly and using decorators offered by Gtk.Templates.

I only touch on essential concepts in the order of practical importance and skip trivial points and points already addressed in The Python GTK+ 3 Tutorial.

GTK GUI situation

GTK3 GUI has been changing. (version 3.38.5, 2021-07, Debian Bullseye)

The Python GTK+ 3 Tutorial (as of 2021-07) goes as:

Gtk.UIManager, Gtk.Action, and Gtk.ActionGroup have been deprecated since GTK+ version 3.10 and should not be used in newly-written code. Use the Application framework instead.

I understand this is caused by App Menu Retirement. I see no Python based tutorial contents for creating modern Primary menu on the headbar using the client side decoration (CSD).

How do I do it? Unfortunately, many code examples in the upstream source tree and the tutorial tend to contain old deprecated practices. This is why I recorded my learning experiences here. (Actual my experiences were much more twisted and tangled. I have touched up my learning history to make it easy for me to recall how to do this again.)

Gtk 3 documentation for Python user

As usual with F/LOSS documents, there are too many similar documents including old ones out there.

These are the key documents:

Please note the GTK3’s C API name is spelled without.” after “Gtk”, while the corresponding Python API name is spelled with.” after “Gtk”.

Once you understand this, C API document becomes useful for Python programmer.

(If you see Python GTK document with their first part of GTK class name spelled in all lower case such as “gtk.Window” instead, you are reading old API based documents such as PyGTK 2.0 Reference Manual. Though they look similar, it is based on pre-GObject Introspection API and they are old. Keep away from them :-))

GUI programming workflow

Let’s recap my planned GUI programming workflow here.

Know some limitations for Glade:


Let me go step-by-step to use Glade to create GTK GUI in my way.

In order to understand what each Glade widget does, the TOC page “Part II. GTK+ Widgets and Objects” gives me the best one-line summary.

Please note Glade uses C API names.

For details on Python API, linked pages from the corresponding listed classes in the Gtk 3.0’s Classes page were valuable and gave me the most current insights.

Where to start GUI design

Looking at the way Glade is designed, it looked like I should start creating window design by clicking and moving item from selection in the top 4 big buttons to the center canvas.

Out of these 4 big buttons, the “Toplevels” button seems to be a good to start. Let’s check what are these GUI objects in “Toplevels”.

Since I want a simple GUI, GtkWindow seems to be a good starting point for the GUI programming learning experience for me now, though Gtk.ApplicationWindow seems to be a good starting point for serious applications in future

Glade generates GtkBuilder UI descriptions in a XML file and Gtk.Buildable consumes this XML file to create complicated widgets. Please pay attention to some of these linked pages talking how widgets are implemented in the Gtk.Buildable.

How to create the top bar embedded primary menu is tricky with GtkWindow. It looks like GtkHeaderBar under the “Containers” button is the one to be used. We will get back to this header bar topic later.

Please note GtkMenuBar is not the one to be used for creating the menu (marked as deprecated for Glade 3.38.2).

How to write a clean python code

Being a lazy person, I want to write a clean and easy python code using decorator technique as described in The Python GTK+ 3 Tutorial: 22.5. Gtk.Template. This is extremely terse. The upstream document is found at PyGObject: Docs » User Guide » Gtk.Template gives a bit more details. PyGObject API Reference under Gtk 3.0 » Classes has no mention of this Gtk.Template.

It’s best to check how this Gtk.Template is implemented to be confident. This is found in the python3-gi package as /usr/lib/python3/dist-packages/gi/ imported from /usr/lib/python3/dist-packages/gi/overrides/ Reading these gives us what exactly does this decorator does.

In order to use this decorator technique, the top level widget needs to be declared as <template> instead of <object> in XML. For Glade, this requires us to click the “Composite” checkbox next to ID entry box on the right side panel to change “ID” to “Class Name” while focusing at the top level widget GtkWindow on the left side panel for my simple example case here.

Let’s put “simple1” to “ID”/“Class Name” entry and see the difference in XML.

$  diff -u0 simple1.ui-ID simple1.ui
--- simple1.ui-ID	2021-07-18 07:29:13.744765698 +0900
+++ simple1.ui	2021-07-18 07:30:00.030723401 +0900
@@ -5 +5 @@
-  <object class="GtkWindow" id="simple1">
+  <template class="simple1" parent="GtkWindow">
@@ -52 +52 @@
-  </object>
+  </template>

Previous Post Top Next Post