org.gnome.gtk

## Class Assistant

- Object
- - org.freedesktop.bindings.Pointer
  - - org.freedesktop.bindings.Proxy
    - - org.gnome.glib.Object
      - - org.gnome.gtk.Widget
        - - org.gnome.gtk.Container
          - - org.gnome.gtk.Bin
            - - org.gnome.gtk.Window
              - - org.gnome.gtk.Assistant

-     public class Assistant
      extends Window

  Guide a user through a multi-step operation one page at a time. You may recognize the name "wizard" or "druid"; GTK calls these Assistants.

  An Assistant contains of multiple pages. While each page is just a Widget of your choice, in most cases you will use a layout container as you would in creating a regular top level Window. Each page in the Assistant is marked as a specific type, set with `setPageType()`. Be aware that the last page of the Assistant must be of type `CONFIRM` or `SUMMARY`.

  You can hook to a number of signals which indicate user actions specific to the Assistant:

  - `Assistant.Apply` - The user activated the 'Apply' button on the page.
  - `Assistant.Cancel` - The user cancelled the Assistant.
  - `Assistant.Close` - The Assistant closes normally.
  - `Assistant.Prepare` - Another page is going to be displayed

  Listening to the `Assistant.Prepare` signal allows you to modify the page contents in time, perhaps depending on input made on previous pages.

  You create the Assistant with a number of pages with most of them being of type CONTENT. To allow a user to go from one page to the next, the page must be flagged as complete. The 'Next' button will remain disabled until this property is set for that page. The definition of "complete" will necessarily depend on what you are doing on a given page, but typically you hook up to signals emitted from the Widgets inside the page and when contents have changed call `setPageComplete(true)`.

  Since:
    4.0.9
  Author:
    Stefan Prelle, Andrew Cowie, Guillaume Mazoyer

