Gtk.Assistant¶

class — extends Window, Accessible, Buildable, ConstraintTarget, Native, Root, ShortcutManager

:::warning Deprecated since 4.10 This API is deprecated. :::

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 GtkAssistants way of handling buttons, you can use the AssistantPageType.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 Assistant.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¶

new¶

@classmethod
def new(cls) -> Widget

:::warning Deprecated since 4.10 This API is deprecated. :::

Creates a new GtkAssistant.

Methods¶

add_action_widget¶

def add_action_widget(self, child: Widget) -> None

:::warning Deprecated since 4.10 This API is deprecated. :::

Adds a widget to the action area of a GtkAssistant.

Parameters:

child — a GtkWidget

append_page¶

def append_page(self, page: Widget) -> int

:::warning Deprecated since 4.10 This API is deprecated. :::

Appends a page to the assistant.

Parameters:

page — a GtkWidget

commit¶

def commit(self) -> None

:::warning Deprecated since 4.10 This API is deprecated. :::

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.

get_current_page¶

def get_current_page(self) -> int

:::warning Deprecated since 4.10 This API is deprecated. :::

Returns the page number of the current page.

get_n_pages¶

def get_n_pages(self) -> int

:::warning Deprecated since 4.10 This API is deprecated. :::

Returns the number of pages in the assistant

get_nth_page¶

def get_nth_page(self, page_num: int) -> Widget | None

:::warning Deprecated since 4.10 This API is deprecated. :::

Returns the child widget contained in page number page_num.

Parameters:

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

get_page¶

def get_page(self, child: Widget) -> AssistantPage

:::warning Deprecated since 4.10 This API is deprecated. :::

Returns the GtkAssistantPage object for child.

Parameters:

child — a child of assistant

get_page_complete¶

def get_page_complete(self, page: Widget) -> bool

:::warning Deprecated since 4.10 This API is deprecated. :::

Gets whether page is complete.

Parameters:

page — a page of assistant

get_page_title¶

def get_page_title(self, page: Widget) -> str

:::warning Deprecated since 4.10 This API is deprecated. :::

Gets the title for page.

Parameters:

page — a page of assistant

get_page_type¶

def get_page_type(self, page: Widget) -> AssistantPageType

:::warning Deprecated since 4.10 This API is deprecated. :::

Gets the page type of page.

Parameters:

page — a page of assistant

get_pages¶

def get_pages(self) -> Gio.ListModel

:::warning Deprecated since 4.10 This API is deprecated. :::

Gets a list model of the assistant pages.

insert_page¶

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

:::warning Deprecated since 4.10 This API is deprecated. :::

Inserts a page in the assistant at a given position.

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¶

def next_page(self) -> None

:::warning Deprecated since 4.10 This API is deprecated. :::

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 AssistantPageType.CUSTOM type.

prepend_page¶

def prepend_page(self, page: Widget) -> int

:::warning Deprecated since 4.10 This API is deprecated. :::

Prepends a page to the assistant.

Parameters:

page — a GtkWidget

previous_page¶

def previous_page(self) -> None

:::warning Deprecated since 4.10 This API is deprecated. :::

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 AssistantPageType.CUSTOM type.

remove_action_widget¶

def remove_action_widget(self, child: Widget) -> None

:::warning Deprecated since 4.10 This API is deprecated. :::

Removes a widget from the action area of a GtkAssistant.

Parameters:

child — a GtkWidget

remove_page¶

def remove_page(self, page_num: int) -> None

:::warning Deprecated since 4.10 This API is deprecated. :::

Removes the page_num’s page from assistant.

Parameters:

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

set_current_page¶

def set_current_page(self, page_num: int) -> None

:::warning Deprecated since 4.10 This API is deprecated. :::

Switches the page to page_num.

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

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¶

def set_forward_page_func(self, page_func: AssistantPageFunc | None = ...) -> None

:::warning Deprecated since 4.10 This API is deprecated. :::

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.

Parameters:

page_func — the GtkAssistantPageFunc, or None to use the default one

set_page_complete¶

def set_page_complete(self, page: Widget, complete: bool) -> None

:::warning Deprecated since 4.10 This API is deprecated. :::

Sets whether page contents are complete.

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

Parameters:

page — a page of assistant
complete — the completeness status of the page

set_page_title¶

def set_page_title(self, page: Widget, title: str) -> None

:::warning Deprecated since 4.10 This API is deprecated. :::

Sets a title for page.

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

Parameters:

page — a page of assistant
title — the new title for page

set_page_type¶

def set_page_type(self, page: Widget, type: AssistantPageType | int) -> None

:::warning Deprecated since 4.10 This API is deprecated. :::

Sets the page type for page.

The page type determines the page behavior in the assistant.

Parameters:

page — a page of assistant
type — the new type for page

update_buttons_state¶

def update_buttons_state(self) -> None

:::warning Deprecated since 4.10 This API is deprecated. :::

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.

Properties¶

pages¶

pages: Gio.ListModel  # read-only

GListModel containing the pages.

use_header_bar¶

use_header_bar: int  # read/write

:::warning Deprecated since 4.10 This API is deprecated. :::

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.

Signals¶

apply¶

def on_apply(self) -> None: ...

:::warning Deprecated since 4.10 This API is deprecated. :::

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 AssistantPageType.PROGRESS after the confirmation page and handle this operation within the Assistant.prepare signal of the progress page.

cancel¶

def on_cancel(self) -> None: ...

:::warning Deprecated since 4.10 This API is deprecated. :::

Emitted when then the cancel button is clicked.

close¶

def on_close(self) -> None: ...

:::warning Deprecated since 4.10 This API is deprecated. :::

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 AssistantPageType.CONFIRM) is clicked.

escape¶

def on_escape(self) -> None: ...

:::warning Deprecated since 4.10 This API is deprecated. :::

The action signal for the Escape binding.

prepare¶

def on_prepare(self, page: Widget) -> None: ...

:::warning Deprecated since 4.10 This API is deprecated. :::

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.