Differences Between GTK+ 2.x and 3.x

If you are proficient in GTK+ 2.x, you may be surprised by the changes in version 3.x. There are both small and large changes to the GTK+ API and the Python classes that wrap those libraries. While the basics for most widgets are unchanged, there are a lot of small “gotchas” that can cause you grief until you understand why and where the changes have been made.

The reason for most of these changes is due to a change in the GTK+ philosophy. The GTK+ 2.x libraries were designed around consistency between all GTK+ programs, with the use of GTK+ themes as the basis for that consistency. This philosophy completely changed with the GTK+ libraries. While themes are still available, it is now easier to create GTK+ programs that have their own look and feel separate from the current GTK theme. While this gives the developer greater control, it also requires some extra programming steps to achieve the look and feel. It also removes some APIs that make a widget easy to create and control.

Creating menus is much easier using the Gtk.Application and Gtk.ApplicationWindow classes. This required complex programming in the GTK+ 2.x environment and is reduced to creating an XML file to represent the menu you want to create in the 3.x environment.

Installing GTK+ 3.x

Before you can create programs, you must install Python, GTK+, and all the dependent libraries. This section covers installing GTK+ on Linux and other Unix-like operating systems. It does not cover how to install GTK+ on macOS or Windows. You need to research the correct way to install GTK+ and Python in those OS environments.

Most modern Linux distributions include Python and GTK+ as part of their respective repositories. You simply need to select Python 3 (this is sometimes installed by default) and GTK+ 3.x (use the latest version available, as shown in Figure 1-1) from the package install program in your Linux distribution and then install those packages along with all the dependent packages.

To test your installation, run the following command.

/usr/bin/gtk3-demo

If the program exists and the widget documentation window appears, then the GTK+ installation was successful.

Summary

This chapter introduced GTK+ Version 3.x and Python 3 along with some installation prerequisites. It presented some post-installation tests to ensure that GTK+ was successfully installed. And it discussed some differences between GTK+ 2.x and 3.x.

After successfully installing GTK+ 3.x and Python 3, your environment should be ready to build your first Python/GTK+ program.

Chapter 2 further discusses Gtk.Application and the Gtk.ApplicationWindow, the base classes that you should use for all Python 3 GTK+ 3.x programs.

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.

Hello World

Practically every programming language book in the world starts with a Hello World example. While this book is no different, the example it uses is more complicated than most other language examples. This is because we base our example around the Gtk.Application and Gtk.ApplicationWindow classes. This makes the example program somewhat longer, and, at first glance, overblown for such a simple GTK+ window. But it also allows good explanations for how GTK+ works and how the Python bindings wrap the APIs into a very good object-oriented system.

Figure 3-1 contains everything you need for a complete GTK+ 3.x Python program.

If you have previous experience with GTK+, you may notice some GTK+ 2.x common elements are missing. We explicitly make this a Python 3 program at line 1. This is necessary because the GTK+ 3.x modules are only available in Python version 3.x. This declaration allows lines 4–6 to properly establish the GTK+ 3.x environment.

Lines 8–11 support the visible GTK+ window. The only activity we need to support for this application is calling the super class to initialize it. But there seems to be some missing activities! All of those missing elements are either contained in the Gtk.ApplicationWindow superclass or they are supported in the Gtk.Application class. One of the default supporting actions connects the delete-event to a default method to quit the application.

Lines 13–23 support the application logic. One of the four default methods for the Gtk.Application class are defined in our subclass. The do_activate method performs the activation activities needed.

do_activate is called when the application is activated (after startup). In this case, two functions are needed. First, we check to see if this is the initial call to the method, and if it is, we create the Application GTK+ window instance. Second, we activate and show (present) the main application window.

Lines 25–27 are the only Python statements needed to start our application. No other statements are necessary, and in fact, none should be added. All the application work should take place in the Gtk.Application class or the Gtk.ApplicationWindow class or their subclasses. This prevents any unnecessary work taking place for a “single instance” application that has attempted to start up another application instance.

GTK+ Widget Hierarchy

The GTK+ application programming interface is actually a C language API. However, it is organized in such a way that an object-oriented language like Python can wrap the C API so that the entire set of APIs are turned into a set of classes organized in a hierarchy.

The transition from GTK+ 2.x to 3.x made changes that have helped other languages create object-oriented bindings that are easier to maintain and easier to implement. For instance, while Python 2.x supported abstract classes, they were buried in the collection classes and were hard to implement in your own code. Python 3.3 supplies the collections.abc module, which makes it easy for you to subclass classes in the module to create your own abstract classes. Also, the GTK+ 3.x API drastically reduces the number of abstract classes. In the future, all of them will probably be eliminated.

The GTK+ 3.x object hierarchy is documented by the PyGObject API Reference ( http://lazka.github.io / pgi-docs/#Gtk-3.0) document. This is the Python GTK+ 3.x reference document. It covers everything you need to know about the Python object bindings to GTK+, including the object hierarchy, supported classes, interfaces, functions, methods, and properties. While the document is mostly comprehensive, it lacks information concerning some new classes. We hope that this book provides that information, as well excellent examples on how to use all the widgets and classes.

While it is important to have an understanding of the GTK+ hierarchy, it is still possible to create good GUI applications with only a superficial understanding. But the more you understand the hierarchy, the better control you have over your application.

Extending HelloWorld.py

Figure 3-2 is the result of running Listing 3-2. Note that the label is already highlighted.

We now have an application that displays data, and thus is a little more useful. Let’s take a look at the changes we made to the program to achieve this result.

Lines 12–15 are where most of the changes have been made. On line 12, we create Gtk.Label with text “Hello World!” contained within it. On line 13, we make that text selectable. This allows the user to select the text and copy it to the clipboard. On line 14, we add the label to the Gtk.ApplicationWindow default container. All main windows in GTK+ derive from Gtk.Container, so it is possible to add widgets to that container. Line 15 resizes Gtk.ApplicationWindow.

Line 27 shows all the widgets contained by Gtk.ApplicationWindow. We need this method call because the present method does not perform that function. It only shows the main window.

These are the only changes made to Listing 3-1. As you can see, it does not take a lot of effort to add new functionality to a Python GTK+ application.

Signals and Callbacks

GTK+ is a system that relies on signals and callback methods. A signal is a notification to your application that the user has performed some action. You can tell GTK+ to run a method or function when the signal is emitted. These are called callback methods/functions.

After you initialize your user interface, control is given to the gtk_main() function through the Gtk.Application class instance, which sleeps until a signal is emitted. At this point, control is passed to other methods/functions.

As the programmer, you connect signals to their methods/callback functions. The callback method/function is called when the action has occurred and the signal is emitted, or when you have explicitly emitted the signal. You also have the capability of stopping signals from being emitted at all.

There are many types of signals, and just like functions, they are inherited from parent structures. Many signals are generic to all widgets, such as "hide" and "grab-focus" or specific to the widget such as the Gtk.RadioButton signal "group-changed". In any case, widgets derived from a class can use all the signals available to all of its ancestors.

Events

Events are special types of signals that are emitted by the X Window System. They are initially emitted by the X Window System and then sent from the window manager to your application to be interpreted by the signal system provided by GLib. For example, the "destroy" signal is emitted on the widget, but the "delete-event" event is first recognized by the underlying Gdk.Window of the widget, and then emitted as a signal of the widget.

The first instance of an event you encountered was the "delete-event". The "delete-event" signal is emitted when the user tries to close the window. The window can be exited by clicking the Close button on the title bar, using the Close pop-up menu item in the taskbar, or by any other means provided by the window manager.

The first difference in the callback method/function is the boolean return value. If True is returned from an event callback, GTK+ assumes the event has already been handled and it does not continue. By returning False, you are telling GTK+ to continue handling the event. False is the default return value for the function, so you do not need to use the "delete-event" signal in most cases. This is only useful if you want to override the default signal handler.

By returning False from the "delete-event" callback function, widget.destroy() is automatically called on the widget. This signal automatically continues with the action, so there is no need to connect to it unless you want to override the default.

In addition, the callback function includes the Gdk.Event parameter. Gdk.Event is a union of the Gdk.EventType enumeration and all the available event structures. Let’s first look at the Gdk.EventType enumeration.

Further GTK+ Methods

Before continuing on to further examples, I would like to draw your attention to a few functions that will come in handy in later chapters and when you create your own GTK+ applications.

Buttons

Gtk.Button is a special kind of container that can only contain a single child. However, that child can be a container itself, thus allowing a button to contain multiple widgets. The Gtk.Button class is a clickable entity. It can be connected to a defined method of the owning container or window.

Figure 3-3 shows the result of running Listing 3-3. Note how the button is centered by default.

Those of you who are experienced GTK+ 2.x developers may wonder why we did not use a stock button instead. Stock buttons have been deprecated since GTK+ 3.1 and should not be used in new code. This may come as a huge surprise because this causes a lot of work when upgrading a 2.x application to a 3.x application. But all is not as bad as it first seems. By converting to non-stock buttons, your application becomes more portable for all supported platforms.

Let's take a detailed look at the button code. There is some interesting code.

Line 12 sets the border width around the button to be created later. Lines 13–16 create the button and connect it to a method in the Gtk.Application instance. Line 13 creates a button with the mnemonic label "_Close". The underline indicates that the letter C is the mnemonic. When the user presses Alt+C, the "clicked" signal is emitted by the button.

Line 14 connects the "clicked" signal produced by the button to the on_button_clicked method in the Gtk.ApplicationWindow instance. It does this by obtaining the instance from the kwargs argument. The dictionary name application was assigned a value on line 28, and that value was fetched on line 14 to point to the correct Gtk.Application instance method.

You may be wondering why we did not connect the button signal to a method local to the Gtk.ApplicationWindow class. This is because the signal to quit the application rightly belongs to the Gtk.Application class, not the Gtk.ApplicationWindow class. This is one of those “gotchas” that can be very hard to understand and apply properly. You need to think carefully when connecting signals to methods to make sure that the correct class gets the signal. This is a roundabout method to process the "clicked" signal. The normal way is to create your own method, like on_button_clicked, in the Gtk.ApplicationWindow class and connect the signal to that method. We are only showing this example to make the point that you can send signals to either the Gtk.ApplicationWindow instance or the Gtk.Application instance.

Line 14 sets the relief style for the button. You should always use the Gtk.ReliefStyle.NORMAL style unless you have good reasons for doing otherwise.

Line 16 adds the button to the Gtk.ApplicationWindow container. This works just like adding a label, as shown in Listing 3-2.

Lines 19–20 process the "clicked" signal emitted from our button. Our only action is to destroy the Gtk.ApplicationWindow instance.

We should note that when the last Gtk.ApplicationWindow instance is destroyed, the Gtk.Application causes the application to exit.

Test Your Understanding

In this chapter, you learned about the window, button, and label widgets. It is time to put that knowledge into practice. In the following exercise, you employ your knowledge of the structure of GTK+ applications, signals, and the GObject property system.

Summary

In Chapter 4, we cover the Gtk.Container class and the vast array of container types available.

GTK.Container

The Gtk.Container class has been covered briefly in past sections, But we now cover the class in more depth. This is necessary so that you have the necessary base knowledge about containers so we may cover all the derived classes in subsequent sections.

The Gtk.Container class is an abstract class. Therefore you should never attempt to create an instance of this class, only of the derived classes.

The main purpose of a container class is to allow a parent widget to contain one or more child widgets. There are two type of container widgets in GTK+, those used for laying out children and decorators and those that add some sort of functionality beyond positioning children.

Horizontal and Vertical Boxes

Gtk.Box is a container widget that allows multiple children to be packed in a one-dimensional, rectangular area. There are two types of boxes: a vertical box which packs children into a single column, and a horizontal box which packs them into a single row.

Figure 4-1 shows the result of running Listing 4-1.

In analyzing Listing 4-2, Gtk.Box uses the same set of methods. Gtk.Box uses the same set of methods.

The "spacing" keyword parameter places a default number of pixels of spacing between each child and its neighbor. This value can be changed for individual cells as children are added, if the box is not set as equally spaced.

Since you do not need further access to the labels in Listing 4-2 after they are added to the widget, the application does not store individual pointers to each object. They are all cleaned up automatically when the parent is destroyed. Each button is then added to the box using a method called the packing.Gtk.Box widget.

Packing boxes can be slightly unintuitive because of the naming of functions. The best way to think about it is in terms of where the packing begins. If you pack at the start position, children are added with the first child appearing at the top or left. If you pack at the end position, the first child appears at the bottom or right of the box.

Since we packed each of the widgets starting at the end, they are shown in reverse order in Figure 4-2). The packing began at the end of the box and packed each child before the previous one. You are free to intersperse calls to start and end packing functions. GTK+ keeps track of both reference positions. Since we packed each of the widgets starting at the end, they are shown in reverse order. The packing began at the end of the box and packed each child before the previous one. You are free to intersperse calls to start and end packing functions. GTK+ keeps track of both reference positions.

