Gtk.Assistant

Gtk.Assistant — A widget used to guide users through multi-step operations

Object Hierarchy:

    GObject
    ╰── GInitiallyUnowned
        ╰── Gtk.Widget
            ╰── Gtk.Container
                ╰── Gtk.Bin
                    ╰── Gtk.Window
                        ╰── Gtk.Assistant

Functions:

Signals:

  • “apply” (assistant, user_data)
  • “cancel” (assistant, user_data)
  • “close” (assistant, user_data)
  • “escape” (assistant, user_data)
  • “prepare” (assistant, page, user_data)

Description:

A Gtk.Assistant is a widget used to represent a generally complex operation splitted in several steps, guiding the user through its pages and controlling the page flow to collect the necessary data.

The design of Gtk.Assistant is that it controls what buttons to show and to make sensitive, based on what it knows about the page sequence and the [type][Gtk.AssistantPageType] of each page, in addition to state information like the page [completion][gtk-assistant-set-page-complete] and [committed][gtk-assistant-commit] status.

If you have a case that doesn’t quite fit in Gtk.Assistants way of handling buttons, you can use the Gtk.AssistantPageType.CUSTOM page type and handle buttons yourself.

Gtk.Assistant as Gtk.Buildable

The Gtk.Assistant implementation of the Gtk.Buildable interface exposes the action_area as internal children with the name action_area.

To add pages to an assistant in Gtk.Builder, simply add it as a child to the Gtk.Assistant object, and set its child properties as necessary.

Function Details:

new()

new () -> Gtk.Widget

Creates a new Gtk.Assistant.

  • Returns: a newly created Gtk.Assistant

  • Since: 2.10

get_current_page()

get_current_page (self) -> int

Returns the page number of the current page.

  • Returns: The index (starting from 0) of the currentpage in the assistant, or -1 if the assistanthas no pages,or no current page.

  • Since: 2.10

set_current_page()

set_current_page (self, page_num:int)

Switches the page to page_num. Note that this will only be necessary in custom buttons,as the assistant flow can be set withGtk.Assistant:set_forward_page_func().

  • Since: 2.10

get_n_pages()

get_n_pages (self) -> int

Returns the number of pages in the assistant

  • Returns: the number of pages in the assistant

  • Since: 2.10

get_nth_page()

get_nth_page (self, page_num:int) -> Gtk.Widget

Returns the child widget contained in page number page_num.

  • Returns: the child widget, or Noneif page_numis out of bounds.

  • Since: 2.10

prepend_page()

prepend_page (self, page:Gtk.Widget) -> int

Prepends a page to the assistant.

  • Returns: the index (starting at 0) of the inserted page

  • Since: 2.10

append_page()

append_page (self, page:Gtk.Widget) -> int

Appends a page to the assistant.

  • Returns: the index (starting at 0) of the inserted page

  • Since: 2.10

insert_page()

insert_page (self, page:Gtk.Widget, position:int) -> int

Inserts a page in the assistant at a given position.

  • Returns: the index (starting from 0) of the inserted page

  • Since: 2.10

remove_page()

remove_page (self, page_num:int)

Removes the page_num’s page from assistant.

  • Since: 3.2

set_forward_page_func()

set_forward_page_func (self, page_func:Gtk.AssistantPageFunc=None, data=None)

Sets the page forwarding function to be page_func. This function will be used to determine what will bethe next page when the user presses the forward button.Setting page_func to None will make the assistant touse the default forward function, which just goes to thenext visible page.

  • Since: 2.10

set_page_type()

set_page_type (self, page:Gtk.Widget, type:Gtk.AssistantPageType)

Sets the page type for page. The page type determines the page behavior in the assistant.

  • Since: 2.10

get_page_type()

get_page_type (self, page:Gtk.Widget) -> Gtk.AssistantPageType

Gets the page type of page.

  • Returns: the page type of page

  • Since: 2.10

set_page_title()

set_page_title (self, page:Gtk.Widget, title:str)

Sets a title for page. The title is displayed in the header area of the assistantwhen page is the current page.

  • Since: 2.10

get_page_title()