- - ### Nested Class Summary

    Nested Classes
    Modifier and Type | Class and Description
    --- | ---
    `static interface` | `Assistant.Apply` The signal emitted when the user is on a `CONFIRM` page and confirms the input they have given.
    `static interface` | `Assistant.Cancel` The signal emitted if the user cancels the Assistant.
    `static interface` | `Assistant.Close` This signal emitted at the end of the Assistant's life cycle.
    `static interface` | `Assistant.ForwardPage` The callback invoked when an Assistant wants to display another page.
    `static interface` | `Assistant.Prepare` The signal emitted every time a page inside the assistant is displayed.

    - ### Nested classes/interfaces inherited from class org.gnome.gtk.Window

      `Window.ConfigureEvent, Window.DeleteEvent`

    - ### Nested classes/interfaces inherited from class org.gnome.gtk.Widget

      `Widget.ButtonPressEvent, Widget.ButtonReleaseEvent, Widget.Destroy, Widget.Draw, Widget.EnterNotifyEvent, Widget.FocusInEvent, Widget.FocusOutEvent, Widget.Hide, Widget.KeyPressEvent, Widget.KeyReleaseEvent, Widget.LeaveNotifyEvent, Widget.MapEvent, Widget.MotionNotifyEvent, Widget.PopupMenu, Widget.ScrollEvent, Widget.SizeAllocate, Widget.UnmapEvent, Widget.VisibilityNotifyEvent`

  - ### Constructor Summary

    Constructors
    Constructor and Description
    `Assistant()` Creates a new instance of the Assistant.

  - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `void` | `addActionWidget(Widget child)` Adds a widget to the action area of a Assistant.
    `int` | `appendPage(Widget page)` Appends a page to the pages in the Assistant.
    `void` | `connect(Assistant.Apply handler)` Hook up an `Assistant.Apply` handler that will be called when the user chooses to confirm their selections.
    `void` | `connect(Assistant.Cancel handler)` Hook up an `Assistant.Cancel` handler will be called when the Assistant is cancelled.
    `void` | `connect(Assistant.Close handler)` Attach a `Assistant.Close` handler that will be called when the Assistant is closed normally at a `CONFIRM` or `SUMMARY` page.
    `void` | `connect(Assistant.Prepare handler)` Hook up an `Assistant.Prepare` handler that is called when a new page is displayed.
    `int` | `emitForwardPage(int currentPage)` Force the Assistant.ForwardPage signal to be emitted.
    `int` | `getCurrentPage()` Get the page number of the currently displayed page.
    `int` | `getNumPages()` Get the number of pages in the Assistant.
    `Widget` | `getPage(int pageNum)` Returns the child Widget contained in the given page.
    `boolean` | `getPageComplete(Widget page)` Gets whether page is complete.
    `Pixbuf` | `getPageHeaderImage(Widget page)` Gets the header image for page.
    `Pixbuf` | `getPageSideImage(Widget page)` Gets the side image for page.
    `String` | `getPageTitle(Widget page)` Obtains the title that has been set for a specific page.
    `AssistantPageType` | `getPageType(Widget page)` Get the type of the given Assistant page.
    `int` | `insertPage(Widget page, int position)` Places a page at a specific position between the pages already existing in the Assistant.
    `int` | `prependPage(Widget page)` Prepend `page` to the existing pages in the Assistant.
    `void` | `removeActionWidget(Widget child)` Removes a Widget that has been added with `addActionWidget(Widget)`.
    `void` | `setCurrentPage(int pageNum)` Select the page to be displayed to the user.
    `void` | `setForwardPageCallback(Assistant.ForwardPage callback)` Hookup the `Assistant.ForwardPage` callback that will be used to determine what page should be displayed when `[Forward]` is pressed.
    `void` | `setPageComplete(Widget page, boolean complete)` Sets whether page contents are complete.
    `void` | `setPageHeaderImage(Widget page, Pixbuf image)` Sets a header image for page.
    `void` | `setPageSideImage(Widget page, Pixbuf image)` Sets a side image for page.
    `void` | `setPageTitle(Widget page, String title)` Sets the title for a given page.
    `void` | `setPageType(Widget page, AssistantPageType type)` Sets the page-type for the given page.
    `void` | `show()` Cause this Widget to be mapped to the screen.
    `void` | `showAll()` Cause this Widget, and any Widgets it contains, to be mapped to the screen.
    `void` | `updateButtonsState()` Force the Assistant to recompute the buttons state.

    - ### Methods inherited from class org.gnome.gtk.Window

      `addAcceleratorGroup, connect, connect, getHeight, getMaximized, getPositionX, getPositionY, getScreen, getWidth, move, present, resize, setDecorated, setDefaultSize, setFullscreen, setGravity, setHasResizeGrip, setIcon, setIcon, setKeepAbove, setKeepBelow, setMaximize, setModal, setPosition, setResizable, setSkipPagerHint, setSkipTaskbarHint, setStick, setTitle, setTransientFor, setTypeHint`

    - ### Methods inherited from class org.gnome.gtk.Bin

      `getChild`

    - ### Methods inherited from class org.gnome.gtk.Container

      `add, getChildren, remove, setBorderWidth`

    - ### Methods inherited from class org.gnome.gtk.Widget

      `activate, addEvents, connect, connect, connect, connect, connect, connect, connect, connect, connect, connect, connect, connect, connect, connect, connect, connect, connect, connect, destroy, getAllocatedHeight, getAllocatedWidth, getAllocation, getCanDefault, getCanFocus, getHasFocus, getName, getParent, getPreferredHeightForWidthMinimum, getPreferredHeightForWidthNatural, getPreferredHeightMinimum, getPreferredHeightNatural, getPreferredWidthForHeightMinimum, getPreferredWidthForHeightNatural, getPreferredWidthMinimum, getPreferredWidthNatural, getRequestMode, getRequisition, getSensitive, getStyleContext, getToplevel, getWindow, grabAdd, grabDefault, grabFocus, grabRemove, hide, isSensitive, overrideBackground, overrideColor, overrideFont, queueDraw, queueDrawArea, realize, setAlignHorizontal, setAlignVertical, setCanDefault, setCanFocus, setEvents, setExpandHorizontal, setExpandVertical, setName, setSensitive, setSizeRequest, setTooltipMarkup, setTooltipText`

    - ### Methods inherited from class org.freedesktop.bindings.Pointer

      `toString`

    - ### Methods inherited from class Object

      `equals, getClass, hashCode, notify, notifyAll, wait, wait, wait`