By using this method, you can move a child widget to a new position in the Gtk.Box. The position of the first widget in a Gtk.Box container is indexed from zero. The widget is placed in the last position of the box if you specify a position value of –1 or a value greater than the number of children.

Horizontal and Vertical Panes

Gtk.Paned is a special type of container widget that holds exactly two widgets. A resize bar is placed between them, which allows the user to resize the two widgets by dragging the bar in one direction or the other. When the bar is moved, either by user interaction or programmatic calls, one of the two widgets shrinks while the other expands.

As you can see in Figure 4-3 the Gtk.Paned widget places a vertical bar between its two children. By dragging the bar, one widget shrinks while the other expands. In fact, it is possible to move the bar so that one child is completely hidden from the user’s view. You learn how to prevent this with the pack1() and pack2() methods.

All of the Gtk.Paned functions then work with either type of paned widget.

The second parameter in pack1() and pack2() specifies whether the child widget should expand when the pane is resized. If you set this to False, no matter how much larger you make the available area, the child widget does not expand.

Gtk.Paned provides multiple signals, but one of the most useful is move-handle, which tells you when the resizing bar has been moved. If you want to remember the position of the resize bar, this tells you when you need to retrieve a new value.

Grids

So far, all the layout container widgets I have covered only allow children to be packed in one dimension.

The Gtk.Grid widget, however, allows you to pack children in two-dimensional space.

One advantage of using the Gtk.Grid widget over using multiple Gtk.Box widgets is that children in adjacent rows and columns are automatically aligned with each other, which is not the case with boxes within boxes. However, this is also a disadvantage, because you will not always want everything to be lined up in this way.

Figure 4-4 shows a simple grid that contains three widgets. Notice that the single label spans two columns. This illustrates the fact that grids allow one widget to span multiple columns and/or rows as long as the region is rectangular.

Fixed Containers

The Gtk.Fixed widget is a type of layout container that allows you to place widgets by the pixel. There are many problems that can arise when using this widget, but before we explore the drawbacks, let’s look at a simple example.

The top-left corner of the fixed container is referred to by location (0,0). You should only be able to specify real locations for widgets or locations in positive space. The fixed container resizes itself, so every widget is completely visible.

This brings us to the inherent problems with using the Gtk.Fixed widget. The first problem is that your users are free to use whatever theme they want. This means that the size of text on the user’s machine may differ from the size of text on your machine unless you explicitly set the font. The sizes of widgets vary among different user themes as well. This can cause misalignment and overlap. This is illustrated in Figure 4-5, which shows two screenshots, one with a small font size and one with a larger font size.

You can explicitly set the size and font of text to avoid overlap, but this is not advised in most cases. Accessibility options are provided for users with low vision. If you change their fonts, some users may not be able to read the text on the screen.

Another problem with using Gtk.Fixed arises when your application is translated into other languages. A user interface may look great in English, but the displayed strings in other languages may cause display problems, because the width is not constant. Furthermore, languages that are read right to left, such as Hebrew and Arabic, cannot be properly mirrored with the Gtk.Fixed widget. It is best to use a variable-sized container, such as Gtk.Box or Gtk.Grid in this case.

Finally, it can be quite a pain adding and removing widgets from your graphical interface when using a Gtk.Fixed container. Changing the user interface requires you to reposition all of your widgets. If you have an application with a lot of widgets, this presents a long-term maintenance problem.

On the other hand, you have grids, boxes, and various other automatically formatting containers. If you need to add or remove a widget from the user interface, it is as easy as adding or removing a cell. This makes maintenance much more efficient, which is something you should consider in large applications.

Therefore, unless you know that none of the presented problems will plague your application, you should use variable-sized containers instead of Gtk.Fixed. This container was presented only so you know it is available if a suitable situation arises. Even in suitable situations, flexible containers are almost always a better solution and are the proper way of doing things.

Expanders

The Gtk.Expander container can handle only one child. The child can be shown or hidden by clicking the triangle to the left of the expander’s label. A before-and-after screenshot of this action can be viewed in Figure 4-6.

Activating a Gtk.Expander widget cause it to be expanded or retracted depending on its current state.

If you wish to include an underscore character in the expander label, you should prefix it with a second underscore. If you do not want to take advantage of the mnemonic feature, you can use Gtk.Expander.new() to initialize the Gtk.Expander with a standard string as the label, but providing mnemonics as an option to the user is always a good idea. In normal expander labels, underscore characters are not parsed but are treated as just another character.

The Gtk.Expander widget itself is derived from Gtk.Bin, which means that it can only contain one child. As with other containers that hold one child, you need to use expander.add() to add the child widget.

Notebook

The Gtk.Notebook widget organizes child widgets into a number of pages. The user can switch between these pages by clicking the tabs that appear along one edge of the widget.

You are able to specify the location of the tabs, although they appear along the top by default. You can also hide the tabs altogether. Figure 4-7 shows a Gtk.Notebook widget with two tabs that was created with the code in Listing 4-7.

After you create a Gtk.Notebook, it is not very useful until you add tabs to it. To add a tab to the end or beginning of the list of tabs, you can use notebook.append_page() or notebook.prepend_page(), respectively. Each of these methods accepts a child widget, and a widget to display in the tab, as shown next.

Each notebook page can only display one child widget. However, each of the children can be another container, so each page can display many widgets. In fact, it is possible to use Gtk.Notebook as the child widget of another Gtk.Notebook tab.

All three of the functions used to add tabs to a Gtk.Notebook return the integer location of the tab you added or –1 if the action has failed.

Event Boxes

Various widgets, including Gtk.Label , do not respond to GDK events, because they do not have an associated GDK window. To fix this, GTK+ provides a container widget called Gtk.EventBox. Event boxes catch events for the child widget by providing a GDK window for the object.

When using an event box, you need to decide whether the event box’s Gdk.Window should be positioned above the windows of its child or below them. If the event box window is above, all events inside the event box go to the event box. If the window is below, events in windows of child widgets first go to that widget and then to its parents.

You must call eventbox.set_events() before you call eventbox.realize() on the widget. If a widget has already been realized by GTK+, you have to instead use eventbox.add_events() to add event masks.

Before calling eventbox.realize(), your Gtk.EventBox does not yet have an associated Gdk.Window or any other GDK widget resources. Normally, realization occurs when the parent is realized, but event boxes are an exception. When you call window.show() on a widget, it is automatically realized by GTK+. Event boxes are not realized when you call window.show_all(), because they are set as invisible. Calling eventbox.realize() on the event box is an easy way to work around this problem.

When you realize your event box, you need to make sure that it is already added as a child to a top-level widget, or it will not work. This is because, when you realize a widget, it automatically realizes its ancestors. If it has no ancestors, GTK+ is not happy, and realization fails.

After the event box is realized, it has an associated Gdk.Window. Gdk.Window is a class that refers to a rectangular region on the screen where a widget is drawn. It is not the same thing as a Gtk.Window, which refers to a top-level window with a title bar and so on. A Gtk.Window contains many Gdk.Window objects, one for each child widget. They are used for drawing widgets on the screen.

Test Your Understanding

This chapter has introduced you to a number of container widgets that are included in GTK+. The following two exercises allow you to practice what you have learned about a few of these new widgets.

Summary

In this chapter, you learned about the two types of container widgets: decorators and layout containers. Types of decorators covered were expanders, and event boxes. Types of layout containers covered were boxes, panes, grids, fixed containers, and notebooks.

The event box container is seen in later chapters, because there are other widgets besides Gtk.Label that cannot handle GDK events. This is specified when you learn about these widgets. You will see most of the containers in later chapters as well.

While these containers are necessary for GTK+ application development, merely displaying Gtk.Label and Gtk.Button widgets in containers is not very useful (or interesting) in most applications. This type of application does little to accommodate anything beyond basic user interaction.

Therefore, in the next chapter, you are going to learn about many widgets that allow you to interact with the user. These widgets include types of buttons, toggles, text entries, and spin buttons.

Using Push Buttons

Previously, this section was titled “Using Stock Items.” But GTK+ 3.x stock items have been deprecated, so I will show you how to create look-alike stock items out of standard items.

Figure 5-1 shows how to create a look-alike stock Close button.

The first statement gets the default GTK+ theme. Next we load the PixBuf icon from the theme by name.

Next, we turn the PixBuf icon into an image and then add it to the horizontal box.

Toggle Buttons

The Gtk.ToggleButton widget is a type of Gtk.Button that holds its active or inactive state after it is clicked. It is shown as pressed down when active. Clicking an active toggle button causes it to return to its normal state. There are two widgets derived from Gtk.ToggleButton: Gtk.CheckButton and Gtk.RadioButton .

You can create a new The Gtk.ToggleButton with one of three functions. To create an empty toggle button, use Gtk.ToggleButton. new() . If you want the toggle button to include a label by default, use Gtk.ToggleButton. new_with_label() . Lastly, Gtk.ToggleButton also supports mnemonic labels with Gtk.ToggleButton. new_with_mnemonic() .

Figure 5-2 shows two Gtk.ToggleButton widgets that were created with two mnemonic labels by calling the Gtk.ToggleButton. new_with_mnemonic() initializer. The widgets in the screenshot were created with the code in Listing 5-2.

The only signal added by the Gtk.ToggleButton class is "toggled", which is emitted when the user activates or deactivates the button. This signal was triggered in Listing 5-2 by one toggle button in order to disable the other.

In Listing 5-2 another important piece of information was shown: multiple widgets can use the same callback method. We did not need to create a separate callback method for each toggle button, since each required the same functionality. It is also possible to connect one signal to multiple callback methods, although this is not recommended. Instead, you should just implement the whole functionality in a single callback method.

Check Buttons

In most cases, you will not want to use the Gtk.ToggleButton widget, because it looks exactly like a normal Gtk.Button . Instead, GTK+ provides the Gtk.CheckButton widget, which places a discrete toggle next to the display text. Gtk.CheckButton is derived from the Gtk.ToggleButton class. Two instances of this widget are shown in Figure 5-3.

As with toggle buttons, three functions are provided for Gtk.CheckButton initialization. These include Gtk.CheckButton. new() , Gtk.CheckButton.new_with_label(), and Gtk.CheckButton. new_with_mnemonic() . Gtk.CheckButton also inherits the important “toggled” signal, which is used in Listing 5-3.

#!/usr/bin/python3

import sys

import gi

gi.require_version('Gtk', '3.0')

from gi.repository import Gtk

class AppWindow(Gtk.ApplicationWindow):

    def __init__(self, *args, **kwargs):

        super().__init__(*args, **kwargs)

        self.set_border_width(10)

        check1 = Gtk.CheckButton.new_with_label("I am the main option.")

        check2 = Gtk.CheckButton.new_with_label("I rely on the other guy.")

        check2.set_sensitive(False)

        check1.connect("toggled", self.on_button_checked, check2)

        closebutton = Gtk.Button.new_with_mnemonic("_Close")

        closebutton.connect("clicked", self.on_button_close_clicked)

        vbox = Gtk.Box.new(orientation=Gtk.Orientation.VERTICAL, spacing=0)

        vbox.pack_start(check1, False, True, 0)

        vbox.pack_start(check2, False, True, 0)

        vbox.pack_start(closebutton, False, True, 0)

        self.add(vbox)

    def on_button_checked(self, check1, check2):

        if check1.get_active():

            check2.set_sensitive(True);

        else:

            check2.set_sensitive(False)

    def on_button_close_clicked(self, button):

        self.destroy()

class Application(Gtk.Application):

    def __init__(self, *args, **kwargs):

        super().__init__(*args, application_id="org.example.myapp",

                         **kwargs)

        self.window = None

def do_activate(self):

    if not self.window:

        self.window = AppWindow(application=self, title="Check Buttons")

    self.window.show_all()

    self.window.present()

