src directory are two files:
meson.build file describes the build rules for the program – we will
look at these later in Building the Application.
main.py file contains the Python source code for the application.
Because the application is very simple, we show the whole main program here to provide an overview before looking at the details:
#!/usr/bin/env python3 # -*- coding: utf-8 -*- # Copyright (C) 2018 Purism SPC # SPDX-License-Identifier: GPL-3.0+ # Author: David Boddie <email@example.com> import sys import gi gi.require_version('Gtk', '3.0') from gi.repository import GLib, Gtk class Application(Gtk.Application): def __init__(self): super().__init__(application_id='com.example.first_application') GLib.set_application_name('Your First Application') GLib.set_prgname('com.example.first_application') def do_activate(self): window = Gtk.ApplicationWindow(application=self) window.set_icon_name('com.example.first_application') label = Gtk.Label() label.set_markup('<span font="40">Hello World!</span>') window.add(label) window.show_all() if __name__ == "__main__": app = Application() result = app.run(sys.argv) sys.exit(result)
After the opening comments, there are three parts to the program: the module imports, the application class, and the module level code at the end. We will examine these parts of this program individually.
The program begins by importing the modules it needs to create a user
interface. These are the
sys module, which is needed to access the
command line arguments passed to the program when it is run, and the
module, which provides a Python interface to the GNOME libraries:
import sys import gi gi.require_version('Gtk', '3.0') from gi.repository import GLib, Gtk
When importing the
Gtk module, it is important to specify the version of
the API that will be used. Version 3.0 is the default in many environments, but
it is good practice to be explicit about the version in use.
The application is represented by the
Application class which is derived
from the standard
Gtk.Application class. This class provides methods to set
up the application and perform tasks when it is run. It is defined in the
normal way, beginning with the
class Application(Gtk.Application): def __init__(self): super().__init__(application_id='com.example.first_application') GLib.set_application_name('Your First Application') GLib.set_prgname('com.example.first_application')
This method performs three tasks that are necessary for the application to run correctly:
- It uses the
superbuilt-function to call the
__init__method of the base class. This associates the application with the application ID given. This ID must have a certain format which is described in the Gio.GApplication documentation.
- It calls the
GLib.set_application_namefunction to set a user-readable application name that will be localized if translations are available.
- It calls the
GLib.set_prgnamefunction to set the program name, using the application ID for this value. This ensures that the application icon will be used to represent the application in the phone environment.
It is not necessary to know what these things do. We just need to ensure that they are done in this method.
When the application is run, the
do_activate method of the
class is called. This is something that we need to implement if we want the
application to do something. In this case, we create a window and give it an
icon. Then we add a label to the window and show it:
def do_activate(self): window = Gtk.ApplicationWindow(application=self) window.set_icon_name('com.example.first_application') label = Gtk.Label() label.set_markup('<span font="40">Hello World!</span>') window.add(label) window.show_all()
Going into detail, we create an instance of the
class, passing the application instance to it so that the application runs
until the window is closed – see the application property documentation for
Text is displayed in the window using an instance of the
which we configure by calling
set_markup to set its
This allows us to use simple HTML-like markup to show text with a specific size.
Because the window is a container, the label is added to it using the
method, and the window is shown using the
show_all method so that both the
window and its contents are displayed.
The last part of the program contains a standard Python idiom for checking that the module is being run as a script:
if __name__ == "__main__": app = Application() result = app.run(sys.argv) sys.exit(result)
Here, we create the
Application instance and call its
run method with
any arguments that were passed to the application from its environment. When it
has finished running, its exit code is returned via the normal
This part of the tutorial showed the simple Python program that forms the core of the application. It can be run as a standalone application.
However, if we want to install it, we need to build it in a particular way, and we need to provide files that will allow the user to launch it from a GUI. The next part of this tutorial describes how we provide the data files to do that.