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.

Nonmodal Message Dialog

By calling dialog.run(), your dialog is always set as modal, which is not always desirable. To create a nonmodal dialog, you need to connect to Gtk.Dialog’s response signal.

Creating a nonmodal dialog is very similar to the previous example, except you do not want to call dialog.run(). By calling this function, a modal dialog is created by blocking the parent window’s main loop regardless of the dialog flags.

By connecting to Gtk.Dialog’s response signal, you can wait for a response identifier to be emitted. By using this method, the dialog is not automatically unreferenced when a response identifier is emitted. The response callback method receives the dialog, the response identifier that was emitted, and the optional data parameter.

One of the most important decisions you have to make when designing a dialog is whether it is modal or nonmodal. As a rule of thumb, if the action needs to be completed before the user can continue working with the application, then the dialog should be modal. Examples of this would be message dialogs, dialogs that ask the user a question, and dialogs to open a file.

If there is no reason why the user cannot continue working while the dialog is open, you should use a nonmodal dialog. You also need to remember that multiple instances of nonmodal dialogs can be created unless you prevent this programmatically, so dialogs that must have only one instance should be created as modal.

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.

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.

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.

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.

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.

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 .

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.

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 " % 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.

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.

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.

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.

Creating Gtk.Assistant Pages

You can connect to all Gtk.Assistant signals with assistant.connect() or any other signal connection function provided by GLib . Excluding "prepare", the callback methods for Gtk.Assistant signals receive the assistant and the user data parameter. The callback method for the prepare signal also accepts the child widget of the current page.

On every page, a Cancel button is displayed in addition to a few others. On pages other than the first one, a Back button is displayed that is always sensitive. This allows you to visit the previously displayed page and make changes.

On every page except the last, a Forward button is placed, which allows the user to move to the next page. On the last page, an Apply button is displayed that allows the user to apply the changes. However, until the page is set as complete, the assistant sets the Forward or Apply button as insensitive. This allows you to prevent the user from proceeding until some action is taken.

In Listing 6-11, the first and last pages of the assistant were set as complete, because they were merely informative pages. This is the case in most assistants, since they should begin with an introduction page and end with a confirmation or summary page.

The other two pages are where it becomes interesting. On the second page, we want to make sure that the user cannot proceed until text is entered in the Gtk.Entry widget. It would seem that we should just check when text has been inserted and be done with it.

However, what happens if the user deletes all of the text? In this case, the forward button should be disabled yet again. To handle both of these actions, you can use Gtk.Editable’s changed signal. This allows you to check the current state of the text in the entry upon every change, as in Listing 6-11.

On the third page, we want to enable the forward button only when the check button is active. To do this, we used the toggled signal of Gtk.ToggleButton to check the current state of the check button. Based on this state, the forward button’s sensitivity was set.

The fourth page has a type of Gtk.AssistantPageType.PROGRESS, which disables all actions until the page is set as complete. The user is instructed to click a button, which begins the process of filling a Gtk.ProgressBar widget 10 percent every second. When the progress bar is filled, the page is set as complete.

Gtk.ProgressBar

The Gtk.Assistant example introduced another new widget called Gtk.ProgressBar. Progress bars are a simple way to show how much of a process has been completed and is useful for processes that take a long time to handle. Progress bars give the user a visual cue that progress is being made, so they do not think the program has frozen.

You may also want to display text that can complement the progress bar. In the preceding example, progress.set_text() displayed the percent complete statistic, which is superimposed on the progress bar widget.

By setting the pulse step to 0.1, the progress bar fills up in the first ten steps and clears itself in the next ten. This process continues for as long as you continue pulsing the progress bar.

Page Forward Methods

There are times that you may want to skip to specific assistant pages if conditions are correct. For example, let’s assume your application is creating a new project. Depending on the chosen language, you want to jump to either the third or fourth page. In this case, you want to define your own Gtk.AssistantPageFunc method for forward motion.

In the assistant.forward() method, flow is changed based on the Boolean value returned by the fictional function decide_next_page(). In either case, the last page is page 4. If the current page is not within bounds, –1 is returned, so an exception is thrown by GTK+.

While this Gtk.Assistant example is very simple, implementations of this widget can become very complex as they expand in number of pages. This widget could be re-created with a dialog, a Gtk.Notebook with hidden tabs, and a few buttons. (I have had to do that very thing multiple times!), but it makes the process a lot easier.)

Exercise 1: Implementing File Chooser Dialogs

You need to set each of the dialogs to a decent size so that the entire content is visible to the user. If you get stuck during this exercise, you can find a solution in Appendix D.