Gtk.Assistant¶

Example¶

Subclasses:: None

Methods¶

Inherited:: Gtk.Window (62), Gtk.Widget (181), GObject.Object (37), Gtk.Accessible (15), Gtk.Buildable (1), Gtk.Native (6), Gtk.Root (3)
Structs:: Gtk.WidgetClass (18), GObject.ObjectClass (5)

class	`new` ()
	`add_action_widget` (child)
	`append_page` (page)
	`commit` ()
	`get_current_page` ()
	`get_n_pages` ()
	`get_nth_page` (page_num)
	`get_page` (child)
	`get_page_complete` (page)
	`get_page_title` (page)
	`get_page_type` (page)
	`get_pages` ()
	`insert_page` (page, position)
	`next_page` ()
	`prepend_page` (page)
	`previous_page` ()
	`remove_action_widget` (child)
	`remove_page` (page_num)
	`set_current_page` (page_num)
	`set_forward_page_func` (page_func, *data)
	`set_page_complete` (page, complete)
	`set_page_title` (page, title)
	`set_page_type` (page, type)
	`update_buttons_state` ()

Virtual Methods¶

Inherited:: Gtk.Window (5), Gtk.Widget (25), GObject.Object (7), Gtk.Accessible (6), Gtk.Buildable (9), Gtk.ShortcutManager (2)

Properties¶

Inherited:: Gtk.Window (25), Gtk.Widget (34), Gtk.Accessible (1)

Name	Type	Flags	Short Description
`pages`	`Gio.ListModel`	r
`use-header-bar`	`int`	r/w/co	`deprecated`

Signals¶

Inherited:: Gtk.Window (5), Gtk.Widget (13), GObject.Object (1)

Name	Short Description
`apply`	Emitted when the apply button is clicked. `deprecated`
`cancel`	Emitted when then the cancel button is clicked. `deprecated`
`close`	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 `Gtk.AssistantPageType.CONFIRM`) is clicked. `deprecated`
`escape`	The action signal for the Escape binding. `deprecated`
`prepare`	Emitted when a new page is set as the assistant’s current page, before making the new page visible. `deprecated`

Fields¶

Inherited:: Gtk.Window (5), Gtk.Widget (13), GObject.Object (1)

Class Details¶

class Gtk.Assistant(*args, **kwargs)¶

Bases:: Gtk.Window
Abstract:: No

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

An example Gtk.Assistant

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 [enum`Gtk`.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 Gtk.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 [method`Gtk`.Assistant.get_page].

Gtk.Assistant as Gtk.Buildable

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.

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

classmethod new()[source]¶

Returns:: a newly created GtkAssistant
Return type:: Gtk.Widget

Creates a new GtkAssistant.

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

add_action_widget(child)[source]¶

Parameters:: child (Gtk.Widget) – a GtkWidget

Adds a widget to the action area of a GtkAssistant.

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

append_page(page)[source]¶

Parameters:: page (Gtk.Widget) – a GtkWidget
Returns:: the index (starting at 0) of the inserted page
Return type:: int

Appends a page to the self.

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

commit()[source]¶

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()[source]¶

Returns:: The index (starting from 0) of the current page in the self, or -1 if the self has no pages, or no current page
Return type:: 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()[source]¶

Returns:: the number of pages in the self
Return type:: int

Returns the number of pages in the self

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

get_nth_page(page_num)[source]¶

Parameters:: page_num (int) – the index of a page in the self, or -1 to get the last page
Returns:: the child widget, or None if page_num is out of bounds
Return type:: Gtk.Widget or None

Returns the child widget contained in page number page_num.

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

get_page(child)[source]¶

Parameters:: child (Gtk.Widget) – a child of self
Returns:: the GtkAssistantPage for child
Return type:: Gtk.AssistantPage

Returns the GtkAssistantPage object for child.

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

get_page_complete(page)[source]¶

Parameters:: page (Gtk.Widget) – a page of self
Returns:: True if page is complete.
Return type:: bool

Gets whether page is complete.

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

get_page_title(page)[source]¶

Parameters:: page (Gtk.Widget) – a page of self
Returns:: the title for page
Return type:: str

Gets the title for page.

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

get_page_type(page)[source]¶

Parameters:: page (Gtk.Widget) – a page of self
Returns:: the page type of page
Return type:: Gtk.AssistantPageType

Gets the page type of page.

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

get_pages()[source]¶

Returns:: A list model of the pages.
Return type:: Gio.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, position)[source]¶