- - ### Constructor Detail

    - #### Assistant

          public Assistant()

      Creates a new instance of the Assistant.
      Since:
        4.0.9

  - ### Method Detail

    - #### addActionWidget

          public void addActionWidget(Widget child)

      Adds a widget to the action area of a Assistant.
      Since:
        4.0.9

    - #### appendPage

          public int appendPage(Widget page)

      Appends a page to the pages in the Assistant.
      Parameters:
        `page` - Page to add.
      Returns:
        the index (starting at 0) of the inserted page
      Since:
        4.0.9

    - #### connect

          public void connect(Assistant.Apply handler)

      Hook up an `Assistant.Apply` handler that will be called when the user chooses to confirm their selections.
      Since:
        4.0.9

    - #### connect

          public void connect(Assistant.Cancel handler)

      Hook up an `Assistant.Cancel` handler will be called when the Assistant is cancelled.
      Since:
        4.0.9

    - #### connect

          public void connect(Assistant.Close handler)

      Attach a `Assistant.Close` handler that will be called when the Assistant is closed normally at a `CONFIRM` or `SUMMARY` page.
      Since:
        4.0.9

    - #### connect

          public void connect(Assistant.Prepare handler)

      Hook up an `Assistant.Prepare` handler that is called when a new page is displayed.
      Since:
        4.0.9

    - #### emitForwardPage

          public int emitForwardPage(int currentPage)

      Force the Assistant.ForwardPage signal to be emitted.
      Since:
        4.0.17

    - #### getCurrentPage

          public int getCurrentPage()

      Get the page number of the currently displayed page. Page numbers count from `0`. If the assistant has no pages, `-1` will be returned.
      Since:
        4.0.9

    - #### getNumPages

          public int getNumPages()

      Get the number of pages in the Assistant.
      Since:
        4.0.9

    - #### getPage

          public Widget getPage(int pageNum)

      Returns the child Widget contained in the given page.
      Parameters:
        `pageNum` - The index of a page in the assistant. Use `-1` to get the last page.
      Since:
        4.0.9

    - #### getPageComplete

          public boolean getPageComplete(Widget page)

      Gets whether page is complete.
      Since:
        4.0.9

    - #### getPageHeaderImage

          public Pixbuf getPageHeaderImage(Widget page)

      Gets the header image for page.
      Since:
        4.0.9

    - #### getPageSideImage

          public Pixbuf getPageSideImage(Widget page)

      Gets the side image for page.
      Since:
        4.0.9

    - #### getPageTitle

          public String getPageTitle(Widget page)

      Obtains the title that has been set for a specific page.
      Since:
        4.0.9

    - #### getPageType

          public AssistantPageType getPageType(Widget page)

      Get the type of the given Assistant page.
      Since:
        4.0.9

    - #### insertPage

          public int insertPage(Widget page,
                       int position)

      Places a page at a specific position between the pages already existing in the Assistant.
      Parameters:
        `page` - Page to add.
        `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 at `0`) of the inserted page.
      Since:
        4.0.9

    - #### prependPage

          public int prependPage(Widget page)

      Prepend `page` to the existing pages in the Assistant.
      Returns:
        the index (starting at 0) of the inserted page.
      Since:
        4.0.9

    - #### removeActionWidget

          public void removeActionWidget(Widget child)

      Removes a Widget that has been added with `addActionWidget(Widget)`.
      Since:
        4.0.9

    - #### setCurrentPage

          public void setCurrentPage(int pageNum)

      Select the page to be displayed to the user.
      Since:
        4.0.9

    - #### setForwardPageCallback

          public void setForwardPageCallback(Assistant.ForwardPage callback)

      Hookup the `Assistant.ForwardPage` callback that will be used to determine what page should be displayed when `[Forward]` is pressed.
      Since:
        4.0.17

    - #### setPageComplete

          public void setPageComplete(Widget page,
                             boolean complete)

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

    - #### setPageHeaderImage

          public void setPageHeaderImage(Widget page,
                                Pixbuf image)

      Sets a header image for page. This image is displayed in the header area of the Assistant when `page` is the current page.
      Parameters:
        `page` - A page of assistant
        `image` - the new header image
      Since:
        4.0.9

    - #### setPageSideImage

          public void setPageSideImage(Widget page,
                              Pixbuf image)

      Sets a side image for page. This image is displayed in the side area of the assistant when `page` is the current page.
      Parameters:
        `page` - A page of assistant
        `image` - the new side image
      Since:
        4.0.9

    - #### setPageTitle

          public void setPageTitle(Widget page,
                          String title)

      Sets the title for a given page. The title is displayed in the header area of the Assistant when page is the current page.
      Since:
        4.0.9

    - #### setPageType

          public void setPageType(Widget page,
                         AssistantPageType type)

      Sets the page-type for the given page. This determines the page's behaviour in the Assistant; see `AssistantPageType`.
      Since:
        4.0.9

    - #### show

          public void show()

      Description copied from class: `Widget`
      Cause this Widget to be mapped to the screen. Flags a widget to be displayed. Any widget that isn't shown will not appear on the screen.

      There are a bunch of quirks you need to be aware of:

      - You have to show the Containers containing a Widget, in addition to the Widget itself, before it will appear on the display.
      - When a toplevel Container is shown (ie, your `Window` ), it is immediately realized and mapped, and any Widgets within it that are shown are then realized and mapped.
      - You can't get information about the actual size that has been allocated to a Widget until it gets mapped to the screen.

      If you want to show all the widgets in a container, it's actually much easier to just call `Widget.showAll()` on the container, rather than calling show manually one each individual Widget you've added to it.

      Overrides:
        `show` in class `Widget`

    - #### showAll

          public void showAll()

      Description copied from class: `Widget`
      Cause this Widget, and any Widgets it contains, to be mapped to the screen. You typically call this on a `Window` after you've finished all the work necessary to set it up.

      Quite frequently you also want to cause a Window to appear on the screen as well (ie, not be buried under a whole bunch of other applications' Windows), so calling Window's `present()` is usually next.

      Don't be surprised if this takes a few hundred milliseconds. Realizing and mapping all the zillion elements that ultimately make up a Window is one of the most resource intensive operations that GTK, GDK, Pango, your X server, and your kernel have to churn through. Sometimes, you just gotta wait.

      Overrides:
        `showAll` in class `Widget`

    - #### updateButtonsState

          public void updateButtonsState()

      Force the Assistant to recompute the buttons state. In most case, this method is not useful since GTK+ automatically takes care of this. But it might be necessary in some situations when changing a value on the current page.
      Since:
        4.0.9