![]() |
![]() |
![]() |
GTK+ Reference Manual | ![]() |
---|---|---|---|---|
#include <gtk/gtk.h> GtkAssistant; GtkWidget* gtk_assistant_new (void); gint gtk_assistant_get_current_page (GtkAssistant *assistant); void gtk_assistant_set_current_page (GtkAssistant *assistant, gint page_num); gint gtk_assistant_get_n_pages (GtkAssistant *assistant); GtkWidget* gtk_assistant_get_nth_page (GtkAssistant *assistant, gint page_num); gint gtk_assistant_prepend_page (GtkAssistant *assistant, GtkWidget *page); gint gtk_assistant_append_page (GtkAssistant *assistant, GtkWidget *page); gint gtk_assistant_insert_page (GtkAssistant *assistant, GtkWidget *page, gint position); gint (*GtkAssistantPageFunc) (gint current_page, gpointer data); void gtk_assistant_set_forward_page_func (GtkAssistant *assistant, GtkAssistantPageFunc page_func, gpointer data, GDestroyNotify destroy); enum GtkAssistantPageType; void gtk_assistant_set_page_type (GtkAssistant *assistant, GtkWidget *page, GtkAssistantPageType type); GtkAssistantPageType gtk_assistant_get_page_type (GtkAssistant *assistant, GtkWidget *page); void gtk_assistant_set_page_title (GtkAssistant *assistant, GtkWidget *page, const gchar *title); const gchar* gtk_assistant_get_page_title (GtkAssistant *assistant, GtkWidget *page); void gtk_assistant_set_page_header_image (GtkAssistant *assistant, GtkWidget *page, GdkPixbuf *pixbuf); GdkPixbuf* gtk_assistant_get_page_header_image (GtkAssistant *assistant, GtkWidget *page); void gtk_assistant_set_page_side_image (GtkAssistant *assistant, GtkWidget *page, GdkPixbuf *pixbuf); GdkPixbuf* gtk_assistant_get_page_side_image (GtkAssistant *assistant, GtkWidget *page); void gtk_assistant_set_page_complete (GtkAssistant *assistant, GtkWidget *page, gboolean complete); gboolean gtk_assistant_get_page_complete (GtkAssistant *assistant, GtkWidget *page); void gtk_assistant_add_action_widget (GtkAssistant *assistant, GtkWidget *child); void gtk_assistant_remove_action_widget (GtkAssistant *assistant, GtkWidget *child); void gtk_assistant_update_buttons_state (GtkAssistant *assistant);
GObject +----GInitiallyUnowned +----GtkObject +----GtkWidget +----GtkContainer +----GtkBin +----GtkWindow +----GtkAssistant
"complete" gboolean : Read / Write "header-image" GdkPixbuf : Read / Write "page-type" GtkAssistantPageType : Read / Write "sidebar-image" GdkPixbuf : Read / Write "title" gchararray : Read / Write
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.
GtkWidget* gtk_assistant_new (void);
Creates a new GtkAssistant.
Returns : | a newly created GtkAssistant |
Since 2.10
gint gtk_assistant_get_current_page (GtkAssistant *assistant);
Returns the page number of the current page
assistant : | a GtkAssistant |
Returns : | The index (starting from 0) of the current page in the assistant, if the assistant has no pages, -1 will be returned |
Since 2.10
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().
assistant : | a GtkAssistant |
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. |
Since 2.10
gint gtk_assistant_get_n_pages (GtkAssistant *assistant);
Returns the number of pages in the assistant
assistant : | a GtkAssistant |
Returns : | The number of pages in the assistant. |
Since 2.10
GtkWidget* gtk_assistant_get_nth_page (GtkAssistant *assistant, gint page_num);
Returns the child widget contained in page number page_num.
assistant : | a GtkAssistant |
page_num : | The index of a page in the assistant, or -1 to get the last page; |
Returns : | The child widget, or NULL if page_num is out of bounds. |
Since 2.10
gint gtk_assistant_prepend_page (GtkAssistant *assistant, GtkWidget *page);
Prepends a page to the assistant.
assistant : | a GtkAssistant |
page : | a GtkWidget |
Returns : | the index (starting at 0) of the inserted page |
Since 2.10
gint gtk_assistant_append_page (GtkAssistant *assistant, GtkWidget *page);
Appends a page to the assistant.
assistant : | a GtkAssistant |
page : | a GtkWidget |
Returns : | the index (starting at 0) of the inserted page |
Since 2.10
gint gtk_assistant_insert_page (GtkAssistant *assistant, GtkWidget *page, gint position);
Inserts a page in the assistant at a given position.
assistant : | a GtkAssistant |
page : | a GtkWidget |
position : | the index (starting at 0) at which to insert the page, or -1 to append the page to the assistant |
Returns : | the index (starting from 0) of the inserted page |
Since 2.10
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.
current_page : | The page number used to calculate the next page. |
data : | user data. |
Returns : | The next page number. |
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.
assistant : | a GtkAssistant |
page_func : | the GtkAssistantPageFunc, or NULL to use the default one |
data : | user data for page_func |
destroy : | destroy notifier for data |
Since 2.10
typedef enum { GTK_ASSISTANT_PAGE_CONTENT, GTK_ASSISTANT_PAGE_INTRO, GTK_ASSISTANT_PAGE_CONFIRM, GTK_ASSISTANT_PAGE_SUMMARY, GTK_ASSISTANT_PAGE_PROGRESS } 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 or GTK_ASSISTANT_PAGE_SUMMARY to be correct.
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.
assistant : | a GtkAssistant |
page : | a page of assistant |
type : | the new type for page |
Since 2.10
GtkAssistantPageType gtk_assistant_get_page_type (GtkAssistant *assistant, GtkWidget *page);
Gets the page type of page.
assistant : | a GtkAssistant |
page : | a page of assistant |
Returns : | the page type of page. |
Since 2.10
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.
assistant : | a GtkAssistant |
page : | a page of assistant |
title : | the new title for page |
Since 2.10
const gchar* gtk_assistant_get_page_title (GtkAssistant *assistant, GtkWidget *page);
Gets the title for page.
assistant : | a GtkAssistant |
page : | a page of assistant |
Returns : | the title for page. |
Since 2.10
void gtk_assistant_set_page_header_image (GtkAssistant *assistant, GtkWidget *page, GdkPixbuf *pixbuf);
Sets a header image for page. This image is displayed in the header area of the assistant when page is the current page.
assistant : | a GtkAssistant |
page : | a page of assistant |
pixbuf : | the new header image page |
Since 2.10
GdkPixbuf* gtk_assistant_get_page_header_image (GtkAssistant *assistant, GtkWidget *page);
Gets the header image for page.
assistant : | a GtkAssistant |
page : | a page of assistant |
Returns : | the header image for page, or NULL if there's no header image for the page. |
Since 2.10
void gtk_assistant_set_page_side_image (GtkAssistant *assistant, GtkWidget *page, GdkPixbuf *pixbuf);
Sets a header image for page. This image is displayed in the side area of the assistant when page is the current page.
assistant : | a GtkAssistant |
page : | a page of assistant |
pixbuf : | the new header image page |
Since 2.10
GdkPixbuf* gtk_assistant_get_page_side_image (GtkAssistant *assistant, GtkWidget *page);
Gets the header image for page.
assistant : | a GtkAssistant |
page : | a page of assistant |
Returns : | the side image for page, or NULL if there's no side image for the page. |
Since 2.10
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.
assistant : | a GtkAssistant |
page : | a page of assistant |
complete : | the completeness status of the page |
Since 2.10
gboolean gtk_assistant_get_page_complete (GtkAssistant *assistant, GtkWidget *page);
Gets whether page is complete..
assistant : | a GtkAssistant |
page : | a page of assistant |
Returns : | TRUE if page is complete. |
Since 2.10
void gtk_assistant_add_action_widget (GtkAssistant *assistant, GtkWidget *child);
Adds a widget to the action area of a GtkAssistant.
assistant : | a GtkAssistant |
child : | a GtkWidget |
Since 2.10
void gtk_assistant_remove_action_widget (GtkAssistant *assistant, GtkWidget *child);
Removes a widget from the action area of a GtkAssistant.
assistant : | a GtkAssistant |
child : | a GtkWidget |
Since 2.10
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.
assistant : | a GtkAssistant |
Since 2.10
"complete" gboolean : Read / Write
Setting the "complete" child 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.
Default value: FALSE
Since 2.10
"header-image" GdkPixbuf : Read / Write
The image that is displayed next to the page.
Set this to NULL to make the sidebar disappear.
Since 2.10
"page-type" GtkAssistantPageType : Read / Write
The type of the assistant page.
Default value: GTK_ASSISTANT_PAGE_CONTENT
Since 2.10
"sidebar-image" GdkPixbuf : Read / Write
Sidebar image for the assistant page.
"title" gchararray : Read / Write
The title that is displayed in the page header.
If title and header-image are both NULL, no header is displayed.
Default value: NULL
Since 2.10
"content-padding" gint : Read
Number of pixels around the content pages.
Allowed values: >= 0
Default value: 1
void user_function (GtkAssistant *assistant, gpointer user_data) : Run Last
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 to put a page of type GTK_ASSISTANT_PAGE_PROGRESS after the confirmation page and handle this operation within the ::prepare signal of the progress page.
assistant : | the GtkAssistant |
user_data : | user data set when the signal handler was connected. |
Since 2.10
void user_function (GtkAssistant *assistant, gpointer user_data) : Run Last
The ::cancel signal is emitted when then the cancel button is clicked.
assistant : | the GtkAssistant |
user_data : | user data set when the signal handler was connected. |
Since 2.10
void user_function (GtkAssistant *assistant, gpointer user_data) : Run Last
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.
assistant : | the GtkAssistant |
user_data : | user data set when the signal handler was connected. |
Since 2.10
void user_function (GtkAssistant *assistant, GtkWidget *page, gpointer user_data) : Run Last
The ::prepared 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 preparation which are necessary before showing page.
assistant : | the GtkAssistant |
page : | the current page |
user_data : | user data set when the signal handler was connected. |
Since 2.10