Source Files

Inside the src directory are two files: main.py and meson.build. The meson.build file describes the build rules for the program – we will look at these later in Building the Application. The main.py file contains the Python source code for the application.

The Program

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 <david.boddie@puri.sm>

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.

Importing Modules

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 gi 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.

Application Class

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 __init__ method:

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:

  1. It uses the super built-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.
  2. It calls the GLib.set_application_name function to set a user-readable application name that will be localized if translations are available.
  3. It calls the GLib.set_prgname function 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 Application 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 Gtk.ApplicationWindow class, passing the application instance to it so that the application runs until the window is closed – see the application property documentation for more information.

Text is displayed in the window using an instance of the Gtk.Label class which we configure by calling set_markup to set its markup property. 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 add method, and the window is shown using the show_all method so that both the window and its contents are displayed.

Creating and Running an Application Instance

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 sys.exit call.

Summary

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.