gtk.Assistant

gtk.Assistant
Prev	The gtk Class Reference	Next

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.