Assistant

Deprecated since version 4.10: This widget will be removed in GTK 5

class Assistant(*args, **kwargs)

Superclasses: Window, Widget, InitiallyUnowned, Object

Implemented Interfaces: Accessible, Buildable, ConstraintTarget, Native, Root, ShortcutManager

GtkAssistant is used to represent a complex as a series of steps.

Each step consists of one or more pages. GtkAssistant guides the user through the pages, and controls the page flow to collect the data needed for the operation.

GtkAssistant handles which buttons to show and to make sensitive based on page sequence knowledge and the AssistantPageType of each page in addition to state information like the completed and committed page statuses.

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

GtkAssistant maintains a GtkAssistantPage object for each added child, which holds additional per-child properties. You obtain the GtkAssistantPage for a child with get_page.

GtkAssistant as GtkBuildable

The GtkAssistant implementation of the GtkBuildable interface exposes the action_area as internal children with the name “action_area”.

To add pages to an assistant in GtkBuilder, simply add it as a child to the GtkAssistant object. If you need to set per-object properties, create a GtkAssistantPage object explicitly, and set the child widget as a property on it.

CSS nodes

GtkAssistant has a single CSS node with the name window and style class .assistant.

Constructors

class Assistant

classmethod new() → Widget

Creates a new GtkAssistant.

Deprecated since version 4.10: This widget will be removed in GTK 5

Methods

class Assistant

add_action_widget(child: Widget) → None

Adds a widget to the action area of a GtkAssistant.

Deprecated since version 4.10: This widget will be removed in GTK 5

Parameters:

child – a GtkWidget

append_page(page: Widget) → int

Appends a page to the assistant.

Deprecated since version 4.10: This widget will be removed in GTK 5

Parameters:

page – a GtkWidget

commit() → None

Erases the visited page history.

GTK will then hide the back button on the current page, and removes the cancel button from subsequent pages.

Use this when the information provided up to the current page is hereafter deemed permanent and cannot be modified or undone. For example, showing a progress page to track a long-running, unreversible operation after the user has clicked apply on a confirmation page.

Deprecated since version 4.10: This widget will be removed in GTK 5

get_current_page() → int

Returns the page number of the current page.

Deprecated since version 4.10: This widget will be removed in GTK 5

get_n_pages() → int

Returns the number of pages in the assistant

Deprecated since version 4.10: This widget will be removed in GTK 5

get_nth_page(page_num: int) → Widget | None

Returns the child widget contained in page number page_num.

Deprecated since version 4.10: This widget will be removed in GTK 5

Parameters:

page_num – the index of a page in the assistant, or -1 to get the last page

get_page(child: Widget) → AssistantPage

Returns the GtkAssistantPage object for child.

Deprecated since version 4.10: This widget will be removed in GTK 5

Parameters:

child – a child of assistant

get_page_complete(page: Widget) → bool

Gets whether page is complete.

Deprecated since version 4.10: This widget will be removed in GTK 5

Parameters:

page – a page of assistant

get_page_title(page: Widget) → str

Gets the title for page.

Deprecated since version 4.10: This widget will be removed in GTK 5

Parameters:

page – a page of assistant

get_page_type(page: Widget) → AssistantPageType

Gets the page type of page.

Deprecated since version 4.10: This widget will be removed in GTK 5

Parameters:

page – a page of assistant

get_pages() → ListModel

Gets a list model of the assistant pages.

Deprecated since version 4.10: This widget will be removed in GTK 5

insert_page(page: Widget, position: int) → int

Inserts a page in the assistant at a given position.

Deprecated since version 4.10: This widget will be removed in GTK 5

Parameters:

• page – a GtkWidget

• position – the index (starting at 0) at which to insert the page, or -1 to append the page to the assistant

next_page() → None

Navigate to the next page.

It is a programming error to call this function when there is no next page.

This function is for use when creating pages of the CUSTOM type.

Deprecated since version 4.10: This widget will be removed in GTK 5

prepend_page(page: Widget) → int

