gtk.Assistant
Prev | The gtk Class Reference | Next

## gtk.Assistant

gtk.Assistant — a widget used to guide users through multi-step operations (new in PyGTK 2.10)

## Synopsis

    class gtk.Assistant(gtk.Window):
        gtk.Assistant()
        def get_current_page()
        def set_current_page(page_num)
        def get_n_pages()
        def get_nth_page(page_num)
        def prepend_page(page)
        def append_page(page)
        def insert_page(page, position)
        def set_forward_page_func(page_func, data)
        def set_page_type(page, type)
        def get_page_type(page)
        def set_page_title(page, title)
        def get_page_title(page)
        def set_page_header_image(page, pixbuf=None)
        def get_page_header_image(page)
        def set_page_side_image(page, pixbuf=None)
        def get_page_side_image(page)
        def set_page_complete(page, complete)
        def get_page_complete(page)
        def add_action_widget(child)
        def remove_action_widget(child)
        def update_buttons_state()
        def commit()

## Ancestry

    +-- gobject.GObject
      +-- gtk.Object
        +-- gtk.Widget
          +-- gtk.Container
            +-- gtk.Bin
              +-- gtk.Window
                +-- gtk.Assistant

## Implemented Interfaces

`gtk.Assistant` implements `gtk.Buildable`

## gtk.Assistant Properties

gtk.Object Properties

gtk.Widget Properties

gtk.Container Properties

gtk.Window Properties

## gtk.Assistant Style Properties

gtk.Widget Style Properties

"content-padding" | Read | Number of pixels around the content pages. Allowed values: >= 0. Default value: 1. This property is available in GTK+ 2.10 and above.
"header-padding" | Read | Number of pixels around the header. Allowed values: >= 0 Default value: 6. This property is available in GTK+ 2.10 and above.

## gtk.Assistant Child Properties

"complete" | Read-Write | If `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`. This property is available in GTK+ 2.10 and above.
"header-image" | Read-Write | The `gtk.gdk.Pixbuf` image that is displayed in the page header. This property is available in GTK+ 2.10 and above.
"page-type" | Read-Write | The type of the assistant page - one of the GTK Assistant Page Type Constants . Default value: `gtk.ASSISTANT_PAGE_CONTENT`. This property is available in GTK+ 2.10 and above.
"sidebar-image" | Read-Write | The `gtk.gdk.Pixbuf` image displayed in the sidebar for the assistant page. Set this to `None` to make the sidebar disappear. This property is available in GTK+ 2.10 and above.
"title" | Read-Write | The title that is displayed in the page header. If "title" and "header-image" are both `None`, no header is displayed. Default value: `None`. This property is available in GTK+ 2.10 and above.

## gtk.Assistant Signal Prototypes

gobject.GObject Signal Prototypes

gtk.Object Signal Prototypes

gtk.Widget Signal Prototypes

gtk.Container Signal Prototypes

gtk.Window Signal Prototypes

"apply" | `def callback(`widget`, `user_param1`, `...`)`
"cancel" | `def callback(`widget`, `user_param1`, `...`)`
"close" | `def callback(`widget`, `user_param1`, `...`)`
"prepare" | `def callback(`widget`, `page`, `user_param1`, `...`)`

## Description

A `gtk.Assistant` is a widget used to guide the user through a complex operation by breaking it into several steps. Each step is generally handled by one assistant page. The assistant controls the page flow to collect the necessary data to complete the application task.

## Constructor

### gtk.Assistant

        gtk.Assistant()

Returns : | a new `gtk.Assistant` object.

### Note

This constructor is available in PyGTK 2.10 and above.

Creates a new `gtk.Assistant`.

## Methods

### gtk.Assistant.get_current_page

        def get_current_page()

Returns :, `` : | The index (starting from 0) of the current page in the assistant, if the assistant has no pages, -1 will be returned.

### Note

This method is available in PyGTK 2.10 and above.

The `get_current_page`() method returns the page number of the current page.

### gtk.Assistant.set_current_page

        def set_current_page(page_num)