if __name__ == "__main__":

    app = Application()

    app.run(sys.argv)

Listing 5-3

Gtk.CheckButtons

Excluding the initialization methods, all functionality for check boxes is implemented in the Gtk.ToggleButton class and its ancestors. Gtk.CheckButton is merely a convenience widget, which provides the graphical differences from standard Gtk.Button widgets.

Radio Buttons

The second type of widget derived from Gtk.ToggleButton is the radio button widget. In fact, Gtk.RadioButton is actually derived from Gtk.CheckButton . Radio buttons are toggles that are generally grouped together.

In a group, when one radio button is selected, all others are deselected. The group forbids selecting multiple radio buttons at once. This allows you to provide multiple options to the user where only one should be selected.

Note

GTK+ does not provide a way to deselect a radio button, so one radio button is not desirable. The user is not able to deselect the option! If you only need one button, you should use a Gtk.CheckButton or Gtk.ToggleButton widget.

Radio buttons are drawn as a discrete circular toggle on the side of the label widget, so that they can be differentiated from other types of toggle buttons. It is possible to draw radio buttons with the same toggle as Gtk.CheckButton , but this should not be done because it can confuse and frustrate the user. A group of four radio buttons in a vertical box is shown in Figure 5-4.

For radio buttons to work correctly, they must all be referenced to another radio button in the group. Otherwise, all of the buttons would act as independent toggle buttons. An example of how to use multiple radio buttons is shown in Listing 5-4.

#!/usr/bin/python3

import sys

import gi

gi.require_version('Gtk', '3.0')

from gi.repository import Gtk

