gtk-0.12.0: Binding to the Gtk+ graphical user interface library.

Portability | portable (depends on GHC)
Stability | provisional
Maintainer | gtk2hs-users@lists.sourceforge.net

Graphics.UI.Gtk.Windows.Assistant

Contents

- Detail
  - GtkAssistant as GtkBuildable
- Class Hierarchy
- Types
- Enums.
- Constructors
- Methods
- Attributes
- Child Attributes
- Signals

Description

A widget used to guide users through multi-step operations

- Module available since Gtk+ version 2.10

Synopsis

- data Assistant
- class WindowClass o => AssistantClass o
- castToAssistant :: GObjectClass obj => obj -> Assistant
- toAssistant :: AssistantClass o => o -> Assistant
- data AssistantPageType
  - = AssistantPageContent
  - | AssistantPageIntro
  - | AssistantPageConfirm
  - | AssistantPageSummary
  - | AssistantPageProgress
- assistantNew :: IO Assistant
- assistantGetNPages :: AssistantClass self => self -> IO Int
- assistantGetNthPage :: AssistantClass self => self -> Int -> IO (Maybe Widget)
- assistantPrependPage :: (AssistantClass self, WidgetClass page) => self -> page -> IO Int
- assistantAppendPage :: (AssistantClass self, WidgetClass page) => self -> page -> IO Int
- assistantInsertPage :: (AssistantClass self, WidgetClass page) => self -> page -> Int -> IO Int
- assistantSetForwardPageFunc :: AssistantClass self => self -> Maybe (Int -> IO Int) -> IO ()
- assistantAddActionWidget :: (AssistantClass self, WidgetClass child) => self -> child -> IO ()
- assistantRemoveActionWidget :: (AssistantClass self, WidgetClass child) => self -> child -> IO ()
- assistantUpdateButtonsState :: AssistantClass self => self -> IO ()
- assistantSetPageType :: (AssistantClass self, WidgetClass page) => self -> page -> AssistantPageType -> IO ()
- assistantGetPageType :: (AssistantClass self, WidgetClass page) => self -> page -> IO AssistantPageType
- assistantSetPageTitle :: (AssistantClass self, WidgetClass page) => self -> page -> String -> IO ()
- assistantGetPageTitle :: (AssistantClass self, WidgetClass page) => self -> page -> IO String
- assistantSetPageHeaderImage :: (AssistantClass self, WidgetClass page) => self -> page -> Pixbuf -> IO ()
- assistantGetPageHeaderImage :: (AssistantClass self, WidgetClass page) => self -> page -> IO (Maybe Pixbuf)
- assistantSetPageSideImage :: (AssistantClass self, WidgetClass page) => self -> page -> Pixbuf -> IO ()
- assistantGetPageSideImage :: (AssistantClass self, WidgetClass page) => self -> page -> IO (Maybe Pixbuf)
- assistantSetPageComplete :: (AssistantClass self, WidgetClass page) => self -> page -> Bool -> IO ()
- assistantGetPageComplete :: (AssistantClass self, WidgetClass page) => self -> page -> IO Bool
- assistantCommit :: AssistantClass self => self -> IO ()
- assistantCurrentPage :: AssistantClass self => Attr self Int
- assistantChildPageType :: AssistantClass self => Attr self AssistantPageType
- assistantChildTitle :: AssistantClass self => Attr self String
- assistantChildHeaderImage :: AssistantClass self => Attr self Pixbuf
- assistantChildSidebarImage :: AssistantClass self => Attr self Pixbuf
- assistantChildComplete :: AssistantClass self => Attr self Bool
- assistantCancel :: AssistantClass self => Signal self (IO ())
- assistantPrepare :: AssistantClass self => Signal self (Widget -> IO ())
- assistantApply :: AssistantClass self => Signal self (IO ())
- assistantClose :: AssistantClass self => Signal self (IO ())

# Detail

A `Assistant` 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.

## GtkAssistant as GtkBuildable

The `Assistant` implementation of the `Buildable` interface exposes the `actionArea` as internal children with the name "action_area".

To add pages to an assistant in `Builder`, simply add it as a <child> to the `Assistant` object, and set its child properties as necessary.

# Class Hierarchy

     | GObject
     | +----Object
     | +----Widget
     | +----Container
     | +----Bin
     | +----Window
     | +----Assistant

# Types

data Assistant

Instances

