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
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 forchild
.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 fromassistant
.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 withset_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
toNone
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
, orNone
to use the default onedata – 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.use_header_bar: int
True
if the assistant uses aGtkHeaderBar
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
orFalse
.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 theprepare
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