class AppWindow(Gtk.ApplicationWindow):

    def __init__(self, *args, **kwargs):

        super().__init__(*args, **kwargs)

        self.set_border_width(10)

        radio1 = Gtk.RadioButton.new_with_label(None, "I want to be clicked!")

        radio2 = Gtk.RadioButton.new_with_label_from_widget(radio1,

                                                    "Click me instead!)

        radio3 = Gtk.RadioButton.new_with_label_from_widget(radio1,

                                                    "No! Click me!”)

        radio4 = Gtk.RadioButton.new_with_label_from_widget(radio3,

                                                    "No! Click me!”)

        vbox = Gtk.Box(orientation=Gtk.Orientation.VERTICAL,

        spacing=0) vbox.pack_start(radio1, False, False, 0)

        vbox.pack_start(radio2, False, False, 0)

        vbox.pack_start(radio3, False, False, 0)

        vbox.pack_start(radio4, False, False, 0)

        self.add(vbox)

        self.show_all()

class Application(Gtk.Application):

    def __init__(self, *args, **kwargs):

        super().__init__(*args, application_id="org.example.myapp",

                         **kwargs)

        self.window = None

    def do_activate(self):

        if not self.window:

            self.window = AppWindow(application=self, title="Radio Buttons")

        self.window.show_all()

        self.window.present()

if __name__ == "__main__":

    app = Application()

    app.run(sys.argv)

Listing 5-4

Gtk.RadioButton

The first radio button in a group can be created with any of the following three functions. However, if you want to use a Gtk.Label widget as the child, it is also possible to use a mnemonic widget, so the toggle can be activated from the keyboard.

radiobutton = Gtk.RadioButton.new(list)

radiobutton = Gtk.RadioButton.new_with_label(list, "My label")

radiobutton = Gtk.RadioButton.new_with_mnemonic(list, "_My label")

However, there is a fourth way to both create multiple radio buttons and a list at the same time. You do this by creating your first radio button without specifying a list. Subsequent radio buttons are created referencing the first radio button created or any other radio button that is a part of the internal group.

radio1 = Gtk.RadioButton.new_with_label(None, "I want to be clicked!")

radio2 = Gtk.RadioButton.new_with_label_from_widget(radio1, "Click me instead!")

radio3 = Gtk.RadioButton.new_with_label_from_widget(radio1, "No! Click me!")

radio4 = Gtk.RadioButton.new_with_label_from_widget(radio3, "No! Click me instead!

None is specified for the radio group in each call. This is because the simplest way to create a group of radio buttons is to associate them to another widget in the group. By using this method, you avoid having to use the GLib with singly linked lists, since the list is created and managed for you automatically.

Referring the initialization function to a radio button that already exists creates each of these. GTK+ adds the new radio button to the group from the specified widget. Because of this, you need only refer to any widget that already exists within the desired radio group.

Lastly, every radio button in the group must be connected to the toggled signal. When a radio button is selected, exactly two radio buttons emit the toggled signal, because one is selected and another is deselected. You will not be able to catch all radio button signals if you do not connect every radio button to toggled.

Text Entries

The Gtk.Entry widget is a single line, free-form text entry widget. It is implemented in a general manner, so that it can be molded to fit many types of solutions. It can be used for text entry, password entry, and even number selections.

Gtk.Entry also implements the Gtk.Editable interface, which provides a large number of functions that are created to handle selections of text. An example Gtk.Entry widget is shown in Figure 5-5. This text entry is used for password entry.

Spin Buttons

The Gtk.SpinButton widget is a number selection widget that is capable of handling integers and floating-point numbers. It is derived from Gtk.Entry , so Gtk.SpinButton inherits all of its functions and signals.

A Spin Button Example

The spin button widget allows the user to select an integer or floating-point number by incrementing or decrementing with the up or down arrows. The user can still type in a value with the keyboard, and it is displayed as the nearest acceptable value if it is out of range. Figure 5-6 shows two spin buttons in action that display an integer and a floating-point number.

Spin buttons show integer or floating-point numbers. In actuality, numbers are stored as double values. The spin button handles rounding the number to the correct number of decimal places. Listing 5-6 is a simple example that creates both integer and floating-point number spin buttons.

#!/usr/bin/python3

import sys

import gi

gi.require_version('Gtk', '3.0')

from gi.repository import Gtk

class AppWindow(Gtk.ApplicationWindow):

    def __init__(self, *args, **kwargs):

        super().__init__(*args, **kwargs)

        self.set_border_width(10)

        integer = Gtk.Adjustment(5.0, 0.0, 10.0, 1.0, 2.0, 2.0)

        float_pt = Gtk.Adjustment(5.0, 0.0, 1.0, 0.1, 0.5, 0.5)

        spin_int = Gtk.SpinButton()

        spin_int.set_adjustment(integer)

        spin_int.set_increments(1.0, 0)

        spin_int.set_digits(0)

        spin_float = Gtk.SpinButton()

        spin_float.set_adjustment(float_pt)

        spin_float.set_increments(0.1, 0)

        spin_float.set_digits(1)

        vbox = Gtk.Box(orientation=Gtk.Orientation.VERTICAL, spacing=0)

        vbox.pack_start(spin_int, False, False, 5)

        vbox.pack_start(spin_float, False, False, 5)

        self.add(vbox)

        self.set_size_request(180, 100)

        self.show_all()

class Application(Gtk.Application):

    def __init__(self, *args, **kwargs):

        super().__init__(*args, application_id="org.example.myapp",

                         **kwargs)

        self.window = None

    def do_activate(self):

        if not self.window:

            self.window = AppWindow(application=self, title="Spin Buttons")

        self.window.show_all()

        self.window.present()

if __name__ == "__main__":

    app = Application()

    app.run(sys.argv)

Listing 5-6

Integer and Floating-Point Number Selection

Before creating the spin buttons, you should create the adjustments. You can also initialize the spin button with a None adjustment, but it is set as insensitive. After your adjustments are initialized, you can create new spin buttons with Gtk.SpinButton. new() . The other two parameters in the initialization function specify the climb rate of the spin button and the number of decimal places to display. The climb rate is how much the value should be incremented or decremented when a (+) or (-) sign is pressed.

Gtk.SpinButton.new(climb_rate, digits)

Alternatively, you can create a new spin button with Gtk.SpinButton. new_with_range() , which automatically creates a new adjustment based on the minimum, maximum, and step values you specify. The initial value is set to the minimum value plus a page increment of ten times the step_increment by default. The precision of the widget is automatically set to the value of step_increment.

Gtk.SpinButton.new_with_range (minimum_value, maximum_value, step_increment)

You can call spinbutton. set_digits() to set a new precision of the spin button and spinbutton.set_value() to set a new value. The value is automatically altered if it is out of bounds of the spin button.

spin_button.set_value(value)

Horizontal and Vertical Scales

Another type of widget called a scale allows you to provide a horizontal or vertical slider that can choose an integer or a floating-point number. Gtk.Scale is both a horizontal scale widget and a vertical scale widget. In GTK+ 2.x the Gtk.Scale was an abstract class. The two subclasses Gtk.HScale and Gtk.VScale were used to create horizontal and vertical scales respectively. In GTK+ 3.x these two classes have been deprecated and the Gtk.Scale has become a real class from which both horizontal and vertical boxes can be created.

The functionality of the Gtk.Scale widget is not much different from Gtk.SpinButton . It is often used when you want to restrict the user from entering values, since the value is chosen by moving the slider. Figure 5-7 shows a screenshot of two horizontal scale widgets.

Gtk.Scale is derived from a widget called Gtk.Range . This widget is an abstract type that provides the ability to handle an adjustment. You should use scale. get_value() to retrieve the current value of the scale. Gtk.Range also provides the “value-changed” signal, which is emitted when the user changes the position of the scale.

Gtk.Adjustment widgets may also be shared with other widgets. A single Gtk.Adjustment may be shared with the Gtk.SpinButton and a Gtk.Scale widgets. See the GTK documentation for more information.

Additional Buttons

While the Gtk.Button widget allows you to create your own custom buttons, GTK+ provides three additional button widgets that are at your disposal: the color selection button, file chooser button, and font selection button.

Each of the sections covering these three widgets also cover other important concepts, such as the Gtk.Color class, file filters, and Pango fonts. These concepts are used in later chapters, so it is a good idea to get a grasp of them now.

Color Button

The Gtk.ColorButton widget provides a simple way for you to allow your users to select a specific color. These colors can be specified as six-digit hexadecimal values or the RGB value. The color button itself displays the selected color in a rectangular block set as the child widget of the button. Figure 5-8 is an example of this.

A Gtk.ColorButton Example

When clicked, the color button opens a dialog that allows the user to enter in the color value or browse for a choice on the color wheel. The color wheel is provided so the user is not required to know the numeric values of the colors. Listing 5-8 shows how to use the Gtk.ColorButton widget in an application.

#!/usr/bin/python3

import sys

import gi

gi.require_version('Gtk', '3.0')

from gi.repository import Gtk

from gi.repository import Gdk

class AppWindow(Gtk.ApplicationWindow):

    def __init__(self, *args, **kwargs):

        super().__init__(*args, **kwargs)

        self.set_border_width(10)

        color = Gdk.RGBA(red=0, green=.33, blue=.66, alpha=1.0)

        color = Gdk.RGBA.to_color(color)

        button = Gtk.ColorButton.new_with_color(color)

        button.set_title("Select a Color!")

        label = Gtk.Label("Look at my color!")

        label.modify_fg(Gtk.StateType.NORMAL, color)

        button.connect("color_set", self.on_color_changed, label)

        hbox = Gtk.Box(orientation=Gtk.Orientation.HORIZONTAL, spacing=0)

        hbox.pack_start(button, False, False, 5)

        hbox.pack_start(label, False, False, 5)

        self.add(hbox)

    def on_color_changed(self, button, label):

        color = button.get_color()

        label.modify_fg(Gtk.StateType.NORMAL, color)

class Application(Gtk.Application):

    def __init__(self, *args, **kwargs):

        super().__init__(*args, application_id="org.example.myapp",

                         **kwargs)

        self.window = None

    def do_activate(self):

        if not self.window:

            self.window = AppWindow(application=self, title="Color Button")

        self.window.show_all()

        self.window.present()

if __name__ == "__main__":

    app = Application()

    app.run(sys.argv)

Listing 5-8

Gtk.ColorButton and Gdk.Color

In most cases, you want to create a Gtk.ColorButton with an initial color value, which is done by specifying a Gdk.Color object to button = Gtk.ColorButton. new_with_color() . The default color, if none is provided, is opaque black with the alpha option disabled.

Storing Colors in Gdk.Color

Gdk.Color is a class that stores red, green, and blue values for a color. These values can be retrieved or set using the method shown next. The fourth available value is the pixel object. It automatically stores the index of the color when it is allocated in a color map, so there is usually no need for you to alter this value.

After creating a new Gdk.Color object, if you already know the red, green, and blue values of the color, you can specify them in the following manner. Red, green, and blue values are stored as unsigned integer values ranging from 0 to 65,535, where 65,535 indicates full-color intensity. For example, the following color refers to white.

mycolorobj = Gdk.Color.new()

mycolorobj.red = 65535

mycolorobj.green = 65535

mycolorobj.blue = 65535

Using the Color Button

After setting your initial color, you can choose the title that is given to the color selection dialog with button. set_title() . By default, the title is “Pick a Color”, so it is not necessary to set this value if you are content with this title.

button.get_color()

label.modify_fg(Gtk.StateType.NORMAL, color)

In Listing 5-8, the foreground color was set in the normal widget state, which is what state all labels are in, by and large, unless they are selectable. There are five options for the Gtk.StateType enumeration that can be used in label. modify_fg() . You can reset the widget’s foreground color to the default value by passing a None color.

File Chooser Buttons

The Gtk.FileChooserButton widget provides an easy method for you to ask users to choose a file or a folder. It implements the functionality of the file selection framework provided by GTK+. Figure 5-9 shows a file chooser button set to select a folder and a button set to select a file.

When the user clicks a Gtk.FileChooserButton , an instance of Gtk.FileChooserDialog is opened that allows the user to browse and select one file or one folder, depending on the type of button you created.

Note

You do not learn how to use the Gtk.FileChooserDialog widget until Chapter 6, but you do not need to directly interface with it at this point, because Gtk.FileChooserButton handles all interactions with the dialog.

A Gtk.FileChooserButton Example

You are able to change basic settings, such as the currently selected file, the current folder, and the title of the file selection window. Listing 5-9 shows you how to use both types of file chooser buttons.

#!/usr/bin/python3

import sys

import gi

gi.require_version('Gtk', '3.0')

from gi.repository import Gtk

from pathlib import Path

class AppWindow(Gtk.ApplicationWindow):

    def __init__(self, *args, **kwargs):

        super().__init__(*args, **kwargs)

        self.set_border_width(10)

        label = Gtk.Label("")

        chooser1 = Gtk.FileChooserButton("Choose a Folder.",

                                         Gtk.FileChooserAction.SELECT_FOLDER)

        chooser2 = Gtk.FileChooserButton("Choose a Folder.",

                                         Gtk.FileChooserAction.OPEN)

        chooser1.connect("selection_changed",

                         self.on_folder_changed, chooser2)

        chooser2.connect("selection_changed",

                         self.on_file_changed, label)

        chooser1.set_current_folder(str(Path.home()))

        chooser2.set_current_folder(str(Path.home()))

        filter1 = Gtk.FileFilter()

        filter2 = Gtk.FileFilter()

        filter1.set_name("Image Files")

        filter2.set_name("All Files")

        filter1.add_pattern("*.png")

        filter1.add_pattern("*.jpg")

        filter1.add_pattern("*.gif")

        filter2.add_pattern("*")

        chooser2.add_filter(filter1)

        chooser2.add_filter(filter2)

        vbox = Gtk.Box(orientation=Gtk.Orientation.VERTICAL, spacing=0)

        vbox.pack_start(chooser1, False, False, 0)

        vbox.pack_start(chooser2, False, False, 0)

        vbox.pack_start(label, False, False, 0)

        self.add(vbox)

        self.set_size_request(240, -1)

    def on_folder_changed(self,

        chooser1, chooser2): folder =

        chooser1.get_filename()

        chooser2.set_current_folder(folder)

    def on_file_changed(self, chooser2, label):

        file = chooser2.get_filename()

        label.set_text(file)

class Application(Gtk.Application):

    def __init__(self, *args, **kwargs):

        super().__init__(*args, application_id="org.example.myapp",

                         **kwargs)

        self.window = None

    def do_activate(self):

        if not self.window:

            self.window = AppWindow(application=self, title="File Chooser Button")

        self.window.show_all()

        self.window.present()

if __name__ == "__main__":

    app = Application()

    app.run(sys.argv)

Listing 5-9

Using the File Chooser Button

File chooser button widgets are created with Gtk.FileChooserButton. new() . This widget is able to serve two purposes: selecting a single file or a single folder. There are four types of file choosers that can be created (the remaining two are covered in Chapter 6), but file chooser buttons support only Gtk.FileChooserAction .OPEN and Gtk.FileChooserAction.SELECT_FOLDER.

Gtk.FileChooser

The Gtk.FileChooserButton widget is an implementation of the functionality provided by the Gtk.FileChooser class. This means that, while the button is not derived from Gtk.FileChooser, it can still utilize all the methods defined by Gtk.FileChooser. Quite a few of the methods in Listing 5-9 utilize functions provided by Gtk.FileChooser.

In Listing 5-9, chooser1. set_current_folder() was used to set the current folder of each file chooser button to the user’s home directory. The contents of this folder is shown when the user initially clicks a file chooser button unless it is changed through some other means. This method returns True if the folder was successfully changed.

chooser1.set_current_folder(filename)

The Path.home() method is a utility module provided by Python that returns the current user’s home directory. As with most features in pathlib, this method is platform independent.

This brings up a useful characteristic of the file chooser interface; it can be used to browse many types of file structures, whether it is on a UNIX or Windows machine. This is especially useful if you want your application to be designed for multiple operating systems.

Since the file chooser button only allows one file to be selected at a time, you can use chooser1.get_filename()to retrieve the currently selected file or folder, depending on the type of file chooser button. If no file is selected, this function returns None.

filename = chooser1.get_filename()

At this point, you have enough information about the Gtk.FileChooser class to implement file chooser buttons. Gtk.FileChooser is covered in more depth in the next chapter when you learn about the Gtk.FileChooserDialog widget.

File Filters

Gtk.FileFilter objects allow you to restrict the files shown in the file chooser. For example, in Listing 5-9, only PNG, JPG, and GIF files could be viewed and chosen by the user when the Image Files filter was selected.

File filters are created with Gtk.FileFilter. new() . Therefore, you need to use filefilter. set_name() to set a displayed name for the filter type. If you provide more than one filter, this name allows the user to switch between them.

filefilter = Gtk.FileFilter.new ();

filefilter.set_name (name)

Lastly, for a filter to be complete you need to add types of files to show. The standard way of doing this is with filefilter. add_pattern() as shown in the following code snippet. This function allows you to specify a format for the filenames that are to be shown. Usually identifying file extensions that should be shown does this. You can use the asterisk character as a wildcard for any type of filtering function.

filefilter.add_pattern (pattern)

Tip

As in Listing 5-9, you may want to provide an All Files filter that shows every file in the directory. To do this, you should create a filter with only one pattern set to the wildcard character. If you do not provide this filter, the user will never be able to view any files that do not match a pattern provided by another filter.

You can also specify filter patterns with filefilter. add_mime_type() by specifying the Multipurpose Internet Mail Extensions (MIME) type. For example, image/* shows all files that are an image MIME type. The problem with this function is that you need to be familiar with MIME types. However, the advantage of using MIME types is that you do not need to specify every file extension for a filter. It allows you to generalize to all files in a specific MIME category.

filefilter.add_mime_type(mime_type)

After you create the filter, it needs to be added to the file chooser, which can be done with filechooser. add_filter() . Once you supply the filters, the first specified filters is used by default in the file chooser. The user is able to switch between types if you have specified multiple filters.

filechooser.add_filter (filter)

Font Buttons

Gtk.FontButton is another type of specialized button that allows the user to select font parameters that correspond to fonts currently residing on the user’s system. Font options are chosen in a font selection dialog that is displayed when the user clicks the button. These options include the font name, style options, and font size. An example Gtk.FontButton widget is displayed in Figure 5-10.

Font button widgets are initialized with Gtk.FontButton. new_with_font() , which allows you to specify the initial font. The font is provided as a string in the following format: Family Style Size. Each of the parameters is optional; the default font for Gtk.FontButton is Sans 12, which provides no style parameters.

“Family” refers to the formal font name, such as Sans, Serif, or Arial. Style options can vary between fonts, but they normally include Italic, Bold, and Bold Italic. If you choose a Regular font style, no font style is specified. The size is the point size of the text, such as 12 or 12.5.

A Gtk.FontButton Example

Listing 5-10 creates a Gtk.FontButton widget that is initialized with a Sans Bold 12 font. When the chosen font in the button is changed, the new font is applied to a Gtk.Label widget packed below the font button.

#!/usr/bin/python3

import sys

import gi

gi.require_version('Gtk', '3.0')

from gi.repository import Gtk

from gi.repository import Pango

class AppWindow(Gtk.ApplicationWindow):

    def __init__(self, *args, **kwargs):

        super().__init__(*args, **kwargs)

        self.set_border_width(10)

        label = Gtk.Label("Look at the font!")

        initial_font = Pango.font_description_from_string("Sans Bold 12")

        label.modify_font(initial_font)

        button = Gtk.FontButton.new_with_font("Sans Bold 12")

        button.set_title("Choose a Font")

        button.connect("font_set", self.on_font_changed, label)

        vbox = Gtk.Box(orientation=Gtk.Orientation.VERTICAL, spacing=0)

        vbox.pack_start(button, False, False, 0)

        vbox.pack_start(label, False, False, 0)

        self.add(vbox)

    def on_font_changed(self, button, label):

        font = button.get_font()

        desc = Pango.font_description_from_string(font)

        buffer = "Font: " + font

        label.set_text(buffer)

        label.modify_font(desc)

class Application(Gtk.Application):

    def __init__(self, *args, **kwargs):

        super().__init__(*args, application_id="org.example.myapp",

                         **kwargs)

        self.window = None

    def do_activate(self):

        if not self.window:

            self.window = AppWindow(application=self, title="Font Button")

        self.window.show_all()

        self.window.present()

if __name__ == "__main__":

    app = Application()

    app.run(sys.argv)

Listing 5-10

Using the Font Button

Using Font Selection Buttons

The code in Listing 5-10 gives the first sampling of the Pango.FontDescription class that you have run across. The Pango.FontDescription class is used to parse font style strings. You can create and use a new font description from a font string, such as Sans Bold 12, by calling Pango. font_description_from_string() as follows.

initial_font = Pango.font_description_from_string("Sans Bold 12")

label.modify_font(initial_font)

After creating a font description, modify_font() can be called to set the font of the widget’s text. This function edits the font description object stored by the widget’s Gtk.StyleContext property.

In Listing 5-10, the label’s text was set to the font stored by the Gtk.FontButton when the “font-set” signal was emitted. You can retrieve the whole font description string stored by the font button with fontbutton. get_font_name() , which was used to retrieve the font string displayed by the label.

fontbutton.get_font_name()

In Listing 5-10, the new font style was applied to the Gtk.Label . However, if you set fontbutton. set_use_font() and fontbutton. set_use_size() to True, the font button uses the font family and size when rendering its text. This allows the user to preview the text in the font button. This is turned off for font buttons by default.

fontbutton.set_use_font(boolean)

fontbutton.set_use_size(boolean)

Test Your Understanding

In this chapter, you learned about a number of basic widgets, such as Gtk.Entry , Gtk.SpinButton , and various types of toggles and buttons. In the following two exercises, you are creating two applications to practice using these widgets.

Summary

In the next chapter, you learn how to create your own custom dialogs using the Gtk.Dialog class and about a number of dialogs that are built into GTK+. By the end of Chapter 6, you have a decent grasp of the most important simple widgets available to you in GTK+. From there, we continue on to more complex topics.

Creating Your Own Dialogs

A dialog is a special type of Gtk.Window that supplements the top-level window. It can give the user a message, retrieve information from the user, or provide some other transient type of action.

Dialog widgets are split in half by an invisible horizontal separator. The top part is where you place the main part of the dialog’s user interface. The bottom half is called the action area, and it holds a collection of buttons. When clicked, each button emits a unique response identifier that tells the programmer which button was clicked.

Gtk.Dialog provides access a vertical box that has the action area defined at bottom of the box. The content area has yet to be defined. To define it you begin packing widgets at start of the vertical box. Therefore you must always use the pack_start() to add widgets to a Gtk.Dialog class. Buttons can easily be added to the action area with the add_button(button_text, response_id) method call.

By packing widgets at the start of the box, the action area and the separator always remains at the bottom of the dialog.

Creating a Message Dialog

One advantage of Gtk.Dialog is that, no matter how complex the content of your dialog is, the same basic concepts can be applied to every dialog. To illustrate this, we begin by creating a very simple dialog that gives the user a message. Figure 6-1 is a screenshot of this dialog.

Listing 6-1 creates a simple dialog that notifies the user when the clicked signal is emitted by the button. This functionality is provided by the Gtk.MessageDialog widget, which is covered in a later section of this chapter.

#!/usr/bin/python3

import sys

import gi

gi.require_version('Gtk', '3.0')

from gi.repository import Gtk

class AppWindow(Gtk.ApplicationWindow):

    def __init__(self, *args, **kwargs):

        super().__init__(*args, **kwargs)

        self.set_border_width(10)

        button = Gtk.Button.new_with_mnemonic("_Click Me")

        button.connect("clicked", self.on_button_clicked, self)

        self.add(button)

        self.set_size_request(150, 50)

    def on_button_clicked(self, button, parent):

        dialog = Gtk.Dialog(title="Information", parent=parent,

                             flags=Gtk.DialogFlags.MODAL)

        dialog.add_button("Ok", Gtk.ResponseType.OK)

        label = Gtk.Label("The button was clicked.")

        image = Gtk.Image.new_from_icon_name("dialog-information",

                                             Gtk.IconSize.DIALOG)

        hbox = Gtk.Box(orientation=Gtk.Orientation.HORIZONTAL, spacing=0)

        hbox.pack_start(image, False, False, 0)

        hbox.pack_start(label, False, False, 0)

        dialog.vbox.pack_start(hbox, False, False, 0)

        dialog.show_all()

        dialog.run()

        dialog.destroy()

class Application(Gtk.Application):

    def __init__(self, *args, **kwargs):

        super().__init__(*args, application_id="org.example.myapp",

                         **kwargs)

        self.window = None

    def do_activate(self):

        if not self.window:

            self.window = AppWindow(application=self, title="Dialogs")

        self.window.show_all()

        self.window.present()

if __name__ == "__main__":

    app = Application()

    app.run(sys.argv)

Listing 6-1

Your First Custom Dialog

Creating the Dialog

The first thing you need to do when the button in the main window is clicked is create the Gtk.Dialog widget with Gtk.Dialog.new_with_buttons(). The first two parameters of this function specify the title of the dialog, a pointer to the parent window, and the modality flag.

dialog = Gtk.Dialog(title="Information", parent=parent, flags=Gtk.DialogFlags.MODA

The dialog is set as the transient window of the parent window, which allows the window manager to center the dialog over the main window and keep it on top if necessary. This can be achieved for arbitrary windows by calling window.set_transient_for(). You can also provide None if you do not want the dialog to have or recognize a parent window.

Next, you can specify one or more dialog flags. Options for this parameter are given by the Gtk.DialogFlags enumeration. There are three available values, which are shown in the following list.

• Gtk.DialogFlags.MODAL: Force the dialog to remain in focus on top of the parent window until closed. The user is prevented from interacting with the parent.

• Gtk.DialogFlags.DESTROY_WITH_PARENT: Destroy the dialog when the parent is destroyed, but do not force the dialog to be in focus. This creates a nonmodal dialog unless you call dialog.run().

• Gtk.DialogFlags.USE_HEADER_BAR: Create a dialog with actions in the header bar instead of the action area.

In Listing 6-1, specifying Gtk.DialogFlags.MODAL created a modal dialog. It is not necessary to specify a title or parent window; the values can be set to None. However, you should always set the title, so it can be drawn in the window manager; otherwise, the user has difficulty choosing the desired window.

In Listing 6-1, an OK button with a response of Gtk.ResponseType.OK was added to the dialog.

In GTK+ 2.x, all dialogs placed a horizontal separator between the main content and the action area of the dialog by default. That separator has been deprecated in GTK+ 3.x.

After the child widgets are created, they need to be added to the dialog. As I previously stated, child widgets are added to the dialog by calling box.pack_start(). The dialog is packed as follows.

image = Gtk.Image.new_from_icon_name("dialog-information", Gtk.IconSize.DIALOG)

hbox = Gtk.Box(orientation=Gtk.Orientation.HORIZONTAL, spacing=0)

hbox.pack_start(image, False, False, 0)

hbox.pack_start(label, False, False, 0)

dialog.vbox.pack_start(hbox, False, False, 0)

At this point, you need to show the dialog and its child widgets, because dialog.run()only calls dialog.show() on the dialog itself. To do this, call dialog.show_all() on the dialog. If you do not show the widgets, only the separator and action area is visible when dialog.run() is called.

Response Identifiers

When a dialog is fully constructed, one method of showing the dialog is by calling dialog.run(). This function returns an integer called a response identifier when complete. It also prevents the user from interacting with anything outside of the dialog until it is destroyed or an action area button is clicked.

dialog.run()

Internally, dialog.run() creates a new main loop for the dialog, which prevents you from interacting with its parent window until a response identifier is emitted or the user closes the dialog. Regardless of what dialog flags you set, the dialog is always modal when you call this method, because it calls dialog.set_modal().

If the dialog is manually destroyed by using a method provided by the window manager, Gtk.ResponseType.NONE is returned; otherwise, dialog.run() returns the response identifier referring to the button that was clicked. A full list of available response identifiers from the Gtk.ResponseType enumeration is shown in Table 6-1. You should always use the identifier’s available values instead of random integer values, since they could change in future versions of GTK+.

Table 6-1

Gtk.ResponseType Enumeration Values

Identifiers	Value	Description
Gtk.ResponseType.NONE	–1	Returned if an action widget has no response ID, or if the dialog is programmatically hidden or destroyed.
Gtk.ResponseType.APPLY	–10	Returned by Apply buttons in GTK+ dialogs.
Gtk.ResponseType.HELP	–11	Returned by Help buttons in GTK+ dialogs.
Gtk.ResponseType.REJECT	–2	Generic response ID, not used by GTK+ dialogs.
Gtk.ResponseType.ACCEPT	–3	Generic response ID, not used by GTK+ dialogs.
Gtk.ResponseType.DELETE_EVENT	–4	Returned if the dialog is deleted.
Gtk.ResponseType.OK	–5	Returned by OK buttons in GTK + dialogs.
Gtk.ResponseType.CANCEL	–6	Returned by Cancel buttons in GTK+ dialogs.
Gtk.ResponseType.CLOSE	–7	Returned by Close buttons in GTK+ dialogs.
Gtk.ResponseType.YES	–8	Returned by Yes buttons in GTK + dialogs.
Gtk.ResponseType.No	–9	Returned by No buttons in GTK+ dialogs.

Of course, when you create your own dialogs and when using many of the built-in dialogs covered in the next few pages, you are free to choose which response identifier to use. However, you should try to resist the urge to apply a Gtk.ResponseType.CANCEL identifier to an OK button, or some other type of absurdity along those lines.

Note

You are free to create your own response identifiers, but you should use positive numbers, since all of the built-in identifiers are negative. This allows you to avoid conflicts when more identifiers are added in future versions of GTK+.

After the dialog returns a response identifier, you need to make sure to call dialog.destroy(), or it will cause a memory leak. GTK+ makes sure all of the dialog’s children are destroyed, but you need to remember to initiate the process.

By calling dialog.destroy(), all of the parent’s children are destroyed and its reference count drops. When an object’s reference count reaches zero, the object is finalized, and its memory freed.

The Gtk.Image Widget

Listing 6-1 introduces another new widget called Gtk.Image. Images can be loaded in a wide variety of ways, but one advantage of Gtk.Image is that it displays the named image “image-missing” if the loading has failed. It is also derived from Gtk.Widget, so it can be added as a child of a container unlike other image objects, such as Gdk.Pixbuf.

In our example, new_from_icon_name() created the Gtk.Image widget from a named theme item.

image = Gtk.Image.new_from_icon_name("dialog-information", Gtk.IconSize.DIALOG)

When loading an image, you also need to specify a size for the image. GTK+ automatically looks for a stock icon for the given size and resizes the image to that size if none is found. Available size parameters are specified by the Gtk.IconTheme enumeration, as seen in the following list.

• Gtk.IconSize.INVALID: Unspecified size

• Gtk.IconSize.MENU: 16×16 pixels

• Gtk.IconSize.SMALL_TOOLBAR: 18×18 pixels

• Gtk.IconSize.LARGE_TOOLBAR: 24×24 pixels

• Gtk.IconSize.BUTTON: 24×24 pixels

• Gtk.IconSize.DND: 32×32 pixels

• Gtk.IconSize.DIALOG: 48×48 pixels

As you can see, theme Gtk.Image objects are usually used for smaller images, such as those that appear in buttons, menus, and dialogs, since theme images are provided in a discrete number of standard sizes. In Listing 6-1, the image was set to Gtk.IconSize.DIALOG or 48×48 pixels.

Multiple initialization functions for Gtk.Image are provided, which are described in the API documentation, but new_from_file() and new_from_pixbuf() are especially important to future examples in this book.

Gtk.Image.new_from_file(filename)

Gtk.Image automatically detects the image type of the file specified to new_from_file(). If the image cannot be loaded, it displays a broken-image icon. Therefore, this function never returns a None object. Gtk.Image also supports animations that occur within the image file.

Calling new_from_pixbuf() creates a new Gtk.Image widget out of a previously initialized Gdk.Pixbuf. Unlike new_from_file(), you can use this function to easily figure out whether the image is successfully loaded since you first have to create a Gdk.Pixbuf.

Gdk.Image.new_from_pixbuf(pixbuf)

You need to note that the Gtk.Image creates its own references to the Gdk.Pixbuf, so you need to release your reference to the object if it should be destroyed with the Gtk.Image.

Another Dialog Example

Now that you have created a simple message dialog from scratch, it is time to produce a more complex dialog. In Listing 6-3, a few pieces of basic information about the user are propagated using Python’s utility functions. A dialog, which is shown in Figure 6-2, allows you to edit each piece of information.

This information is, of course, not actually changed within the user’s system; the new text is simply output to the screen. This example illustrates the fact that, regardless of the complexity of the dialog, the basic principles of how to handle response identifiers are still the only ones that are necessary.

You could easily implement this as a nonmodal dialog as well, although this would not be of much use since the dialog itself is the application’s top-level window.

#!/usr/bin/python3

import sys

import gi

gi.require_version('Gtk', '3.0')

from gi.repository import Gtk

import os

import getpass

import socket

import pwd

class AppWindow(Gtk.ApplicationWindow):

    def __init__(self, *args, **kwargs):

        super().__init__(*args, **kwargs)

        self.set_border_width(10)

        button = Gtk.Button.new_with_mnemonic("_Click Me")

        button.connect("clicked", self.on_button_clicked, self)

        self.add(button)

        self.set_size_request(180, 50)

        self.show_all()

    def on_button_clicked(self, button, parent):

        dialog = Gtk.Dialog(title="Edit User Information",

                            parent=parent, flags=Gtk.DialogFlags.MODAL)

        dialog.add_button("Ok", Gtk.ResponseType.OK)

        dialog.add_button("Cancel", Gtk.ResponseType.CANCEL)

        dialog.set_default_response(Gtk.ResponseType.OK)

        lbl1 = Gtk.Label("User Name:")

        lbl2 = Gtk.Label("Real Name:")

        lbl3 = Gtk.Label("Home Dir:")

        lbl4 = Gtk.Label("Host Name:")

        user = Gtk.Entry()

        real_name = Gtk.Entry()

        home = Gtk.Entry()

        host = Gtk.Entry()

        user.set_text(getpass.getuser())

        real_name.set_text(pwd.getpwuid(os.getuid())[4])

        home.set_text(os.environ['HOME'])

        host.set_text(socket.gethostname())

        grid = Gtk.Grid()

        grid.attach(lbl1, 0, 0, 1, 1)

        grid.attach(lbl2, 0, 1, 1, 1)

        grid.attach(lbl3, 0, 2, 1, 1)

        grid.attach(lbl4, 0, 3, 1, 1)

        grid.attach(user, 1, 0, 1, 1)

        grid.attach(real_name, 1, 1, 1, 1)

        grid.attach(home, 1, 2, 1, 1)

        grid.attach(host, 1, 3, 1, 1)

        dialog.vbox.pack_start(grid, False, False, 5)

        dialog.show_all()

        result = dialog.run()

        if result == Gtk.ResponseType.OK:

            print("User Name: " + user.get_text())

            print("Real Name: " +

            real_name.get_text()) print("Home: " +

            home.get_text()) print("Host: " +

            host.get_text())

        dialog.destroy()

class Application(Gtk.Application):

    def __init__(self, *args, **kwargs):

        super().__init__(*args, application_id="org.example.myapp",

                         **kwargs)

        self.window = None

    def do_activate(self):

        if not self.window:

            self.window = AppWindow(application=self, title="Simple Dialog")

        self.window.show_all()

        self.window.present()

if __name__ == "__main__":

    app = Application()

    app.run(sys.argv)

Listing 6-3

Editing Information in a Dialog

The proper way to handle any modal dialog is to use the response identifiers, deriving the correct response based on the clicked button. Since there was only one response that needed to be deliberately detected, a conditional if statement was used in Listing 6-3.

However, let’s assume that you need to handle multiple response identifiers. In this case, an if statement would be a better solution, since it was created to compare a single variable to multiple selections, as shown in the following code snippet.

result = dialog.run()

if result == Gtk.ResponseType.OK:

    # ... Handle result ...

elif result == Gtk.ResponseType.APPLY:

    # ... Handle result ...

else:

    # ... Handle default result ...

dialog.destroy()

Built-in Dialogs

There are many types of dialogs already built into GTK+. Although not all of the available dialogs are covered in this chapter, you are given a strong understanding of the concepts needed to use any built-in dialog. This section covers Gtk.MessageDialog, GtkAboutDialog, Gtk.FileChooserDialog , Gtk.FontChooserDialog, and Gtk.ColorChooserDialog.

Message Dialogs

Message dialogs give one of four types of informational messages: general information, error messages, warnings, and questions. This type of dialog decides the icon to display, the title of the dialog, and the buttons to add.

There is also a general type provided that makes no assumption as to the content of the message. In most cases, you will not want to use this, since the four provided types would fill most of your needs.

It is very simple to re-create the Gtk.MessageDialog widget. The first two examples implemented a simple message dialog, but Gtk.MessageDialog already provides this functionality, so you should not need to re-create the widget. Using Gtk.MessageDialog saves on typing and avoids the need to re-create this widget many times, since most applications make heavy use of Gtk.MessageDialog. It also provides a uniform look for message dialogs across all GTK+ applications.

Figure 6-3 shows an example of a Gtk.MessageDialog (compare this to Figure 6-1), which gives the user visual notification of a button’s clicked signal.

Since the content of the message is not critical, its type is set to a general message. This message dialog can be produced using the code shown in Listing 6-4.

#!/usr/bin/python3

import sys

import gi

gi.require_version('Gtk', '3.0')

from gi.repository import Gtk

class AppWindow(Gtk.ApplicationWindow):

    def __init__(self, *args, **kwargs):

        super().__init__(*args, **kwargs)

        self.set_border_width(10)

        button = Gtk.Button.new_with_mnemonic("_Click Me")

        button.connect("clicked", self.on_button_clicked, self)

        self.add(button)

        self.set_size_request(150, 50)

    def on_button_clicked(self, button, parent):

        dialog = Gtk.MessageDialog(type=Gtk.MessageType.INFO, parent=parent,

                                    flags=Gtk.DialogFlags.MODAL,

                                    buttons=("Ok", Gtk.ResponseType.OK),

                                    text="The button was clicked.",

                                    title="Information")

        dialog.run()

        dialog.destroy()

class Application(Gtk.Application):

    def __init__(self, *args, **kwargs):

        super().__init__(*args, application_id="org.example.myapp",

                         **kwargs)

        self.window = None

    def do_activate(self):

        if not self.window:

            self.window = AppWindow(application=self, title="Dialogs")

        self.window.show_all()

        self.window.present()

if __name__ == "__main__":

    app = Application()

    app.run(sys.argv)

Listing 6-4

Using a Gtk.MessageDialog

After the button in the main window is clicked, this example creates a new Gtk.MessageDialog.

The parent window can be set to None if necessary, but in most cases, a parent-child relationship should be established. If you do not set a parent widget, the message dialog will not be centered above the parent window.

Message dialogs should be addressed by the user immediately, because they present some type of important message or critical question that needs the user’s attention. By not setting a parent window, the message dialog can be easily ignored, which is not the desired action in most cases.

dialog = Gtk.MessageDialog.(type=Gtk.MessageType.INFO, parent=parent, \

                    flags=Gtk.DialogFlags.MODAL, \

                    buttons=("Ok", Gtk.ResponseType.OK), \

                    text="The button was clicked.", \

                    title="Information")

You specify one or more dialog flags. Options for this parameter are given by the Gtk.DialogFlags enumeration that was used when creating custom dialogs in the previous three examples.

Unlike GTK+ 2.x, the 3.x Gtk.MessageDialog does not use any positional parameters. Instead, it uses keyword parameters exclusively. Also note that Gtk.MessageDialog does not use a new method. This is because Gtk.MessageDialog creates a subclass of Gtk.MessageDialog and the keywords determine what kind subclass is created.

Also note that the light bulb icon image is missing from the message dialog. This is due to philosophy changes in GTK+ 3.x. If you must have icons in your dialogs then you need to use Gtk.Dialog to hand create your dialogs.

Multiple buttons are supported by including a comma-separated list of buttons/response ids using the "buttons" keyword.

You have no control over the visual formatting of the message provided to Gtk.MessageDialog. If you would like to use the Pango Text Markup Language to format the message dialog’s text, you can leave out the "text" keyword from the Gtk.MessageDialog call. Then call set_markup(str) method with a string of Pango markup to set the text of the message.

It is possible to add a secondary text to the message dialog, which causes the first message to be set as bold with format_secondary_text(). The text string provided to this function should be similar to the format supported by the C printf().

This feature is very useful, because it allows you to give a quick summary in the primary text and go into detail with the secondary text.

About Dialogs

The Gtk.AboutDialog widget provides you with a simple way to provide the user with information about an application. This dialog is usually displayed when the item in the Help menu is chosen. However, since menus are not covered until Chapter 10, our example dialog is used as the top-level window.

Various types of information are shown with Gtk.AboutDialog, including the name of the application, copyright, current version, license content, authors, documenters, artists, and translators. Because an application won’t have all of this information, every property is optional. The main window displays only the basic information, which is seen along with the author credits in Figure 6-4.

By clicking the Credits button, the user is presented with any authors, documenters, translators, and artists that are provided. The License button pops up a new dialog that shows the given license content.

Listing 6-5 is a simple example that shows you how to use every available property of the Gtk.AboutDialog widget.

#!/usr/bin/python3

import sys

import gi

gi.require_version('Gtk', '3.0')

from gi.repository import Gtk, GdkPixbuf

class AppWindow(Gtk.ApplicationWindow):

    def __init__(self, *args, **kwargs):

        super().__init__(*args, **kwargs)

        self.set_border_width(10)

        button = Gtk.Button.new_with_mnemonic("_Click Me")

        button.connect("clicked", self.on_button_clicked, self)

        self.add(button)

        self.set_size_request(150, 50)

        self.show_all()

    def on_button_clicked(self, button, parent):

        authors = ["Author #1", "Author #2"]

        documenters = ["Documenter #1", "Documenter

        #2"] dialog = Gtk.AboutDialog(parent=parent)

        logo = GdkPixbuf.Pixbuf.new_from_file("./logo.png")

        if logo != None:

            dialog.set_logo(logo)

        else:

            print("A GdkPixbuf Error has occurred.")

        dialog.set_name("Gtk.AboutDialog")

        dialog.set_version("3.0")

        dialog.set_copyright("(C) 2007 Andrew Krause")

        dialog.set_comments("All about Gtk.AboutDialog")

        dialog.set_license("Free to all!")

        dialog.set_website("http://book.andrewKrause.net")

        dialog.set_website_label("book.andrewkrause.net")

        dialog.set_authors(authors)

        dialog.set_documenters(documenters)

        dialog.set_translator_credits("Translator #1\nTranslator #2")

        dialog.connect("response", self.on_dialog_button_clicked)

        dialog.run()

    def on_dialog_button_clicked(self, dialog, response):

        dialog.destroy()

class Application(Gtk.Application):

    def __init__(self, *args, **kwargs):

        super().__init__(*args, application_id="org.example.myapp",

                         **kwargs)

        self.window = None

    def do_activate(self):

        if not self.window:

            self.window = AppWindow(application=self, title="About Dialog")

        self.window.show_all()

        self.window.present()

if __name__ == "__main__":

    app = Application()

    app.run(sys.argv)

Listing 6-5

Using a Gtk.AboutDialog

Many properties are available for you to set when creating your own Gtk.AboutDialog instance. Table 6-2 summarizes those options that were used in Listing 6-5. If the license is not specified, the License button is not visible. The Credits button is not visible if there are no credits.

Table 6-2

Gtk.AboutDialog Option Values

Property	Description
program_name	The application’s name.
version	The current version of the application the user is running.
copyright	A short copyright string that should not span more than one or two lines.
comments	A short description of the application that should not span more than one or two lines.
license	License information that is displayed in a secondary dialog. Setting this to None hides the License button.
web site	The home page URL of the application.
web site_label	A label that is displayed instead of the URL.
authors	A Python list of authors who have contributed code to the project.
artists	A Python list of artists who have created graphics for the project.
documenters	A Python list of documenters who have written documentation for the project.
translator_credits	A string that specifies the translator(s) of the current language.
logo	Usually loaded from a file, this Gdk.Pixbuf object is the application’s logo.

Unlike author, artist, and documenter credits, the translator credits are only a single string. This is because the translator string should be set to the person that translated the language currently in use. Internationalization and gettext are not topics for this book. For more information, you should visit www.gnu.org/software/gettext .

Gdk.Pixbuf

GdkPixbuf is a class that contains information about an image stored in memory. It allows you to build images manually by placing shapes or pixels or to load a pre-built image from a file. The latter is preferred in most cases, so that is what is covered in this book.

Since GdkPixbuf is derived from GObject, it supports referencing. This means that the same image can be used in multiple locations in a program by increasing the reference count with ref(). Dereferencing GdkPixbuf objects (pixbufs) is performed automatically in almost all cases.

To load a pixbuf from a file, you can use GdkPixbuf.new_from_file(), which was used in Listing 6-5. This function loads the image with an initial size set to the actual size of the image.

logo = GdkPixbuf.Pixbuf.new_from_file("./logo.png")

After you load the image, you can resize it with scale_simple(). This function accepts the new size parameters of the Gdk.Pixbuf and the interpolation mode to use for the scaling.

pixbuf.scale_simple(dest_width, dest_height, interp_type)

The following are the four GdkPixbuf.InterpType modes.

• GdkPixbuf.InterpType.NEAREST: Sampling is performed on the nearest neighboring pixel. This mode is very fast, but it produces the lowest quality of scaling. It should never be used for scaling an image to a smaller size!

• GdkPixbuf.InterpType.TILES: This mode renders every pixel as a shape of color and uses antialiasing for the edges. This is similar to using GdkPixbuf.InterpType.NEAREST for making an image larger or GdkPixbuf.InterpType.BILINEAR for reducing its size.

• GdkPixbuf.InterpType.BILINEAR: This mode is the best mode for resizing images in both directions, because it has a balance between its speed and the quality of the image.

• GdkPixbuf.InterpType.HYPER: While it is very high quality, this method is also very slow. It should only be used when speed is not a concern. Therefore, it should never be used for any application that the user would expect a fast display time. In one function call, GdkPixbuf.new_from_file_at_size() conveniently resizes the image immediately after it loads from the file.

Many other features are provided in the GdkPixbuf class, but only a few of these are covered, as needed. For further information on GdkPixbuf, you should reference the API documentation.

Gtk.FileChooser Dialogs

In the last chapter, you learned about Gtk.FileChooser and the Gtk.FileChooserButton widget. Recall that Gtk.FileChooser is not a widget, but an abstract class. Abstract classes differ from real classes, because they may not implement the methods they declare.

GTK+ provides the following three widgets that subclass the Gtk.FileChooser class.

• Gtk.FileChooserButton : The file chooser button was covered in the previous chapter. It allows the user to choose one file or folder by displaying a Gtk.FileChooser dialog when clicked.

• Gtk.FileChooserDialog : This is the actual widget that allows the user to choose a file folder. It can also facilitate the creation of a folder or saving of a file. When you use Gtk.FileChooserDialog, you are actually using a file chooser widget packed into a Gtk.Dialog .

• Gtk.FileChooserWidget: This is the actual widget that allows the user to choose a file folder. It can also facilitate the creation of a folder or saving of a file. When you use Gtk.FileChooserDialog , you are actually using a file chooser widget packed into a Gtk.Dialog .

You have already learned about Gtk.FileChooserButton and have used a file chooser to open one file and to select a directory. There are three other abilities provided by the file chooser widget. In the next three examples, you learn how to use a file chooser dialog to save a file, create a directory, and choose multiple files.

Saving Files

Figure 6-5 shows a Gtk.FileChooserDialog widget that is saving a file. You will notice that it is similar to the next two figures as well, because all types of file chooser dialogs have a consistent look so that it is minimally confusing to new users and maximally efficient to all. The widget also uses the same code to implement each dialog type to minimize the amount of necessary code.

File chooser dialogs are used in the same way as the previous two dialogs covered in this chapter, except you need to handle the response code returned by Gtk.Dialog.new(). Listing 6-6 allows the user to choose a file name and sets the button’s text to that file name if the correct response identifier is returned.

#!/usr/bin/python3

import sys

import gi

gi.require_version('Gtk', '3.0')

from gi.repository import Gtk

class AppWindow(Gtk.ApplicationWindow):

    def __init__(self, *args, **kwargs):

        super().__init__(*args, **kwargs)

        self.set_border_width(10)

        self.set_size_request(200, 100)

        button = Gtk.Button.new_with_label("Save as ...")

        button.connect("clicked", self.on_button_clicked, self)

        self.add(button)

    def on_button_clicked(self, button, parentwin):

        dialog = Gtk.FileChooserDialog(title="Save file as ...",

                                       parent=parentwin,

                                       action=Gtk.FileChooserAction.SAVE,

                                       buttons=("_Cancel",

                                                Gtk.ResponseType.CANCEL,

                                       "_Save", Gtk.ResponseType.ACCEPT))

        response = dialog.run()

        if response == Gtk.ResponseType.ACCEPT:

            filename = dialog.get_filename()

            button.set_label(filename)

        dialog.destroy()

class Application(Gtk.Application):

    def __init__(self, *args, **kwargs):

        super().__init__(*args, application_id="org.example.myapp",

                         **kwargs)

        self.window = None

    def do_activate(self):

        if not self.window:

            self.window = AppWindow(application=self, title="Save a File")

        self.window.show_all()

        self.window.present()

if __name__ == "__main__":

    app = Application()

    app.run(sys.argv)

Listing 6-6

Using a Gtk.AboutDialog

All file chooser dialogs are created with the Gtk.FileChooserDialog() regardless of what options you choose. As with other dialogs, you begin by setting the title of the dialog and the parent window. The parent window should always be set, because file chooser dialogs should be modal.

dialog = Gtk.FileChooserDialog(title="Save file as ...", \

                           parent=parentwin, \

                           action=Gtk.FileChooserAction.SAVE, \

                           buttons=("_Cancel", Gtk.ResponseType.CANCEL, \

                           "_Save", Gtk.ResponseType.ACCEPT))

Next, as with file chooser buttons, you have to choose the action of file chooser that is created. All four action types provided by the Gtk.FileChooser abstract class are available to Gtk.FileChooserDialog . These are described in the following list.

• Gtk.FileChooserAction .SAVE: The user is prompted to enter a file name and browse throughout the file system for a location. The returned file is the chosen path with the new file name appended to the end. Gtk.FileChooser provides methods that allow you to ask for confirmation if the user enters a file name that already exists.

• Gtk.FileChooserAction .OPEN: The file chooser only allows the user to select one or more files that already exist on the user’s system. The user is able to browse throughout the file system or choose a bookmarked location.

• Gtk.FileChooserAction.SELECT_FOLDER: This is very similar to the save action, because it allows the user to choose a location and specify a new folder name. The user can enter a new folder name that is created when the file chooser returns or click the Create Folder button, shown in Figure 5-6, which creates a new folder in the current directory.

• Gtk.FileChooserAction .CREATE_FOLDER: This is very similar to the save action, because it allows the user to choose a location and specify a new folder name. The user can enter a new folder name that is created when the file chooser returns or click the Create Folder button, shown in Figure 5-6, which creates a new folder in the current directory.

Lastly, you have to provide a name/response ID list of buttons to add to the action area. In Listing 6-6, when the Cancel button is clicked, Gtk.ResponseType.CANCEL is emitted, and when the Save button is clicked, GTK_RESPONSE_ACCEPT is emitted.

Creating a Folder

GTK+ allows you not only to select a folder but also to create a folder. A Gtk.FileChooserDialog widget using this type can be seen in Figure 6-6, which is a screenshot of Listing 6-7.

The dialog in Listing 6-7 handles creating the new folder when accepted by the user, so you do not need to take any further action beyond destroying the dialog.

#!/usr/bin/python3

import sys

import gi

gi.require_version('Gtk', '3.0')

from gi.repository import Gtk

class AppWindow(Gtk.ApplicationWindow):

    def __init__(self, *args, **kwargs):

        super().__init__(*args, **kwargs)

        self.set_border_width(10)

        self.set_size_request(200, 100)

        button = Gtk.Button.new_with_label("Create a Folder ...")

        button.connect("clicked", self.on_button_clicked, self)

        self.add(button)

    def on_button_clicked(self, button, parentwin):

        dialog = Gtk.FileChooserDialog(title="Create a Folder ...",

                                       parent=parentwin,

                                       action=Gtk.FileChooserAction.SAVE,

                                       buttons=("_Cancel",

                                                Gtk.ResponseType.CANCEL,

                                        "_Ok", Gtk.ResponseType.OK))

        response = dialog.run()

        if response == Gtk.ResponseType.OK:

            filename = dialog.get_filename()

            print("Creating directory: %s\n" % filename)

        dialog.destroy()

class Application(Gtk.Application):

    def __init__(self, *args, **kwargs):

        super().__init__(*args, application_id="org.example.myapp",

                         **kwargs)

        self.window = None

    def do_activate(self):

        if not self.window:

            self.window = AppWindow(application=self, title="Create Folder")

        self.window.show_all()

        self.window.present()

if __name__ == "__main__":

    app = Application()

    app.run(sys.argv)

Listing 6-7

Using a Gtk.AboutDialog

The full folder name of the dialog can be retrieved by using the same function that retrieved the file name in the previous example, get_filename() . The standard os.mkdir() method from the os module creates a folder in the specified location on all supported operating systems.

Selecting Multiple Files

Figure 6-7 shows a standard file chooser dialog that allows the user to choose a file. The difference between Gtk.FileChooserDialog and Gtk.FileChooserButton using the Gtk.FileChooserAction .OPEN type is that dialogs are capable of selecting multiple files while buttons are restricted to one file.

Listing 6-8 shows you how to handle multiple file selections. It is very similar to single file selections except for the fact that selections are returned in a Python list.

#!/usr/bin/python3

import sys

import gi

gi.require_version('Gtk', '3.0')

from gi.repository import Gtk

class AppWindow(Gtk.ApplicationWindow):

    def __init__(self, *args, **kwargs):

        super().__init__(*args, **kwargs)

        self.set_border_width(10)

        self.set_size_request(200, 100)

        button = Gtk.Button.new_with_label("Open file(s) ...")

        button.connect("clicked", self.on_button_clicked, self)

        self.add(button)

    def on_button_clicked(self, button, parentwin):

        dialog = Gtk.FileChooserDialog(title="Open file(s) ...",

                                       parent=parentwin,

                                       action=Gtk.FileChooserAction.OPEN,

                                       buttons=("_Cancel",

                                                Gtk.ResponseType.CANCEL,

                                        "_Open", Gtk.ResponseType.ACCEPT))

        dialog.set_select_multiple(True)

        response = dialog.run()

        if response == Gtk.ResponseType.ACCEPT:

            filenames = dialog.get_filenames()

            i = 0

            while i < len(filenames):

                file = filenames[i]

                print(file + " was selected.")

                i += 1

        dialog.destroy()

class Application(Gtk.Application):

    def __init__(self, *args, **kwargs):

        super().__init__(*args, application_id="org.example.myapp",

                         **kwargs)

        self.window = None

    def do_activate(self):

        if not self.window:

            self.window = AppWindow(application=self, title="Open Nultiple Files")

        self.window.show_all()

        self.window.present()

if __name__ == "__main__":

    app = Application()

    app.run(sys.argv)

Listing 6-8

Using A Gtk.FileChooserDialog to Select Multiple Files

The get_filenames() function returns a Python list of the selected file(s).

filenames = dialog.get_filenames()

Color Selection Dialogs

In the previous chapter, you learned about the Gtk.ColorButton widget, which allowed the user to select a color. After clicking that button, the user was presented with a dialog. Although not specified at the time, that dialog was a Gtk.ColorSelectionDialog widget.

Similar to Gtk.FileChooserDialog , the color selection dialog is actually a Gtk.Dialog container with a Gtk.ColorSelection widget packed as its child widget. Gtk.ColorSelection can easily be used on its own. However, since a dialog is a natural way of presenting the widget, GTK+ provides Gtk.ColorSelectionDialog. A color selection dialog is shown in Figure 6-8.

Listing 6-9 contains a top-level window that has two buttons. When the first button is clicked, a modal Gtk.ColorSelectionDialog is created. The other button creates a nonmodal Gtk.ColorSelectionDialog. Each chooses global color and opacity values.

This example also loops through program arguments, setting the initial color value if provided. This allows you to pass an initial color when launching the application.

#!/usr/bin/python3

import sys

import gi

gi.require_version('Gtk', '3.0')

from gi.repository import Gtk, Gdk

global_color = Gdk.RGBA(red=.50, green=.50, blue=.50,

alpha=1.0).to_color() global_alpha = 65535

class AppWindow(Gtk.ApplicationWindow):

    def __init__(self, *args, **kwargs):

        super().__init__(*args, **kwargs)

        self.set_border_width(10)

        self.set_size_request(200, 100)

        modal = Gtk.Button.new_with_label("Modal")

        nonmodal = Gtk.Button.new_with_label("Non-Modal")

        modal.connect("clicked", self.on_run_color_selection_dialog,

                       self, True)

        nonmodal.connect("clicked", self.on_run_color_selection_dialog,

                          self, False)

        hbox = Gtk.Box(orientation=Gtk.Orientation.HORIZONTAL, spacing=0)

        hbox.pack_start(modal, False, False, 5)

        hbox.pack_start(nonmodal, False, False, 5)

        self.add(hbox)

    def on_dialog_response(self, dialog, result):

        if result == Gtk.ResponseType.OK:

            colorsel = dialog.get_color_selection()

            alpha = colorsel.get_current_alpha()

            color = colorsel.get_current_color()

            print(color.to_string())

            global_color = color

            global_alpha = alpha

        dialog.destroy()

    def on_run_color_selection_dialog(self, button, window, domodal):

        if domodal:

            title = ("Choose Color -- Modal")

        else:

            title = ("Choose Color -- Non-Modal")

        dialog = Gtk.ColorSelectionDialog(title=title, parent=window,

                                          modal=domodal)

        colorsel = dialog.get_color_selection()

        colorsel.set_has_opacity_control(True)

        colorsel.set_current_color(global_color)

        dialog.connect("response", self.on_dialog_response)

        dialog.show_all()

class Application(Gtk.Application):

    def __init__(self, *args, **kwargs):

        super().__init__(*args, application_id="org.example.myapp",

                         **kwargs)

        self.window = None

    def do_activate(self):

        if not self.window:

            self.window = AppWindow(application=self,

                                    title="Color Selection Dialog”)

            self.window.show_all()

            self.window.present()

if __name__ == "__main__":

    app = Application()

    app.run(sys.argv)

Listing 6-9

Using a Gtk.ColorSelectionDialog

The only function provided by the Gtk.ColorSelectionDialog class is Gtk.ColorSelectionDialog(). The following code can get the selected color.

alpha = colorsel.get_current_alpha()

color = colorsel.get_current_color()

print(color.to_string())

Gtk.ColorSelectionDialog provides direct access to its four available child widgets. The first, colorsel is the Gtk.ColorSelection widget that facilitates color selection. The other three are an OK button, a Cancel button, and a Help button. By default, the Help button is hidden. You can use show() or the show_all() method to set it visible.

As with Listing 6-2, this example connects to the response signal, which receives all of the response identifiers regardless of whether the dialog is modal or nonmodal. The dialog is set as modal or nonmodal with the "modal" keyword on the insanitation of the Gtk.ColorSelectionDialog class.

Gtk.ColorSelectionDialog(title=title, parent=window, modal=domodal)

Listing 6-9 shows a fourth color property apart from its RGB values, its opacity (alpha value). Ranging between 0 and 65,535, this value regulates how transparent the color is drawn, where 0 is fully transparent and 65,535 is opaque. By default, the opacity control is turned off within color selection widgets. You can call the method set_has_opacity_control() to enable the feature.

colorsel.set_has_opacity_control(boolean)

When opacity is turned on, the hexadecimal color value is sixteen digits long, four digits for each of the values: red, green, blue, and alpha. You must use colorsel.get_current_alpha() to retrieve its value from the color selection widget.

Font Selection Dialogs

The font selection dialog is a dialog that allows the user to select a font and is the dialog shown when a Gtk.FontButton button is clicked. As with Gtk.ColorSelectionDialog, direct access to the action area buttons is provided through the Gtk.FontSelectionDialog structure. An example font selection dialog is shown in Figure 6-9, which should look similar to the one you saw in the last chapter.

Figure 6-9 is the result of running Listing 6-10.

#!/usr/bin/python3

import sys

import gi

gi.require_version('Gtk', '3.0')

from gi.repository import Gtk

class AppWindow(Gtk.ApplicationWindow):

    def __init__(self, *args, **kwargs):

        super().__init__(*args, **kwargs)

        self.set_border_width(10)

        self.set_size_request(200, 100)

        button = Gtk.Button.new_with_label("Run Font Selection Dialog")

        button.connect("clicked", self.on_run_font_selection_dialog)

        self.add(button)

    def on_run_font_selection_dialog(self, button):

        dialog = Gtk.FontSelectionDialog(title="Choose a Font",

                                         buttons=("Apply", Gtk.ResponseType.APPLY),

                                         parent=self)

        dialog.set_preview_text("GTK+ 3 Development With Python")

        dialog.connect("response", self.on_dialog_response)

      dialog.run()

    def on_dialog_response(self, dialog, response):

        if response == Gtk.ResponseType.OK or response == Gtk.ResponseType.APPLY:

            font = dialog.get_font_name()

            message = Gtk.MessageDialog(title="Selected Font",

                                        flags=Gtk.DialogFlags.MODAL,

                                        type=Gtk.MessageType.INFO,

                                        text=font,

                                        buttons=("Ok", Gtk.ResponseType.OK),

                                        parent=dialog);

            message.run()

            message.destroy()

            if response == Gtk.ResponseType.OK:

                dialog.destroy()

        else:

            dialog.destroy()

class Application(Gtk.Application):

    def __init__(self, *args, **kwargs):

        super().__init__(*args, application_id="org.example.myapp",

                         **kwargs)

        self.window = None

    def do_activate(self):

        if not self.window:

            self.window = AppWindow(application=self,

                                    title="Font Selection Dialog”)

        self.window.show_all()

        self.window.present()

if __name__ == "__main__":

    app = Application()

    app.run(sys.argv)

Listing 6-10

Using a Gtk.FontSelectionDialog

The font selection dialog initialization function, Gtk.FontSelectionDialog(), returns a new Gtk.FontSelectionDialog widget with the specified title.

The dialog itself contains three buttons: OK, Apply, and Cancel. They emit the Gtk.ResponseType.OK, Gtk.ResponseType.APPLY, and Gtk.ResponseType.CANCEL signals respectively.

There is no need to create a modal dialog, because the font selection dialog is connected to a response signal.

If the user clicks the OK button, the user is presented with the selected font, and the dialog is destroyed. By clicking Apply, the selected font is presented to the user, but the dialog is not destroyed. This allows you to apply the new font so the user can view the changes without closing the dialog.

The font selection widget contains a Gtk.Entry widget that allows the user to preview the font. By default, the preview text is set to “abcdefghijk ABCDEFGHIJK”. This is somewhat boring, so I decided to reset it to “GTK+ 3 Development With Python”, the title of this book.

The last methods provided by Gtk.FontSelectionDialog() allow you to set and retrieve the current font string. The font string used by dialog.set_font_name() and dialog.get_font_name() is in the same format that we parsed with Pango.FontDescription in the previous chapter.

Dialogs with Multiple Pages

With the release of GTK+ 2.10, a widget called Gtk.Assistant was introduced. Gtk.Assistant makes it easier to create dialogs with multiple stages, because you do not have to programmatically create the whole dialog. This allows you to split otherwise complex dialogs, into steps that guide the user. This functionality is implemented by what are often referred to as wizards in various applications.

Figure 6-10 shows the first page of a simple Gtk.Assistant widget, which was created using the code in Listing 6-11. This example begins by giving the user general information. The next page will not allow the user to proceed until text is entered in a Gtk.Entry widget. The third page will not allow the user to proceed until a Gtk.CheckButton button is activated. The fourth page will not let you do anything until the progress bar is filled, and the last page gives a summary of what has happened. This is the general flow that every Gtk.Assistant widget should follow.

#!/usr/bin/python3

import sys

import gi

gi.require_version('Gtk', '3.0')

from gi.repository import Gtk

import time

class assistant(Gtk.Assistant):

    progress = None

    def __init__(self, *args, **kwargs):

        super().__init__(*args, **kwargs)

        self.set_size_request(450, 300)

        self.set_title("Gtk.Assistant Example")

        self.connect("destroy", Gtk.main_quit, None)

        # create page 0

        page0_widget = Gtk.Label("This in an example of a Gtk.Assistant. By\n"

                                 + "clicking the forward button, you can " +

                                 "continue\nto the next section!")

        self.append_page(page0_widget)

        self.set_page_title(page0_widget, "Introduction")

        self.set_page_type(page0_widget, Gtk.AssistantPageType.INTRO)

        self.set_page_complete(page0_widget, True)

        # create page 1

        page1_widget = Gtk.Box(orientation=Gtk.Orientation.HORIZONTAL, spacing=5)

        label = Gtk.Label("Your Name: ")

        entry = Gtk.Entry()

        page1_widget.pack_start(label, False, False, 5)

        page1_widget.pack_start(entry, False, False, 5)

        self.append_page(page1_widget)

        self.set_page_title(page1_widget, "")

        self.set_page_type(page1_widget, Gtk.AssistantPageType.CONTENT)

        self.set_page_complete(page1_widget, False)

        # create page 2

        page2_widget = Gtk.CheckButton.new_with_label("Click me to Continue!")

        self.append_page(page2_widget)

        self.set_page_title(page2_widget, "Click the Check Button")

        self.set_page_type(page2_widget, Gtk.AssistantPageType.CONTENT)

        self.set_page_complete(page2_widget, False)

        # create page 3

        page3_widget = Gtk.Alignment.new(0.5, 0.5, 0.0, 0.0)

        button = Gtk.Button.new_with_label("Click Me!")

        self.progress = Gtk.ProgressBar()

        hbox = Gtk.Box(orientation=Gtk.Orientation.HORIZONTAL, spacing=5)

        hbox.pack_start(self.progress, True, False, 5)

        hbox.pack_start(button, False, False, 5)

        page3_widget.add(hbox)

        self.append_page(page3_widget)

        self.set_page_title(page3_widget, "Click the Check Button")

        self.set_page_type(page3_widget, Gtk.AssistantPageType.PROGRESS)

        self.set_page_complete(page3_widget, False)

        # create page 4

        page4_widget = Gtk.Label("Text has been entered in the label and the\n" + "combo box is clicked. If you are done, then\n"

                                 + "it is time to leave!")

        self.append_page(page4_widget)

        self.set_page_title(page4_widget, "Confirmation")

        self.set_page_type(page4_widget, Gtk.AssistantPageType.CONFIRM)

        self.set_page_complete(page4_widget, True)

        # set up the callbacks

        entry.connect("changed",self.entry_changed)

        # page2_widget.connect("toggled",self.button_toggle)

        button.connect("clicked", self.button_clicked)

        self.connect("cancel", self.assistant_canceled)

        self.connect("close", self.assistant_close)

    def entry_changed(self, entry):

        text = entry.get_text()

        num = self.get_current_page()

        page = self.get_nth_page(num)

        self.set_page_complete(page, len(text) > 0)

    def button_toggled(self, toggle):

        active = toggle.get_active()

        self.set_page_complete(toggle, active)

    def button_clicked(self, button):

        percent = 0.0

        button.set_sensitive(False)

        page = self.get_nth_page(3)

        while (percent <= 100.0):

            message = str(percent) + " complete"

            print(message)

            self.progress.set_fraction(percent / 100.0)

            self.progress.set_text(message)

            while (Gtk.events_pending()):

                Gtk.main_iteration()

            time.sleep(1)

            percent += 5.0

        self.set_page_complete(page, True)

    def assistant_canceled(self, response):

        self.destroy()

    def assistant_close(self, response):

        print("You would apply your changes

        now!") self.destroy()

class AppWindow(Gtk.ApplicationWindow):

    def __init__(self, *args, **kwargs): super().__init__(*args, **kwargs)

        self.set_border_width(25)

        button = Gtk.Button.new_with_mnemonic("_Open Assistant")

        button.connect("clicked", self.on_start_button_clicked)

        button.set_relief(Gtk.ReliefStyle.NORMAL)

        self.add(button)

        self.set_size_request(200, 100)

    def on_start_button_clicked(self, button):

        assistant()

class Application(Gtk.Application):

    def __init__(self, *args, **kwargs):

        super().__init__(*args, application_id="org.example.myapp", **kwargs)

        self.window = None

def do_activate(self):

    if not self.window:

        self.window = AppWindow(application=self, title="Gtk.Assistant")

    self.window.show_all()

    self.window.present()

if __name__ == "__main__":

    app = Application()

    app.run(sys.argv)

Listing 6-11

The Gtk.Assistant Widget

Test Your Understanding

In the exercise for this chapter, you are creating custom dialogs of your own. Each of the dialogs is an implementation of a type of file chooser dialog. However, you are embedding a Gtk.FileChooserWidget into a Gtk.Dialog to re-create the functionality of the built-in dialogs.

Summary

In this chapter, you learned how to create your own custom dialogs. To do this, you need to first initialize the dialog. Then, action area buttons need to be added as well as the main content to the dialog’s vertical Gtk.Box.

Dialogs can be created as modal or nonmodal. A modal dialog created with dialog.run() blocks the user from interacting with the parent window until it is destroyed by creating a main loop for the dialog. It also centers the dialog above its parent window. Nonmodal dialogs allow the user to interact with any other window in the application and will not force focus on the dialog.

The last section of this chapter showed you a widget called Gtk.Assistant, which was introduced in GTK+ 2.10. It allows you to create dialogs with multiple stages. It is important to note that assistants are not actually a type of Gtk.Dialog widget but are directly derived from the Gtk.Window class. This means that you have to handle these by connecting signals in the main loop instead of calling dialog.run().

You now have a firm understanding of many important aspects of GTK+. The Chapter 9 explains the multiline text entry widget called Gtk.TextView. Other topics include the clipboard and the Gtk.SourceView library.

Arguments and Keyword Arguments

Keyword parameters and arguments are used throughout the GTK+ library to pass class instance property values from class to subclass to subclass, and so on. So let’s examine this phenomenon closely.

Of course, the Gtk.Window class also supplies the get_title() and set_title() methods to perform the same tasks, but the shortcut Python methods also perform the same tasks. The choice as to which methods you use is entirely up to you.

PyGTK rarely uses formal arguments; it uses variable and keyword arguments almost exclusively. This makes it a little easier to cope with instantiating all the GTK+ classes. Just remember that GTK+ ignores any keyword arguments that are not also property names. This is very useful when you want to establish and manage your own properties.

Logging

Logging tracks events that happen when software runs. The software developer adds logging calls to their code to indicate that certain events have occurred. An event is described by a descriptive message that can optionally contain variable data (i.e., data that is potentially different for each occurrence of the event). Events also have an importance that the developer ascribes to the event; the importance can also be called the level or severity.