`page_num` : | the 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, there will be no change.

### Note

This method is available in PyGTK 2.10 and above.

The `set_current_page`() method switches the page to the page specified by `page_num`. Note that this will only be necessary in custom buttons, as the assistant flow can be set with the `set_forward_page_func`() method.

### gtk.Assistant.get_n_pages

        def get_n_pages()

Returns : | The number of pages in the assistant.

### Note

This method is available in PyGTK 2.10 and above.

The `get_n_pages`() method returns the number of pages in the assistant

### gtk.Assistant.get_nth_page

        def get_nth_page(page_num)

`page_num` : | The index of a page in the assistant, or -1 to get the last page;
Returns : | The child widget, or `None` if `page_num` is out of bounds.

### Note

This method is available in PyGTK 2.10 and above.

The `get_nth_page`() method returns the child widget contained in the page specified by `page_num`.

### gtk.Assistant.prepend_page

        def prepend_page(page)

`page` : | a `gtk.Widget`
Returns : | the index (starting at 0) of the inserted page

### Note

This method is available in PyGTK 2.10 and above.

The `prepend_page`() method prepends the page specified by `page` to the assistant.

### gtk.Assistant.append_page

        def append_page(page)

`page` : | a `gtk.Widget`
Returns : | the index (starting at 0) of the inserted page

### Note

This method is available in PyGTK 2.10 and above.

The `append_page`() method appends the page specified by `page` to the assistant.

### gtk.Assistant.insert_page

        def insert_page(page, position)

