The Gtk.Application Class

Gtk.Application is the base class of a GTK application. Its primary purpose is to separate your program from Python __main__ function, which is a Python implementation detail. The philosophy of Gtk.Application is that applications are interested in being told what needs to happen and when it needs to happen in response to actions from the user. The exact mechanism by which Python starts applications is uninteresting.

When your application starts, the startup signal is fired. This gives you a chance to perform initialization tasks that are not directly related to showing a new window. After this, depending on how the application is started, either activate or open signal is called next.

Note that you have to specify the new signal name and the corresponding method name. By convention in GTK+ 3.x, signals that are built into an existing class have a do_ prefix for their corresponding method names. Callbacks should have method names with an on_ prefix. Adding a prefix to the method name prevents inadvertently overriding method names that are not a part of the signal mechanism.

Gtk.Application defaults to applications being single-instance. If the user attempts to start a second instance of a single-instance application, then Gtk.Application signals the first instance, and you receive additional activate or open signals. In this case, the second instance exits immediately without calling startup or shutdown signals.

For this reason, you should do essentially no work at all from Python’s __main__ function. All startup initialization should be done in Gtk.Application do_startup. This avoids wasting work in the second-instance case where the program exits immediately.

The application continues to run as long as it needs to. This is usually as long as there are any open windows. You can also force the application to stay alive by using the hold method.

On shutdown, you receive a shutdown signal where you can do any necessary cleanup tasks (such as saving files to disk).

Gtk.Application does not implement __main__ for you; you must do so yourself. Your __main__ function should be as small as possible and do almost nothing except create your Gtk.Application and run it. The “real work” should always be done in response to the signals fired by Gtk.Application.

Primary vs. Local Instance

The primary instance of an application is the first instance that is run. A remote instance is an instance that has started but is not the primary instance. The term local instance is refers to the current process, which may or may not be the primary instance.

Gtk.Application only emits signals in the primary instance. Calls to the Gtk.Application API can be made in primary or remote instances (and are made from the vantage of being the local instance). When the local instance is the primary instance, method calls on Gtk.Application result in signals being emitted locally. When the local instance is a remote instance, method calls result in messages being sent to the primary instance and the signals are emitted there.

For example, calling the do_activate method on the primary instance emits the activate signal. Calling it on a remote instance results in a message being sent to the primary instance, and it emits the activate signal.

You rarely need to know if the local instance is primary or remote. In almost all cases, you should call the Gtk.Application method that you are interested in and have it forwarded or handled locally, as appropriate.

Actions

An application can register a set of actions that it supports in addition to the default activate and open actions. Actions are added to the application with the GActionMap interface, and invoked or queried with the GActionGroup interface.

As with the activate and open signals, calling activate_action on the primary instance activates the named action in the current process. Calling activate_action on a remote instance sends a message to the primary instance, causing the action to be activated there.

Dealing with the Command Line

Normally, Gtk.Application assumes that arguments passed on the command line are files to be opened. If no arguments are passed, then it assumes that an application is being launched to show its main window or an empty document. When files are given, you receive these files (in the form of GFile) from the open signal; otherwise, you receive an activate signal. It is recommended that new applications make use of this default handling of command-line arguments.

If you want to deal with command-line arguments in more advanced ways, there are several (complementary) mechanisms by which you can do this.

First, the handle-local-options signal is emitted, and the signal handler gets a dictionary with the parsed options. To make use of this, you need to register your options with the add_main_option_entries method. The signal handler can return a non-negative value to end the process with this exit code, or a negative value to continue with the regular handling of command-line options. A popular use of this signal is to implement a --version argument that works without communicating with a remote instance.

If handle-local-options is not flexible enough for your needs, you can override the local_command_line virtual function to entirely take over the handling of command-line arguments in the local instance. If you do so, you are responsible for registering the application and for handling a --help argument (the default local_command_line function does this for you).

It is also possible to invoke actions from handle-local-options or local_command_line in response to command-line arguments. For example, a mail client may choose to map the --compose command-line argument to an invocation of its compose action. This is done by calling activate_action from the local_command_line implementation. If the command line being processed is in the primary instance, then the compose action is invoked locally. If it is a remote instance, the action invocation is forwarded to the primary instance.

Note in particular that it is possible to use action activations instead of activate or open. It is perfectly reasonable that an application could start without an activate signal ever being emitted. activate is only supposed to be the default “started with no options” signal. Actions are meant to be used for anything else.