get_page_title (self, page:Gtk.Widget) -> str

Gets the title for page.

  • Returns: the title for page

  • Since: 2.10

set_page_header_image()

set_page_header_image (self, page:Gtk.Widget, pixbuf:GdkPixbuf.Pixbuf=None)

Gtk.Assistant:set_page_header_image has been deprecated since version 3.2 and should not be used in newly-written code. Since GTK+ 3.2, a header is no longer shown; add your header decoration to the page content instead. Sets a header image for page.

  • Since: 2.10

get_page_header_image()

get_page_header_image (self, page:Gtk.Widget) -> GdkPixbuf.Pixbuf

Gtk.Assistant:get_page_header_image has been deprecated since version 3.2 and should not be used in newly-written code. Since GTK+ 3.2, a header is no longer shown; add your header decoration to the page content instead. Gets the header image for page.

  • Returns: the header image for page,or None if there’s no header image for the page.

  • Since: 2.10

set_page_side_image()

set_page_side_image (self, page:Gtk.Widget, pixbuf:GdkPixbuf.Pixbuf=None)

Gtk.Assistant:set_page_side_image has been deprecated since version 3.2 and should not be used in newly-written code. Since GTK+ 3.2, sidebar images are not shown anymore. Sets a side image for page. This image used to be displayed in the side area of the assistantwhen page is the current page.

  • Since: 2.10

get_page_side_image()

get_page_side_image (self, page:Gtk.Widget) -> GdkPixbuf.Pixbuf

Gtk.Assistant:get_page_side_image has been deprecated since version 3.2 and should not be used in newly-written code. Since GTK+ 3.2, sidebar images are not shown anymore. Gets the side image for page.

  • Returns: the side image for page,or None if there’s no side image for the page.

  • Since: 2.10

set_page_complete()

set_page_complete (self, page:Gtk.Widget, complete:bool)

Sets whether page contents are complete. This will make assistant update the buttons stateto be able to continue the task.

  • Since: 2.10

get_page_complete()

get_page_complete (self, page:Gtk.Widget) -> bool

Gets whether page is complete.

  • Returns: True if pageis complete.

  • Since: 2.10

set_page_has_padding()

set_page_has_padding (self, page:Gtk.Widget, has_padding:bool)

Sets whether the assistant is adding padding aroundthe page.

  • Since: 3.18

get_page_has_padding()

get_page_has_padding (self, page:Gtk.Widget) -> bool

Gets whether page has padding.

  • Returns: True if pagehas padding

  • Since: 3.18

add_action_widget()

add_action_widget (self, child:Gtk.Widget)

Adds a widget to the action area of a Gtk.Assistant.

  • Since: 2.10

remove_action_widget()

remove_action_widget (self, child:Gtk.Widget)

Removes a widget from the action area of a Gtk.Assistant.

  • Since: 2.10

update_buttons_state()

update_buttons_state (self)

Forces assistant to recompute the buttons state. GTK+ automatically takes care of this in most situations,e.g. when the user goes to a different page, or when thevisibility or completeness of a page changes. One situation where it can be necessary to call thisfunction is when changing a value on the current pageaffects the future page flow of the assistant.

  • Since: 2.10

commit()

commit (self)

Erases the visited page history so the back button is notshown on the current page, and removes the cancel buttonfrom subsequent pages. Use this when the information provided up to the currentpage is hereafter deemed permanent and cannot be modifiedor undone. For example, showing a progress page to tracka long-running, unreversible operation after the user hasclicked apply on a confirmation page.

  • Since: 2.22

next_page()

next_page (self)

Navigate to the next page. It is a programming error to call this function whenthere is no next page. This function is for use when creating pages of theGTK_ASSISTANT_PAGE_CUSTOM type.

  • Since: 3.0

previous_page()

previous_page (self)

Navigate to the previous visited page. It is a programming error to call this function whenno previous page is available. This function is for use when creating pages of theGTK_ASSISTANT_PAGE_CUSTOM type.

  • Since: 3.0

Example:

import gi
gi.require_version('Gtk', '3.0')
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()

results matching ""

    No results matching ""