`page` : | a `gtk.Widget`
`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

### Note

This method is available in PyGTK 2.10 and above.

The `insert_page`() method inserts the page specified by `page` in the assistant at the position index specified by `position`.

### gtk.Assistant.set_forward_page_func

        def set_forward_page_func(page_func, data)

`page_func` : | the function, or `None` to use the default function.
`data` : | user data for `page_func`

### Note

This method is available in PyGTK 2.10 and above.

The `set_forward_page_func`() method 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 use the default forward function, which just goes to the next visible page.

The signature of `page_func` is:

            def page_func(current_page, user_data):

where `current_page` is the index of the current page and `user_data` is `data`.

### gtk.Assistant.set_page_type

        def set_page_type(page, type)

`page` : | a page in the assistant
`type` : | the new type for `page`

### Note

This method is available in PyGTK 2.10 and above.

The `set_page_type`() method sets the page type, which specifies the page behavior, for the page specified by `page` to the value specified by `type`. The page type must be one of the GTK Assistant Page Type Constants.

### gtk.Assistant.get_page_type

        def get_page_type(page)

`page` : | a page in the assistant
Returns : | the page type of `page`.

### Note

This method is available in PyGTK 2.10 and above.

The `get_page_type`() method returns the page type of the page specified by `page`. The page type will be one of the GTK Assistant Page Type Constants.

### gtk.Assistant.set_page_title

        def set_page_title(page, title)

`page` : | a page of the assistant
`title` : | the new title for `page`

### Note

This method is available in PyGTK 2.10 and above.

The `set_page_title`() method sets the title for the page specified by `page` to the string specified by `title`. The title is displayed in the header area of the assistant when `page` is the current page.

### gtk.Assistant.get_page_title

        def get_page_title(page)

`page` : | a page of the assistant
Returns : | the title for `page`.

### Note

This method is available in PyGTK 2.10 and above.

The `get_page_title`() method returns the title for the page specified by `page`.

### gtk.Assistant.set_page_header_image

        def set_page_header_image(page, pixbuf=None)

`page` : | a page of the assistant
`pixbuf` : | the new header image for `page` or `None`.

### Note

This method is available in PyGTK 2.10 and above.

The `set_page_header_image`() method sets the `gtk.gdk.Pixbuf` specified by `pixbuf` as the header image for the page specified by `page`. This image is displayed in the header area of the assistant when `page` is the current page. If `pixbuf` is `None` the header image will be removed.

### gtk.Assistant.get_page_header_image

        def get_page_header_image(page)

`page` : | a page of the assistant
Returns : | the header image for `page`, or `None` if there's no header image for the page.

### Note

This method is available in PyGTK 2.10 and above.

The `get_page_header_image`() method returns the header image for the page specified by `page`.

### gtk.Assistant.set_page_side_image

        def set_page_side_image(page, pixbuf=None)

`page` : | a page of the assistant
`pixbuf` : | the new side image for `page` or `None`.

### Note

This method is available in PyGTK 2.10 and above.

The `set_page_side_image`() method sets the `gtk.gdk.Pixbuf` specified by `pixbuf` as the header image for the page specified by `page`. This image is displayed in the side area of the assistant when `page` is the current page. If `pixbuf` is `None` the side image will be removed.

### gtk.Assistant.get_page_side_image

        def get_page_side_image(page)

`page` : | a page of the assistant
Returns : | the side image for `page`, or `None` if there's no side image for the page.

### Note

This method is available in PyGTK 2.10 and above.

The `get_page_side_image`() method returns the header image for the page specified by `page`.

### gtk.Assistant.set_page_complete

        def set_page_complete(page, complete)

`page` : | a page of the assistant
`complete` : | if `True` the page status is complete.

### Note

This method is available in PyGTK 2.10 and above.

The `set_page_complete`() method sets the "complete" property of the page specified by `page` to the value specified by `complete`. If `complete` is `True` the `page` contents are complete. This will make the assistant update the state of its buttons.

### gtk.Assistant.get_page_complete

        def get_page_complete(page)

`page` : | a page of the assistant
Returns : | `True` if `page` is complete.

### Note

This method is available in PyGTK 2.10 and above.

The `get_page_complete`() method returns the value of the "complete" property of the page specified by `page`. If the return value is `True`, the `page` contents are complete.

### gtk.Assistant.add_action_widget

        def add_action_widget(child)

`child` : | a `gtk.Widget`

### Note

This method is available in PyGTK 2.10 and above.

The `add_action_widget`() method adds the widget specified by `child` to the action area of the assistant.

### gtk.Assistant.remove_action_widget

        def remove_action_widget(child)

`child` : | a `gtk.Widget`

### Note

This method is available in PyGTK 2.10 and above.

The `remove_action_widget`() method removes the widget specified by `child` from the action area of the assistant.

### gtk.Assistant.update_buttons_state

        def update_buttons_state()

### Note

This method is available in PyGTK 2.10 and above.

The `update_buttons_state`() method forces the assistant to recompute the state of its buttons.

PyGTK 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

        def commit()

### Note

This method is available in PyGTK 2.22 and above.

The `commit`() method 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.

## Signals

### The "apply" Signal

        def callback(assistant, user_param1, ...)

`assistant` : | the `gtk.Assistant` that received the signal
`user_param1` : | the first user parameter (if any) specified with the `connect`() method
`...` : | additional user parameters (if any)

The "apply" signal is emitted when the apply button is clicked. The default behavior of the `gtk.Assistant` 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.

### The "cancel" Signal

        def callback(assistant, user_param1, ...)

`assistant` : | the `gtk.Assistant` that received the signal
`user_param1` : | the first user parameter (if any) specified with the `connect`() method
`...` : | additional user parameters (if any)

The "cancel" signal is emitted when the cancel button is clicked.

### The "close" Signal

        def callback(assistant, user_param1, ...)

`assistant` : | the `gtk.Assistant` that received the signal
`user_param1` : | the first user parameter (if any) specified with the `connect`() method
`...` : | additional user parameters (if any)

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.

### The "prepare" Signal

        def callback(assistant, page, user_param1, ...)

`assistant` : | the `gtk.Assistant` that received the signal
`page` : | the new page to prepare for display
`user_param1` : | the first user parameter (if any) specified with the `connect`() method
`...` : | additional user parameters (if any)

The "prepare" signal is emitted when a new page is set as the assistant's current page, but before making the new page visible. A handler for this signal can do any preparation that are necessary before showing `page`.

Prev | Up | Next
gtk.AspectFrame | Home | gtk.Bin