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.

https://docs.gtk.org/gtk4/assistant.png

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 GtkAssistants 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, Any], int] | None = None, data: Any = None) → 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#

The type of the None singleton.

props.use_header_bar: int#

The type of the None singleton.

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

Signals#

class Assistant.signals
apply() → None#

The type of the None singleton.

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

cancel() → None#

The type of the None singleton.

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 type of the None singleton.

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

prepare(page: Widget) → None#

The type of the None singleton.

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

Parameters:

page – the current page