Prepends a page to the assistant.

Deprecated since version 4.10: This widget will be removed in GTK 5

Parameters:

page – a GtkWidget

previous_page() → None

Navigate to the previous visited page.

It is a programming error to call this function when no previous page is available.

This function is for use when creating pages of the CUSTOM type.

Deprecated since version 4.10: This widget will be removed in GTK 5

remove_action_widget(child: Widget) → None

Removes a widget from the action area of a GtkAssistant.

Deprecated since version 4.10: This widget will be removed in GTK 5

Parameters:

child – a GtkWidget

remove_page(page_num: int) → None

Removes the page_num’s page from assistant.

Deprecated since version 4.10: This widget will be removed in GTK 5

Parameters:

page_num – the index of a page in the assistant, or -1 to remove the last page

set_current_page(page_num: int) → None

Switches the page to page_num.

Note that this will only be necessary in custom buttons, as the assistant flow can be set with set_forward_page_func().

Deprecated since version 4.10: This widget will be removed in GTK 5

Parameters:

page_num – index of the page to switch to, starting from 0. If negative, the last page will be used. If greater than the number of pages in the assistant, nothing will be done.

set_forward_page_func(page_func: Callable[[...], int] | None = None, *data: Any) → None

Sets the page forwarding function to be page_func.

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

Deprecated since version 4.10: This widget will be removed in GTK 5

Parameters:

• page_func – the GtkAssistantPageFunc, or None to use the default one

• data – user data for page_func

set_page_complete(page: Widget, complete: bool) → None

Sets whether page contents are complete.

This will make assistant update the buttons state to be able to continue the task.

Deprecated since version 4.10: This widget will be removed in GTK 5

Parameters:

• page – a page of assistant

• complete – the completeness status of the page

set_page_title(page: Widget, title: str) → None

Sets a title for page.

The title is displayed in the header area of the assistant when page is the current page.

Deprecated since version 4.10: This widget will be removed in GTK 5

Parameters:

• page – a page of assistant

• title – the new title for page

set_page_type(page: Widget, type: AssistantPageType) → None

Sets the page type for page.

The page type determines the page behavior in the assistant.

Deprecated since version 4.10: This widget will be removed in GTK 5

Parameters:

• page – a page of assistant

• type – the new type for page

update_buttons_state() → None

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 the visibility or completeness of a page changes.

One situation where it can be necessary to call this function is when changing a value on the current page affects the future page flow of the assistant.

Deprecated since version 4.10: This widget will be removed in GTK 5

Properties

class Assistant

props.pages: ListModel

GListModel containing the pages.

props.use_header_bar: int

True if the assistant uses a GtkHeaderBar for action buttons instead of the action-area.

For technical reasons, this property is declared as an integer property, but you should only set it to True or False.

Deprecated since version 4.10: This widget will be removed in GTK 5

Signals

class Assistant.signals

apply() → None

Emitted when the apply button is clicked.

The default behavior of the GtkAssistant is to switch to the page after the current page, unless the current page is the last one.

A handler for the ::apply signal should carry out the actions for which the wizard has collected data. If the action takes a long time to complete, you might consider putting a page of type PROGRESS after the confirmation page and handle this operation within the prepare signal of the progress page.

Deprecated since version 4.10: This widget will be removed in GTK 5

cancel() → None

Emitted when then the cancel button is clicked.

Deprecated since version 4.10: This widget will be removed in GTK 5

close() → None

Emitted either when the close button of a summary page is clicked, or when the apply button in the last page in the flow (of type CONFIRM) is clicked.

Deprecated since version 4.10: This widget will be removed in GTK 5

escape() → None

The action signal for the Escape binding.

Deprecated since version 4.10: This widget will be removed in GTK 5

prepare(page: Widget) → None

Emitted when a new page is set as the assistant’s current page, before making the new page visible.

A handler for this signal can do any preparations which are necessary before showing page.

Deprecated since version 4.10: This widget will be removed in GTK 5

Parameters:

page – the current page