Top |
Functions
GtkWidget * | gtk_assistant_new () |
GtkAssistantPage * | gtk_assistant_get_page () |
GListModel * | gtk_assistant_get_pages () |
GtkWidget * | gtk_assistant_page_get_child () |
int | gtk_assistant_get_current_page () |
void | gtk_assistant_set_current_page () |
int | gtk_assistant_get_n_pages () |
GtkWidget * | gtk_assistant_get_nth_page () |
int | gtk_assistant_prepend_page () |
int | gtk_assistant_append_page () |
int | gtk_assistant_insert_page () |
void | gtk_assistant_remove_page () |
int | (*GtkAssistantPageFunc) () |
void | gtk_assistant_set_forward_page_func () |
void | gtk_assistant_set_page_type () |
GtkAssistantPageType | gtk_assistant_get_page_type () |
void | gtk_assistant_set_page_title () |
const char * | gtk_assistant_get_page_title () |
void | gtk_assistant_set_page_complete () |
gboolean | gtk_assistant_get_page_complete () |
void | gtk_assistant_add_action_widget () |
void | gtk_assistant_remove_action_widget () |
void | gtk_assistant_update_buttons_state () |
void | gtk_assistant_commit () |
void | gtk_assistant_next_page () |
void | gtk_assistant_previous_page () |
Properties
GListModel * | pages | Read |
int | use-header-bar | Read / Write / Construct Only |
GtkWidget * | child | Read / Write / Construct Only |
gboolean | complete | Read / Write |
GtkAssistantPageType | page-type | Read / Write |
char * | title | Read / Write |
Object Hierarchy
GObject ├── GInitiallyUnowned │ ╰── GtkWidget │ ╰── GtkWindow │ ╰── GtkAssistant ╰── GtkAssistantPage
Implemented Interfaces
GtkAssistant implements GtkAccessible, GtkBuildable, GtkConstraintTarget, GtkNative, GtkShortcutManager and GtkRoot.
Description
A GtkAssistant is a widget used to represent a generally complex operation split up into several 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 type of each page in addition to state information like the completion and committed page statuses.
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 maintains a GtkAssistantPage object for each added
child, which holds additional per-child properties. You
obtain the GtkAssistantPage for a child with gtk_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.
Functions
gtk_assistant_get_page ()
GtkAssistantPage * gtk_assistant_get_page (GtkAssistant *assistant
,GtkWidget *child
);
Returns the GtkAssistantPage object for child
.
gtk_assistant_get_pages ()
GListModel *
gtk_assistant_get_pages (GtkAssistant *assistant
);
Gets a list model of the assistant pages.
gtk_assistant_page_get_child ()
GtkWidget *
gtk_assistant_page_get_child (GtkAssistantPage *page
);
Returns the child to which page
belongs.
gtk_assistant_get_current_page ()
int
gtk_assistant_get_current_page (GtkAssistant *assistant
);
Returns the page number of the current page.
gtk_assistant_set_current_page ()
void gtk_assistant_set_current_page (GtkAssistant *assistant
,int 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()
.
gtk_assistant_get_n_pages ()
int
gtk_assistant_get_n_pages (GtkAssistant *assistant
);
Returns the number of pages in the assistant
gtk_assistant_get_nth_page ()
GtkWidget * gtk_assistant_get_nth_page (GtkAssistant *assistant
,int page_num
);
Returns the child widget contained in page number page_num
.
gtk_assistant_prepend_page ()
int gtk_assistant_prepend_page (GtkAssistant *assistant
,GtkWidget *page
);
Prepends a page to the assistant
.
gtk_assistant_append_page ()
int gtk_assistant_append_page (GtkAssistant *assistant
,GtkWidget *page
);
Appends a page to the assistant
.
gtk_assistant_insert_page ()
int gtk_assistant_insert_page (GtkAssistant *assistant
,GtkWidget *page
,int position
);
Inserts a page in the assistant
at a given position.
gtk_assistant_remove_page ()
void gtk_assistant_remove_page (GtkAssistant *assistant
,int page_num
);
Removes the page_num
’s page from assistant
.
GtkAssistantPageFunc ()
int (*GtkAssistantPageFunc) (int 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.
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.
Parameters
assistant |
||
page_func |
the GtkAssistantPageFunc, or |
[allow-none] |
data |
user data for |
|
destroy |
destroy notifier for |
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
.
gtk_assistant_get_page_type ()
GtkAssistantPageType gtk_assistant_get_page_type (GtkAssistant *assistant
,GtkWidget *page
);
Gets the page type of page
.
gtk_assistant_set_page_title ()
void gtk_assistant_set_page_title (GtkAssistant *assistant
,GtkWidget *page
,const char *title
);
Sets a title for page
.
The title is displayed in the header area of the assistant
when page
is the current page.
gtk_assistant_get_page_title ()
const char * gtk_assistant_get_page_title (GtkAssistant *assistant
,GtkWidget *page
);
Gets the title for page
.
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.
gtk_assistant_get_page_complete ()
gboolean gtk_assistant_get_page_complete (GtkAssistant *assistant
,GtkWidget *page
);
Gets whether page
is complete.
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.
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.
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.
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.
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.
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.
Types and Values
enum GtkAssistantPageType
An enum for determining the page role inside the GtkAssistant. It's used to handle buttons sensitivity and visibility.
Note that an assistant needs to end its page flow with a page of type
GTK_ASSISTANT_PAGE_CONFIRM
, GTK_ASSISTANT_PAGE_SUMMARY
or
GTK_ASSISTANT_PAGE_PROGRESS
to be correct.
The Cancel button will only be shown if the page isn’t “committed”.
See gtk_assistant_commit()
for details.
Members
The page has regular contents. Both the Back and forward buttons will be shown. |
||
The page contains an introduction to the assistant task. Only the Forward button will be shown if there is a next page. |
||
The page lets the user confirm or deny the changes. The Back and Apply buttons will be shown. |
||
The page informs the user of the changes done. Only the Close button will be shown. |
||
Used for tasks that take a long time to complete, blocks the assistant until the page is marked as complete. Only the back button will be shown. |
||
Used for when other page types are not
appropriate. No buttons will be shown, and the application must
add its own buttons through |
Property Details
The “pages”
property
“pages” GListModel *
The pages of the assistant.
Owner: GtkAssistant
Flags: Read
The “use-header-bar”
property
“use-header-bar” int
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
.
Owner: GtkAssistant
Flags: Read / Write / Construct Only
Allowed values: [-1,1]
Default value: -1
The “child”
property
“child” GtkWidget *
The content the assistant page.
Owner: GtkAssistantPage
Flags: Read / Write / Construct Only
The “complete”
property
“complete” gboolean
Setting the "complete" property to TRUE
marks a page as
complete (i.e.: all the required fields are filled out). GTK uses
this information to control the sensitivity of the navigation buttons.
Owner: GtkAssistantPage
Flags: Read / Write
Default value: FALSE
The “page-type”
property
“page-type” GtkAssistantPageType
The type of the assistant page.
Owner: GtkAssistantPage
Flags: Read / Write
Default value: GTK_ASSISTANT_PAGE_CONTENT
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.
Parameters
assistant |
the GtkAssistant |
|
user_data |
user data set when the signal handler was connected. |
Flags: Run Last
The “cancel”
signal
void user_function (GtkAssistant *assistant, gpointer user_data)
The ::cancel signal is emitted when then the cancel button is clicked.
Parameters
assistant |
the GtkAssistant |
|
user_data |
user data set when the signal handler was connected. |
Flags: Run Last
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.
Parameters
assistant |
the GtkAssistant |
|
user_data |
user data set when the signal handler was connected. |
Flags: Run Last
The “escape”
signal
void user_function (GtkAssistant *assistant, gpointer user_data)
The action signal for the Escape binding.
Parameters
assistant |
the GtkAssistant |
|
user_data |
user data set when the signal handler was connected. |
Flags: Action
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
.
Parameters
assistant |
the GtkAssistant |
|
page |
the current page |
|
user_data |
user data set when the signal handler was connected. |
Flags: Run Last