Assistant

An Assistant widget provides a preset dialog which allows moving through pages in a specific order. It is commonly used to retrieve configuration settings for complex applications.

Constructor

The Assistant can be constructed using the following:

assistant = Gtk.Assistant()

Methods

There are three methods which can be used to add pages to the widget:

assistant.insert_page(widget, page)
assistant.append_page(widget)
assistant.prepend_page(widget)

The .insert() method requires a widget to be specified which is added to the page. This is commonly a Grid or Box container. The page value should be an integer indicating the position at which the page is to be inserted. The .append() and .prepend() methods require just a widget to be specified, and are added in the ordered they are called.

Pages can also be removed by calling:

assistant.remove_page(page)

The page argument should be the number of the page which is to be removed.

When pages have been added to the Assistant, it is necessary to provide the type of page via:

assistant.set_page_type(widget, page_type)

The widget parameter is the same widget which was specified when calling the .insert_page(), .append(), or .prepend() methods. The page_type constant can be one of:

  • Gtk.AssistantPageType.INTRO
  • Gtk.AssistantPageType.CONTENT
  • Gtk.AssistantPageType.PROGRESS
  • Gtk.AssistantPageType.CONFIRM
  • Gtk.AssistantPageType.SUMMARY

A title should also be set on the page to describe help identify the content:

assistant.set_page_title(widget, page_title)

Again, the widget parameter must be the same as the one specified when adding the page. The page_title is simply a textual string.

To retrieve the current page being viewed in the Assistant call:

page = assistant.get_current_page()

Alternatively, to set the page in view use:

assistant.set_current_page(page)

The page parameter should be set to an integer, with 0 indicating the first page within the Assistant.

To return the number of pages in the Assistant run:

n_pages = assistant.get_n_pages()

A page title can be added to the header with the method:

assistant.set_page_title(title)

The area of the Assistant where the buttons are located is known as the action area. Extra buttons can be added and removed from the area area using:

assistant.add_action_widget(child)
assistant.remove_action_widget(child)

Pages can be switched programmatically using the methods:

assistant.next_page()
assistant.previous_page()

Padding can be applied to the Assistant page via the method:

assistant.set_page_has_padding(page, padding)

The page parameter should be set to the widget being displayed on the page. The padding value when set to True inserts a space around the edge to clean up the display.

Signals

The commonly used signals of an Assistant are:

"apply" (assistant)
"closed" (assistant)
"cancel" (assistant)

The "apply" signal emits when the user presses the Apply button on a page. A "closed" signal is emitted when the user explicitly closes the Assistant by pressing a Close button. The "cancel" signal emits when the user presses the Cancel button, or the X on the titlebar of the Assistant window.

Example

Below is an example of an Assistant:

#!/usr/bin/env python3

from gi.repository import Gtk

class Assistant(Gtk.Assistant):
    def __init__(self):
        Gtk.Assistant.__init__(self)
        self.set_title("Assistant")
        self.set_default_size(400, -1)
        self.connect("cancel", self.on_cancel_clicked)
        self.connect("close", self.on_close_clicked)
        self.connect("apply", self.on_apply_clicked)

        box = Gtk.Box(orientation=Gtk.Orientation.VERTICAL)
        self.append_page(box)
        self.set_page_type(box, Gtk.AssistantPageType.INTRO)
        self.set_page_title(box, "Page 1: Introduction")
        label = Gtk.Label(label="An 'Intro' page is the first page of an Assistant. It is used to provide information about what configuration settings need to be configured. The introduction page only has a 'Continue' button.")
        label.set_line_wrap(True)
        box.pack_start(label, True, True, 0)
        self.set_page_complete(box, True)

        box = Gtk.Box(orientation=Gtk.Orientation.VERTICAL)
        self.append_page(box)
        self.set_page_type(box, Gtk.AssistantPageType.CONTENT)
        self.set_page_title(box, "Page 2: Content")
        label = Gtk.Label(label="The 'Content' page provides a place where widgets can be positioned. This allows the user to configure a variety of options as needed. The page contains a 'Continue' button to move onto other pages, and a 'Go Back' button to return to the previous page if necessary.")
        label.set_line_wrap(True)
        box.pack_start(label, True, True, 0)
        self.set_page_complete(box, True)

        self.complete = Gtk.Box(orientation=Gtk.Orientation.VERTICAL)
        self.append_page(self.complete)
        self.set_page_type(self.complete, Gtk.AssistantPageType.PROGRESS)
        self.set_page_title(self.complete, "Page 3: Progress")
        label = Gtk.Label(label="A 'Progress' page is used to prevent changing pages within the Assistant before a long-running process has completed. The 'Continue' button will be marked as insensitive until the process has finished. Once finished, the button will become sensitive.")
        label.set_line_wrap(True)
        self.complete.pack_start(label, True, True, 0)
        checkbutton = Gtk.CheckButton(label="Mark page as complete")
        checkbutton.connect("toggled", self.on_complete_toggled)
        self.complete.pack_start(checkbutton, False, False, 0)

        box = Gtk.Box(orientation=Gtk.Orientation.VERTICAL)
        self.append_page(box)
        self.set_page_type(box, Gtk.AssistantPageType.CONFIRM)
        self.set_page_title(box, "Page 4: Confirm")
        label = Gtk.Label(label="The 'Confirm' page may be set as the final page in the Assistant, however this depends on what the Assistant does. This page provides an 'Apply' button to explicitly set the changes, or a 'Go Back' button to correct any mistakes.")
        label.set_line_wrap(True)
        box.pack_start(label, True, True, 0)
        self.set_page_complete(box, True)

        box = Gtk.Box(orientation=Gtk.Orientation.VERTICAL)
        self.append_page(box)
        self.set_page_type(box, Gtk.AssistantPageType.SUMMARY)
        self.set_page_title(box, "Page 5: Summary")
        label = Gtk.Label(label="A 'Summary' should be set as the final page of the Assistant if used however this depends on the purpose of your Assistant. It provides information on the changes that have been made during the configuration or details of what the user should do next. On this page only a Close button is displayed. Once at the Summary page, the user cannot return to any other page.")
        label.set_line_wrap(True)
        box.pack_start(label, True, True, 0)
        self.set_page_complete(box, True)

    def on_apply_clicked(self, *args):
        print("The 'Apply' button has been clicked")

    def on_close_clicked(self, *args):
        print("The 'Close' button has been clicked")
        Gtk.main_quit()

    def on_cancel_clicked(self, *args):
        print("The Assistant has been cancelled.")
        Gtk.main_quit()

    def on_complete_toggled(self, checkbutton):
        assistant.set_page_complete(self.complete, checkbutton.get_active())

assistant = Assistant()
assistant.show_all()

Gtk.main()

Download: Assistant