Description
A GtkAssistant is a widget used to represent a generally complex
operation splitted in several steps, guiding the user through its
pages and controlling the page flow to collect the necessary data.
The design of GtkAssistant is that it controls what buttons to show
and to make sensitive, based on what it knows about the page sequence
and the type of each page,
in addition to state information like the page
completion
and committed status.
If you have a case that doesn’t quite fit in GtkAssistants way of
handling buttons, you can use the GTK_ASSISTANT_PAGE_CUSTOM page
type and handle buttons yourself.
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, and set its child properties
as necessary.
CSS nodes
GtkAssistant has a single CSS node with the name assistant.
Functions
gtk_assistant_get_current_page ()
gint
gtk_assistant_get_current_page (GtkAssistant *assistant);
Returns the page number of the current page.
Returns
The index (starting from 0) of the current
page in the assistant
, or -1 if the assistant
has no pages,
or no current page.
Since: 2.10
gtk_assistant_set_current_page ()
void
gtk_assistant_set_current_page (GtkAssistant *assistant,
gint page_num);
Switches the page to page_num
.
Note that this will only be necessary in custom buttons,
as the assistant
flow can be set with
gtk_assistant_set_forward_page_func().
Since: 2.10
gtk_assistant_get_n_pages ()
gint
gtk_assistant_get_n_pages (GtkAssistant *assistant);
Returns the number of pages in the assistant
Returns
the number of pages in the assistant
Since: 2.10
gtk_assistant_get_nth_page ()
GtkWidget *
gtk_assistant_get_nth_page (GtkAssistant *assistant,
gint page_num);
Returns the child widget contained in page number page_num
.
Returns
the child widget, or NULL
if page_num
is out of bounds.
[nullable][transfer none]
Since: 2.10
gtk_assistant_prepend_page ()
gint
gtk_assistant_prepend_page (GtkAssistant *assistant,
GtkWidget *page);
Prepends a page to the assistant
.
Returns
the index (starting at 0) of the inserted page
Since: 2.10
gtk_assistant_append_page ()
gint
gtk_assistant_append_page (GtkAssistant *assistant,
GtkWidget *page);
Appends a page to the assistant
.
Returns
the index (starting at 0) of the inserted page
Since: 2.10
gtk_assistant_insert_page ()
gint
gtk_assistant_insert_page (GtkAssistant *assistant,
GtkWidget *page,
gint position);
Inserts a page in the assistant
at a given position.
Returns
the index (starting from 0) of the inserted page
Since: 2.10
gtk_assistant_remove_page ()
void
gtk_assistant_remove_page (GtkAssistant *assistant,
gint page_num);
Removes the page_num
’s page from assistant
.
Since: 3.2
GtkAssistantPageFunc ()
gint
(*GtkAssistantPageFunc) (gint current_page,
gpointer data);
A function used by gtk_assistant_set_forward_page_func() to know which
is the next page given a current one. It’s called both for computing the
next page when the user presses the “forward” button and for handling
the behavior of the “last” button.
Returns
The next page number.
gtk_assistant_set_forward_page_func ()
void
gtk_assistant_set_forward_page_func (GtkAssistant *assistant,
GtkAssistantPageFunc page_func,
gpointer data,
GDestroyNotify destroy);
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 NULL will make the assistant to
use the default forward function, which just goes to the
next visible page.
Since: 2.10
gtk_assistant_set_page_type ()
void
gtk_assistant_set_page_type (GtkAssistant *assistant,
GtkWidget *page,
GtkAssistantPageType type);
Sets the page type for page
.
The page type determines the page behavior in the assistant
.
Since: 2.10
gtk_assistant_set_page_title ()
void
gtk_assistant_set_page_title (GtkAssistant *assistant,
GtkWidget *page,
const gchar *title);
Sets a title for page
.
The title is displayed in the header area of the assistant
when page
is the current page.
Since: 2.10
gtk_assistant_get_page_title ()
const gchar *
gtk_assistant_get_page_title (GtkAssistant *assistant,
GtkWidget *page);
Gets the title for page
.
Returns
the title for page
Since: 2.10
gtk_assistant_set_page_header_image ()
void
gtk_assistant_set_page_header_image (GtkAssistant *assistant,
GtkWidget *page,
GdkPixbuf *pixbuf);
gtk_assistant_set_page_header_image has been deprecated since version 3.2 and should not be used in newly-written code.
Since GTK+ 3.2, a header is no longer shown;
add your header decoration to the page content instead.
Sets a header image for page
.
Since: 2.10
gtk_assistant_get_page_header_image ()
GdkPixbuf *
gtk_assistant_get_page_header_image (GtkAssistant *assistant,
GtkWidget *page);
gtk_assistant_get_page_header_image has been deprecated since version 3.2 and should not be used in newly-written code.
Since GTK+ 3.2, a header is no longer shown;
add your header decoration to the page content instead.
Gets the header image for page
.
Returns
the header image for page
,
or NULL if there’s no header image for the page.
[transfer none]
Since: 2.10
gtk_assistant_set_page_side_image ()
void
gtk_assistant_set_page_side_image (GtkAssistant *assistant,
GtkWidget *page,
GdkPixbuf *pixbuf);
gtk_assistant_set_page_side_image has been deprecated since version 3.2 and should not be used in newly-written code.
Since GTK+ 3.2, sidebar images are not
shown anymore.
Sets a side image for page
.
This image used to be displayed in the side area of the assistant
when page
is the current page.
Since: 2.10
gtk_assistant_get_page_side_image ()
GdkPixbuf *
gtk_assistant_get_page_side_image (GtkAssistant *assistant,
GtkWidget *page);
gtk_assistant_get_page_side_image has been deprecated since version 3.2 and should not be used in newly-written code.
Since GTK+ 3.2, sidebar images are not
shown anymore.
Gets the side image for page
.
Returns
the side image for page
,
or NULL if there’s no side image for the page.
[transfer none]
Since: 2.10
gtk_assistant_set_page_complete ()
void
gtk_assistant_set_page_complete (GtkAssistant *assistant,
GtkWidget *page,
gboolean complete);
Sets whether page
contents are complete.
This will make assistant
update the buttons state
to be able to continue the task.
Since: 2.10
gtk_assistant_get_page_complete ()
gboolean
gtk_assistant_get_page_complete (GtkAssistant *assistant,
GtkWidget *page);
Gets whether page
is complete.
Returns
TRUE if page
is complete.
Since: 2.10
gtk_assistant_set_page_has_padding ()
void
gtk_assistant_set_page_has_padding (GtkAssistant *assistant,
GtkWidget *page,
gboolean has_padding);
Sets whether the assistant is adding padding around
the page.
Since: 3.18
gtk_assistant_get_page_has_padding ()
gboolean
gtk_assistant_get_page_has_padding (GtkAssistant *assistant,
GtkWidget *page);
Gets whether page has padding.
Returns
TRUE if page
has padding
Since: 3.18
gtk_assistant_add_action_widget ()
void
gtk_assistant_add_action_widget (GtkAssistant *assistant,
GtkWidget *child);
Adds a widget to the action area of a GtkAssistant.
Since: 2.10
gtk_assistant_remove_action_widget ()
void
gtk_assistant_remove_action_widget (GtkAssistant *assistant,
GtkWidget *child);
Removes a widget from the action area of a GtkAssistant.
Since: 2.10
gtk_assistant_update_buttons_state ()
void
gtk_assistant_update_buttons_state (GtkAssistant *assistant);
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.
Since: 2.10
gtk_assistant_commit ()
void
gtk_assistant_commit (GtkAssistant *assistant);
Erases the visited page history so the back button is not
shown 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.
Since: 2.22
gtk_assistant_next_page ()
void
gtk_assistant_next_page (GtkAssistant *assistant);
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_ASSISTANT_PAGE_CUSTOM type.
Since: 3.0
gtk_assistant_previous_page ()
void
gtk_assistant_previous_page (GtkAssistant *assistant);
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_ASSISTANT_PAGE_CUSTOM type.
Since: 3.0
Signal Details
The “apply” signal
void
user_function (GtkAssistant *assistant,
gpointer user_data)
The ::apply signal is 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_ASSISTANT_PAGE_PROGRESS after the confirmation page and handle
this operation within the “prepare” signal of the progress
page.
Flags: Run Last
Since: 2.10
The “cancel” signal
void
user_function (GtkAssistant *assistant,
gpointer user_data)
The ::cancel signal is emitted when then the cancel button is clicked.
Flags: Run Last
Since: 2.10
The “close” signal
void
user_function (GtkAssistant *assistant,
gpointer user_data)
The ::close signal is 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_ASSISTANT_PAGE_CONFIRM) is clicked.
Flags: Run Last
Since: 2.10
The “prepare” signal
void
user_function (GtkAssistant *assistant,
GtkWidget *page,
gpointer user_data)
The ::prepare signal is 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
.
Flags: Run Last
Since: 2.10