CtkAssistant as CtkBuildable

The CtkAssistant implementation of the CtkBuildable interface exposes the action_area as internal children with the name “action_area”.

To add pages to an assistant in CtkBuilder, simply add it as a child to the CtkAssistant object, and set its child properties as necessary.

CSS nodes

CtkAssistant has a single CSS node with the name assistant.

ctk_assistant_new ()

CtkWidget *
ctk_assistant_new (void);

Creates a new CtkAssistant.

Since: 2.10

ctk_assistant_get_current_page ()

gint
ctk_assistant_get_current_page (CtkAssistant *assistant);

Returns the page number of the current page.

Since: 2.10

ctk_assistant_set_current_page ()

void
ctk_assistant_set_current_page (CtkAssistant *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 ctk_assistant_set_forward_page_func().

Since: 2.10

ctk_assistant_get_n_pages ()

gint
ctk_assistant_get_n_pages (CtkAssistant *assistant);

Returns the number of pages in the assistant

Since: 2.10

ctk_assistant_get_nth_page ()

CtkWidget *
ctk_assistant_get_nth_page (CtkAssistant *assistant,
                            gint page_num);

Returns the child widget contained in page number page_num .

Since: 2.10

ctk_assistant_prepend_page ()

gint
ctk_assistant_prepend_page (CtkAssistant *assistant,
                            CtkWidget *page);

Prepends a page to the assistant .

Since: 2.10

ctk_assistant_append_page ()

gint
ctk_assistant_append_page (CtkAssistant *assistant,
                           CtkWidget *page);

Appends a page to the assistant .

Since: 2.10

ctk_assistant_insert_page ()

gint
ctk_assistant_insert_page (CtkAssistant *assistant,
                           CtkWidget *page,
                           gint position);

Inserts a page in the assistant at a given position.

Since: 2.10

ctk_assistant_remove_page ()

void
ctk_assistant_remove_page (CtkAssistant *assistant,
                           gint page_num);

Removes the page_num ’s page from assistant .

Since: 3.2

CtkAssistantPageFunc ()

gint
(*CtkAssistantPageFunc) (gint current_page,
                         gpointer data);

A function used by ctk_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.

ctk_assistant_set_forward_page_func ()

void
ctk_assistant_set_forward_page_func (CtkAssistant *assistant,
                                     CtkAssistantPageFunc 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

ctk_assistant_set_page_type ()

void
ctk_assistant_set_page_type (CtkAssistant *assistant,
                             CtkWidget *page,
                             CtkAssistantPageType type);

Sets the page type for page .

The page type determines the page behavior in the assistant .

Since: 2.10

ctk_assistant_get_page_type ()

CtkAssistantPageType
ctk_assistant_get_page_type (CtkAssistant *assistant,
                             CtkWidget *page);

Gets the page type of page .

Since: 2.10

ctk_assistant_set_page_title ()

void
ctk_assistant_set_page_title (CtkAssistant *assistant,
                              CtkWidget *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

ctk_assistant_get_page_title ()

const gchar *
ctk_assistant_get_page_title (CtkAssistant *assistant,
                              CtkWidget *page);

Gets the title for page .

Since: 2.10

ctk_assistant_set_page_header_image ()

void
ctk_assistant_set_page_header_image (CtkAssistant *assistant,
                                     CtkWidget *page,
                                     GdkPixbuf *pixbuf);

Sets a header image for page .

Since: 2.10

ctk_assistant_get_page_header_image ()

GdkPixbuf *
ctk_assistant_get_page_header_image (CtkAssistant *assistant,
                                     CtkWidget *page);

Gets the header image for page .

Since: 2.10

ctk_assistant_set_page_side_image ()

void
ctk_assistant_set_page_side_image (CtkAssistant *assistant,
                                   CtkWidget *page,
                                   GdkPixbuf *pixbuf);

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

ctk_assistant_get_page_side_image ()

GdkPixbuf *
ctk_assistant_get_page_side_image (CtkAssistant *assistant,
                                   CtkWidget *page);

Gets the side image for page .

Since: 2.10

ctk_assistant_set_page_complete ()

void
ctk_assistant_set_page_complete (CtkAssistant *assistant,
                                 CtkWidget *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

ctk_assistant_get_page_complete ()

gboolean
ctk_assistant_get_page_complete (CtkAssistant *assistant,
                                 CtkWidget *page);

Gets whether page is complete.

Since: 2.10

ctk_assistant_set_page_has_padding ()

void
ctk_assistant_set_page_has_padding (CtkAssistant *assistant,
                                    CtkWidget *page,
                                    gboolean has_padding);

Sets whether the assistant is adding padding around the page.

Since: 3.18

ctk_assistant_get_page_has_padding ()

gboolean
ctk_assistant_get_page_has_padding (CtkAssistant *assistant,
                                    CtkWidget *page);

Gets whether page has padding.

Since: 3.18

ctk_assistant_add_action_widget ()

void
ctk_assistant_add_action_widget (CtkAssistant *assistant,
                                 CtkWidget *child);

Adds a widget to the action area of a CtkAssistant.

Since: 2.10

ctk_assistant_remove_action_widget ()

void
ctk_assistant_remove_action_widget (CtkAssistant *assistant,
                                    CtkWidget *child);

Removes a widget from the action area of a CtkAssistant.

Since: 2.10

ctk_assistant_update_buttons_state ()

void
ctk_assistant_update_buttons_state (CtkAssistant *assistant);

Forces assistant to recompute the buttons state.

CTK+ 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

ctk_assistant_commit ()

void
ctk_assistant_commit (CtkAssistant *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

ctk_assistant_next_page ()

void
ctk_assistant_next_page (CtkAssistant *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 CTK_ASSISTANT_PAGE_CUSTOM type.

Since: 3.0

ctk_assistant_previous_page ()

void
ctk_assistant_previous_page (CtkAssistant *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 CTK_ASSISTANT_PAGE_CUSTOM type.

Since: 3.0

struct CtkAssistant

struct CtkAssistant;

struct CtkAssistantClass

struct CtkAssistantClass {
  CtkWindowClass parent_class;

  void (* prepare) (CtkAssistant *assistant, CtkWidget *page);
  void (* apply)   (CtkAssistant *assistant);
  void (* close)   (CtkAssistant *assistant);
  void (* cancel)  (CtkAssistant *assistant);
};

enum CtkAssistantPageType

An enum for determining the page role inside the CtkAssistant. It's used to handle buttons sensitivity and visibility.

Note that an assistant needs to end its page flow with a page of type CTK_ASSISTANT_PAGE_CONFIRM, CTK_ASSISTANT_PAGE_SUMMARY or CTK_ASSISTANT_PAGE_PROGRESS to be correct.

The Cancel button will only be shown if the page isn’t “committed”. See ctk_assistant_commit() for details.

The “use-header-bar” property

  “use-header-bar”           int

TRUE if the assistant uses a CtkHeaderBar 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: CtkAssistant

Flags: Read / Write / Construct Only

Allowed values: [-1,1]

Default value: -1

Since: 3.12

The “apply” signal

void
user_function (CtkAssistant *assistant,
               gpointer      user_data)

The ::apply signal is emitted when the apply button is clicked.

The default behavior of the CtkAssistant 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 CTK_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 (CtkAssistant *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 (CtkAssistant *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 CTK_ASSISTANT_PAGE_CONFIRM) is clicked.

Flags: Run Last

Since: 2.10

The “escape” signal

void
user_function (CtkAssistant *ctkassistant,
               gpointer      user_data)

Flags: Action

The “prepare” signal

void
user_function (CtkAssistant *assistant,
               CtkWidget    *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