java-gnome version 4.0.15

org.gnome.gtk
Class Assistant

Object
  extended by org.freedesktop.bindings.Pointer
      extended by org.freedesktop.bindings.Proxy
          extended by org.gnome.glib.Object
              extended by org.gnome.gtk.Object
                  extended by org.gnome.gtk.Widget
                      extended by org.gnome.gtk.Container
                          extended by org.gnome.gtk.Bin
                              extended by org.gnome.gtk.Window
                                  extended by 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:

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

Nested Class Summary
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.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.EnterNotifyEvent, Widget.ExposeEvent, Widget.FocusInEvent, Widget.FocusOutEvent, Widget.Hide, Widget.KeyPressEvent, Widget.KeyReleaseEvent, Widget.LeaveNotifyEvent, Widget.MapEvent, Widget.MotionNotifyEvent, Widget.PopupMenu, Widget.ScrollEvent, Widget.UnmapEvent, Widget.VisibilityNotifyEvent
 
Constructor Summary
Assistant()
          Creates a new instance of the Assistant.
 
Method Summary
 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 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 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 ...
 
Methods inherited from class org.gnome.gtk.Window
connect, connect, getHeight, getMaximized, getPositionX, getPositionY, getScreen, getWidth, move, present, resize, setDecorated, setDefaultSize, setFullscreen, setGravity, 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, getAllocation, getCanDefault, getCanFocus, getHasFocus, getName, getParent, getRequisition, getToplevel, getWindow, grabAdd, grabDefault, grabFocus, grabRemove, hide, modifyBackground, modifyBase, modifyFont, modifyText, queueDraw, queueDrawArea, setCanDefault, setCanFocus, setColormap, setEvents, 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

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

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:

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 ... FIXME

Since:
4.0.9


java-gnome