Eq Assistant |
Ord Assistant |
GObjectClass Assistant |
AssistantClass Assistant |
WindowClass Assistant |
BinClass Assistant |
ContainerClass Assistant |
WidgetClass Assistant |
ObjectClass Assistant |

class WindowClass o => AssistantClass o

Instances

AssistantClass Assistant |

castToAssistant :: GObjectClass obj => obj -> Assistant

toAssistant :: AssistantClass o => o -> Assistant

# Enums.

data AssistantPageType

Constructors

AssistantPageContent |
AssistantPageIntro |
AssistantPageConfirm |
AssistantPageSummary |
AssistantPageProgress |

Instances

Bounded AssistantPageType |
Enum AssistantPageType |
Eq AssistantPageType |
Show AssistantPageType |

# Constructors

assistantNew :: IO Assistant

Creates a new `Assistant`.

- Available since Gtk+ version 2.10

# Methods

assistantGetNPages

Arguments

:: AssistantClass self |
=> self |
-> IO Int | returns The number of pages in the `assistant`.

Returns the number of pages in the `assistant`

- Available since Gtk+ version 2.10

assistantGetNthPage

Arguments

:: AssistantClass self |
=> self |
-> Int | `pageNum` - The index of a page in the `assistant`, or -1 to get the last page;
-> IO (Maybe Widget) | returns The child widget, or `Nothing` if `pageNum` is out of bounds.

Returns the child widget contained in page number `pageNum`.

- Available since Gtk+ version 2.10

assistantPrependPage

Arguments

:: (AssistantClass self, WidgetClass page) |
=> self |
-> page | `page` - a `Widget`
-> IO Int | returns the index (starting at 0) of the inserted page

Prepends a page to the `assistant`.

- Available since Gtk+ version 2.10

assistantAppendPage

Arguments

:: (AssistantClass self, WidgetClass page) |
=> self |
-> page | `page` - a `Widget`
-> IO Int | returns the index (starting at 0) of the inserted page

Appends a page to the `assistant`.

- Available since Gtk+ version 2.10

assistantInsertPage

Arguments

:: (AssistantClass self, WidgetClass page) |
=> self |
-> page | `page` - a `Widget`
-> Int | `position` - the index (starting at 0) at which to insert the page, or -1 to append the page to the `assistant`
-> IO Int | returns the index (starting from 0) of the inserted page

Inserts a page in the `assistant` at a given position.

- Available since Gtk+ version 2.10

assistantSetForwardPageFunc

Arguments

:: AssistantClass self |
=> self |
-> Maybe (Int -> IO Int) | `pageFunc` - the `AssistantPage`, or `Nothing` to use the default one.
-> IO () |

Sets the page forwarding function to be `pageFunc`, this function will be used to determine what will be the next page when the user presses the forward button. Setting `pageFunc` to `Nothing` will make the assistant to use the default forward function, which just goes to the next visible page.

- Available since Gtk+ version 2.10

assistantAddActionWidget

Arguments

:: (AssistantClass self, WidgetClass child) |
=> self |
-> child | `child` - a `Widget`
-> IO () |

Adds a widget to the action area of a `Assistant`.

- Available since Gtk+ version 2.10

assistantRemoveActionWidget

Arguments

:: (AssistantClass self, WidgetClass child) |
=> self |
-> child | `child` - a `Widget`
-> IO () |

Removes a widget from the action area of a `Assistant`.

- Available since Gtk+ version 2.10

assistantUpdateButtonsState :: AssistantClass self => self -> IO ()

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.

- Available since Gtk+ version 2.10

assistantSetPageType

Arguments

:: (AssistantClass self, WidgetClass page) |
=> self |
-> page | `page` - a page of `assistant`
-> AssistantPageType | `type` - the new type for `page`
-> IO () |

Sets the page type for `page`. The page type determines the page behavior in the `assistant`.

- Available since Gtk+ version 2.10

assistantGetPageType

Arguments

:: (AssistantClass self, WidgetClass page) |
=> self |
-> page | `page` - a page of `assistant`
-> IO AssistantPageType | returns the page type of `page`.

Gets the page type of `page`.

- Available since Gtk+ version 2.10

assistantSetPageTitle

Arguments

:: (AssistantClass self, WidgetClass page) |
=> self |
-> page | `page` - a page of `assistant`
-> String | `title` - the new title for `page`
-> IO () |

Sets a title for `page`. The title is displayed in the header area of the assistant when `page` is the current page.

- Available since Gtk+ version 2.10

assistantGetPageTitle

Arguments