Parameters:

page (Gtk.Widget) – a GtkWidget
position (int) – the index (starting at 0) at which to insert the page, or -1 to append the page to the self

Returns:

the index (starting from 0) of the inserted page

Return type:

int

Inserts a page in the self at a given position.

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

next_page()[source]¶

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

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

prepend_page(page)[source]¶

Parameters:: page (Gtk.Widget) – a GtkWidget
Returns:: the index (starting at 0) of the inserted page
Return type:: int

Prepends a page to the self.

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

previous_page()[source]¶

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

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

remove_action_widget(child)[source]¶

Parameters:: child (Gtk.Widget) – a GtkWidget

Removes a widget from the action area of a GtkAssistant.

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

remove_page(page_num)[source]¶

Parameters:: page_num (int) – the index of a page in the self, or -1 to remove the last page

Removes the page_num’s page from self.

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

set_current_page(page_num)[source]¶

Parameters:: page_num (int) – 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 self, nothing will be done.

Switches the page to page_num.

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

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

set_forward_page_func(page_func, *data)[source]¶

Parameters:

page_func (Gtk.AssistantPageFunc or None) – the GtkAssistantPageFunc, or None to use the default one
data (object or None) – user data for page_func

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

set_page_complete(page, complete)[source]¶

Parameters:

page (Gtk.Widget) – a page of self
complete (bool) – the completeness status of the page

Sets whether page contents are complete.

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

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

set_page_title(page, title)[source]¶

Parameters:

page (Gtk.Widget) – a page of self
title (str) – the new title for page

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

set_page_type(page, type)[source]¶

Parameters:

page (Gtk.Widget) – a page of self
type (Gtk.AssistantPageType) – the new type for page

Sets the page type for page.

The page type determines the page behavior in the self.

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

update_buttons_state()[source]¶

Forces self 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

Signal Details¶

Gtk.Assistant.signals.apply(assistant)¶

Signal Name:: apply
Flags:: RUN_LAST
Parameters:: assistant (Gtk.Assistant) – The object which received the signal

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

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

Gtk.Assistant.signals.cancel(assistant)¶

Signal Name:: cancel
Flags:: RUN_LAST
Parameters:: assistant (Gtk.Assistant) – The object which received the signal

Emitted when then the cancel button is clicked.

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

Gtk.Assistant.signals.close(assistant)¶

Signal Name:: close
Flags:: RUN_LAST
Parameters:: assistant (Gtk.Assistant) – The object which received the signal

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

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

Gtk.Assistant.signals.escape(assistant)¶

Signal Name:: escape
Flags:: RUN_FIRST, ACTION
Parameters:: assistant (Gtk.Assistant) – The object which received the signal

The action signal for the Escape binding.

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

Gtk.Assistant.signals.prepare(assistant, page)¶

Signal Name:

prepare

Flags:

RUN_LAST

Parameters:

assistant (Gtk.Assistant) – The object which received the signal
page (Gtk.Widget) – the current page

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

Property Details¶

Gtk.Assistant.props.pages¶

Name:: pages
Type:: Gio.ListModel
Default Value:: None
Flags:: READABLE

GListModel containing the pages.

Gtk.Assistant.props.use_header_bar¶

Name:: use-header-bar
Type:: int
Default Value:: -1
Flags:: READABLE, WRITABLE, CONSTRUCT_ONLY

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