Some applications may wish to perform even more advanced handling of command lines, including controlling the life cycle of the remote instance and its exit status once it quits, as well as forwarding the entire contents of the command-line arguments, the environment, and forwarding stdin/stdout/ stderr. This can be accomplished using the HANDLES_COMMAND_LINE option and the command-line signal.

Example

This example is a very simple instance of the Gtk.Application class. This example will be enhanced throughout this book as you gain knowledge of GTK+ 3.x.

Line 23 of the example shows how to create an instance of the Gtk.ApplicationWindow class.

The next section outlines the Gtk.ApplicationWindow class.

The Gtk.ApplicationWindow Class

The Gtk.ApplicationWindow class is the main visible window for your application. Under default conditions, this is the one and only main window visible to the user, unless the application has been set to “multi-instance” (the default is “single-instance”).

Gtk.ApplicationWindow is a Gtk.Window subclass that offers extra functionality for better integration with Gtk.Application features. Notably, it can handle both the application menu as well as the menu bar (see Gtk.Application.set_app_menu() and Gtk.Application.set_menubar()).

When the Gtk.ApplicationWindow is used in coordination with the Gtk.Application class, there is a close relationship between the two classes. Both classes create new actions (signals) that may be acted upon by either class. But the Gtk.ApplicationWindow class is responsible for the full functionality of the widgets contained in the window. It should be noted that the Gtk.ApplicationWindow class also creates a connection for the delete-event that activates the do_quit method of the associated Gtk.Application class.

Actions

The Gtk.ApplicationWindow class implements the Gio.ActionGroup and Gio.ActionMap interfaces to let you add window-specific actions exported by the associated Gtk.Application with its application-wide actions. Window-specific actions are prefixed with win. Prefix and application-wide actions are prefixed with the app. prefix. Actions must be addressed with the prefixed name when referring to them from a Gio.MenuModel.

Note that widgets placed inside the Gtk.ApplicationWindow class can also activate these actions if they implement the Gtk.Actionable interface.

Locking

As with Gtk.Application, the GDK lock is acquired when processing actions arrive from other processes, and should therefore be held when activating actions locally (if GDK threads are enabled).

Example

This example is a full-blown program that should be run from the command line. It modifies the command-line window and adds a menu to it for controlling the application. Most of the menu options are non-functional examples but prove useful for explaining how menu actions act and which class performs the actions specified by the menu XML file.

The top three lines specify the environment for the Python program. Line 5 establishes the Python environment as version 3.x. This is required for all Python programs running GTK 3.x. The next lines establish the Python and GTK imports. It specifically imports the GTK 3.x import libraries. Make sure that you import the modules using the gi interface so that you have the latest modules, because there may be more than one set of modules installed on your system.

The next lines describe the menu XML interface. Each menu item is described by one of three XML attributes. The first is the action attribute. It names an action and the name prefix specifies which class receives the action signal. An app prefix means that Gtk.Application processes the action signal. A win prefix means that Gtk.ApplicationWindow processes the signal. The second attribute is target, which specifies the string that displays in the menu item. The third attribute is label, which specifies whether or not the target attribute string should be translated.

Normally, this XML information is stored in its own file and read at runtime, but to simplify the example, we have included it inline.

The next lines describe the Gtk.ApplicationWindow subclass AppWindow, which encapsulates the main window behavior and all the main window widgets. In this example, there are no widgets contained in the main window. It only intercepts action signals from the menu and acts on those signals.

The main thing to note about the menu signal methods is that they have the same name as specified in the menu XML but with an on_ prefix. The next lines turn two of the four window actions into automatic toggles. The next lines catch the other two signals as method calls.

The Gtk.Application subclass Application encapsulates the application behavior. It provides the application startup and command-line processing, and processes two menu XML signals. As with the methods processed by Gtk.ApplicationWindow, the Gtk.Application method names have an on_ prefix.

First, the initialization for the Gtk.Application subclass calls the superclass to initialize it and then sets up a new command-line option.

The next lines perform the activation activities for the class, and create the Gtk.ApplicationWindow subclass.

Next, two signal methods are defined in the menu XML that are destined for the Gtk.Application subclass.

At the bottom is the actual start of the Python program. The only work that should be done here is to create the class or subclass of Gtk.Application.

Summary

This chapter covered the Gtk.Application and the Gtk.ApplicationWindow classes and the integration of the two classes. We covered how these classes can improve your application and make it more object oriented. The classes can also improve the readability and maintenance of your application.

In subsequent chapters, we cover most of the other GTK+ widgets while using the classes covered in this chapter as the basis for integrating the widgets into sample programs.