:: (AssistantClass self, WidgetClass page) |
=> self |
-> page | `page` - a page of `assistant`
-> IO String | returns the title for `page`.

Gets the title for `page`.

- Available since Gtk+ version 2.10

assistantSetPageHeaderImage

Arguments

:: (AssistantClass self, WidgetClass page) |
=> self |
-> page | `page` - a page of `assistant`
-> Pixbuf | `pixbuf` - the new header image `page`
-> IO () |

Sets a header image for `page`. This image is displayed in the header area of the assistant when `page` is the current page.

- Available since Gtk+ version 2.10

assistantGetPageHeaderImage

Arguments

:: (AssistantClass self, WidgetClass page) |
=> self |
-> page | `page` - a page of `assistant`
-> IO (Maybe Pixbuf) | returns the header image for `page`, or `Nothing` if there's no header image for the page.

Gets the header image for `page`.

- Available since Gtk+ version 2.10

assistantSetPageSideImage

Arguments

:: (AssistantClass self, WidgetClass page) |
=> self |
-> page | `page` - a page of `assistant`
-> Pixbuf | `pixbuf` - the new header image `page`
-> IO () |

Sets a header image for `page`. This image is displayed in the side area of the assistant when `page` is the current page.

- Available since Gtk+ version 2.10

assistantGetPageSideImage

Arguments

:: (AssistantClass self, WidgetClass page) |
=> self |
-> page | `page` - a page of `assistant`
-> IO (Maybe Pixbuf) | returns the side image for `page`, or `Nothing` if there's no side image for the page.

Gets the header image for `page`.

- Available since Gtk+ version 2.10

assistantSetPageComplete

Arguments

:: (AssistantClass self, WidgetClass page) |
=> self |
-> page | `page` - a page of `assistant`
-> Bool | `complete` - the completeness status of the page
-> IO () |

Sets whether `page` contents are complete. This will make `assistant` update the buttons state to be able to continue the task.

- Available since Gtk+ version 2.10

assistantGetPageComplete

Arguments

:: (AssistantClass self, WidgetClass page) |
=> self |
-> page | `page` - a page of `assistant`
-> IO Bool | returns `True` if `page` is complete.

Gets whether `page` is complete.

- Available since Gtk+ version 2.10

assistantCommit :: AssistantClass self => self -> IO ()

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.

- Available since Gtk+ version 2.22

# Attributes

assistantCurrentPage :: AssistantClass self => Attr self Int

Switches the page to `pageNum`. Note that this will only be necessary in custom buttons, as the `assistant` flow can be set with `assistantSetForwardPageFunc`.

Returns the page number of the current page

- Available since Gtk+ version 2.10

# Child Attributes

assistantChildPageType :: AssistantClass self => Attr self AssistantPageType

The type of the assistant page.

Default value: `AssistantPageContent`

- Available since Gtk+ version 2.10

assistantChildTitle :: AssistantClass self => Attr self String

The title that is displayed in the page header.

If title and header-image are both, no header is displayed.

- Available since Gtk+ version 2.10

assistantChildHeaderImage :: AssistantClass self => Attr self Pixbuf

The image that is displayed next to the page.

- Available since Gtk+ version 2.10

assistantChildSidebarImage :: AssistantClass self => Attr self Pixbuf

Sidebar image for the assistant page.

- Available since Gtk+ version 2.10

assistantChildComplete :: AssistantClass self => Attr self Bool

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`

- Available since Gtk+ version 2.10

# Signals

assistantCancel :: AssistantClass self => Signal self (IO ())

The ::assistantCancel signal is emitted when then the assistantCancel button is clicked.

- Available since Gtk+ version 2.10

assistantPrepare :: AssistantClass self => Signal self (Widget -> IO ())

The ::assistantPrepare 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`.

- Available since Gtk+ version 2.10

assistantApply :: AssistantClass self => Signal self (IO ())

The ::assistantApply signal is emitted when the assistantApply button is clicked. The default behavior of the `Assistant` is to switch to the page after the current page, unless the current page is the last one.

A handler for the ::assistantApply 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 `AssistantPageProgress` after the confirmation page and handle this operation within the `assistantPrepare` signal of the progress page.

- Available since Gtk+ version 2.10

assistantClose :: AssistantClass self => Signal self (IO ())

The ::assistantClose signal is emitted either when the assistantClose button of a summary page is clicked, or when the apply button in the last page in the flow (of type `AssistantPageConfirm`) is clicked.