uic.widgets
Class UICWizard

java.lang.Object
  java.awt.Component
      java.awt.Container
          javax.swing.JComponent
              javax.swing.JPanel
                  uic.widgets.UICWizard

All Implemented Interfaces:

ImageObserver, MenuContainer, Serializable, Accessible

public class UICWizard
extends JPanel

The UICWizard class provides a framework for wizard dialogs. A wizard is a special type of input dialog that consists of a sequence of dialog pages. A wizard's purpose is to walk the user through a process step by step. Wizards are useful for complex or infrequently occurring tasks that people may find difficult to learn or do. UICWizard provides page titles and displays Next, Back, Finish, Cancel buttons, depending on the current position in the page sequence.

Extend or simply populate the wizard by adding pages using addPage and insertPage.

You can adjust the page sequence by setting unwanted pages to not appropriate using the setAppropriate method.

Disallowing the next button to be pressed on certain pages can be done by setting the page to be not verified, which can be done by calling the setVerified method.

The actual starting, or showing, of the Wizard is done via the showWizard method.

It is generally considered good design to provide a greater number of simple pages with fewer choices rather than a smaller number of complex pages

Since:

1.2

See Also:

Serialized Form

Nested Class Summary

Nested classes/interfaces inherited from class javax.swing.JPanel

JPanel.AccessibleJPanel

Nested classes/interfaces inherited from class javax.swing.JComponent

JComponent.AccessibleJComponent

Nested classes/interfaces inherited from class java.awt.Container

Container.AccessibleAWTContainer

Nested classes/interfaces inherited from class java.awt.Component

Component.AccessibleAWTComponent, Component.BltBufferStrategy, Component.FlipBufferStrategy

Field Summary

Fields inherited from class javax.swing.JComponent

accessibleContext, listenerList, TOOL_TIP_TEXT_KEY, ui, UNDEFINED_CONDITION, WHEN_ANCESTOR_OF_FOCUSED_COMPONENT, WHEN_FOCUSED, WHEN_IN_FOCUSED_WINDOW

Fields inherited from class java.awt.Component

BOTTOM_ALIGNMENT, CENTER_ALIGNMENT, LEFT_ALIGNMENT, RIGHT_ALIGNMENT, TOP_ALIGNMENT

Fields inherited from interface java.awt.image.ImageObserver

ABORT, ALLBITS, ERROR, FRAMEBITS, HEIGHT, PROPERTIES, SOMEBITS, WIDTH

Constructor Summary

UICWizard()
Sole constructor creates an empty wizard

Method Summary

void	addPage(JComponent page) Add a page to the end of the list of pages.
protected void	buttonNextPressedSlot() a slot which is called by the button
protected void	buttonPrevPressedSlot() a slot which is called by the button
protected void	enteringPage(JComponent to, boolean usingNext) Called when entering a page.
JComponent	getCurrentPage() Return the currently showing page.
JComponent	getPage(int index)
void	insertPage(JComponent page, int index) Insert a page somewhere in the list.
boolean	isAppropriate(JComponent page) A page will only be shown when it is appropriate.
boolean	isVerified(JComponent page)
protected void	leavingPage(JComponent from, boolean usingNext) Called when leaving a page.
protected void	leavingWizard(boolean successfull) Called when leaving the wizard.
void	removePage(JComponent page) Remove a page from the list of pages.
void	setAppropriate(JComponent page, boolean appropriate) A page will only be shown when it is appropriate.
void	setVerified(JComponent page, boolean verified) Alter the next button being enabled at the argument page.
boolean	showWizard(Window parent, String title, boolean modal) Open a new dialog with the first appropriate page being shown.
boolean	showWizard(Window parent, String title, boolean modal, Dimension sizeHint) Open a new dialog with the first appropriate page being shown.
TranslationInterface	translate() The translator that translates texts into foreign languages.

Methods inherited from class javax.swing.JPanel

getAccessibleContext, getUI, getUIClassID, paramString, setUI, updateUI

Methods inherited from class javax.swing.JComponent

addAncestorListener, addNotify, addVetoableChangeListener, computeVisibleRect, contains, createToolTip, disable, enable, firePropertyChange, firePropertyChange, firePropertyChange, fireVetoableChange, getActionForKeyStroke, getActionMap, getAlignmentX, getAlignmentY, getAncestorListeners, getAutoscrolls, getBorder, getBounds, getClientProperty, getComponentGraphics, getComponentPopupMenu, getConditionForKeyStroke, getDebugGraphicsOptions, getDefaultLocale, getFontMetrics, getGraphics, getHeight, getInheritsPopupMenu, getInputMap, getInputMap, getInputVerifier, getInsets, getInsets, getListeners, getLocation, getMaximumSize, getMinimumSize, getNextFocusableComponent, getPopupLocation, getPreferredSize, getRegisteredKeyStrokes, getRootPane, getSize, getToolTipLocation, getToolTipText, getToolTipText, getTopLevelAncestor, getTransferHandler, getVerifyInputWhenFocusTarget, getVetoableChangeListeners, getVisibleRect, getWidth, getX, getY, grabFocus, isDoubleBuffered, isLightweightComponent, isManagingFocus, isOpaque, isOptimizedDrawingEnabled, isPaintingTile, isRequestFocusEnabled, isValidateRoot, paint, paintBorder, paintChildren, paintComponent, paintImmediately, paintImmediately, print, printAll, printBorder, printChildren, printComponent, processComponentKeyEvent, processKeyBinding, processKeyEvent, processMouseEvent, processMouseMotionEvent, putClientProperty, registerKeyboardAction, registerKeyboardAction, removeAncestorListener, removeNotify, removeVetoableChangeListener, repaint, repaint, requestDefaultFocus, requestFocus, requestFocus, requestFocusInWindow, requestFocusInWindow, resetKeyboardActions, reshape, revalidate, scrollRectToVisible, setActionMap, setAlignmentX, setAlignmentY, setAutoscrolls, setBackground, setBorder, setComponentPopupMenu, setDebugGraphicsOptions, setDefaultLocale, setDoubleBuffered, setEnabled, setFocusTraversalKeys, setFont, setForeground, setInheritsPopupMenu, setInputMap, setInputVerifier, setMaximumSize, setMinimumSize, setNextFocusableComponent, setOpaque, setPreferredSize, setRequestFocusEnabled, setToolTipText, setTransferHandler, setUI, setVerifyInputWhenFocusTarget, setVisible, unregisterKeyboardAction, update

Methods inherited from class java.awt.Container

add, add, add, add, add, addContainerListener, addImpl, addPropertyChangeListener, addPropertyChangeListener, applyComponentOrientation, areFocusTraversalKeysSet, countComponents, deliverEvent, doLayout, findComponentAt, findComponentAt, getComponent, getComponentAt, getComponentAt, getComponentCount, getComponents, getComponentZOrder, getContainerListeners, getFocusTraversalKeys, getFocusTraversalPolicy, getLayout, getMousePosition, insets, invalidate, isAncestorOf, isFocusCycleRoot, isFocusCycleRoot, isFocusTraversalPolicyProvider, isFocusTraversalPolicySet, layout, list, list, locate, minimumSize, paintComponents, preferredSize, printComponents, processContainerEvent, processEvent, remove, remove, removeAll, removeContainerListener, setComponentZOrder, setFocusCycleRoot, setFocusTraversalPolicy, setFocusTraversalPolicyProvider, setLayout, transferFocusBackward, transferFocusDownCycle, validate, validateTree

Methods inherited from class java.awt.Component

action, add, addComponentListener, addFocusListener, addHierarchyBoundsListener, addHierarchyListener, addInputMethodListener, addKeyListener, addMouseListener, addMouseMotionListener, addMouseWheelListener, bounds, checkImage, checkImage, coalesceEvents, contains, createImage, createImage, createVolatileImage, createVolatileImage, disableEvents, dispatchEvent, enable, enableEvents, enableInputMethods, firePropertyChange, firePropertyChange, firePropertyChange, firePropertyChange, firePropertyChange, firePropertyChange, getBackground, getBounds, getColorModel, getComponentListeners, getComponentOrientation, getCursor, getDropTarget, getFocusCycleRootAncestor, getFocusListeners, getFocusTraversalKeysEnabled, getFont, getForeground, getGraphicsConfiguration, getHierarchyBoundsListeners, getHierarchyListeners, getIgnoreRepaint, getInputContext, getInputMethodListeners, getInputMethodRequests, getKeyListeners, getLocale, getLocation, getLocationOnScreen, getMouseListeners, getMouseMotionListeners, getMousePosition, getMouseWheelListeners, getName, getParent, getPeer, getPropertyChangeListeners, getPropertyChangeListeners, getSize, getToolkit, getTreeLock, gotFocus, handleEvent, hasFocus, hide, imageUpdate, inside, isBackgroundSet, isCursorSet, isDisplayable, isEnabled, isFocusable, isFocusOwner, isFocusTraversable, isFontSet, isForegroundSet, isLightweight, isMaximumSizeSet, isMinimumSizeSet, isPreferredSizeSet, isShowing, isValid, isVisible, keyDown, keyUp, list, list, list, location, lostFocus, mouseDown, mouseDrag, mouseEnter, mouseExit, mouseMove, mouseUp, move, nextFocus, paintAll, postEvent, prepareImage, prepareImage, processComponentEvent, processFocusEvent, processHierarchyBoundsEvent, processHierarchyEvent, processInputMethodEvent, processMouseWheelEvent, remove, removeComponentListener, removeFocusListener, removeHierarchyBoundsListener, removeHierarchyListener, removeInputMethodListener, removeKeyListener, removeMouseListener, removeMouseMotionListener, removeMouseWheelListener, removePropertyChangeListener, removePropertyChangeListener, repaint, repaint, repaint, resize, resize, setBounds, setBounds, setComponentOrientation, setCursor, setDropTarget, setFocusable, setFocusTraversalKeysEnabled, setIgnoreRepaint, setLocale, setLocation, setLocation, setName, setSize, setSize, show, show, size, toString, transferFocus, transferFocusUpCycle

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Constructor Detail

UICWizard

public UICWizard()

Sole constructor creates an empty wizard

Method Detail

enteringPage

protected void enteringPage(JComponent to,
                            boolean usingNext)

Called when entering a page.

Parameters:

to - the page that is about to be entered.

usingNext - this is true when we come from a page lower in the pages-sequence rather then higher.

leavingPage

protected void leavingPage(JComponent from,
                           boolean usingNext)

Called when leaving a page.

Parameters:

from - the page we are leaving.

usingNext - this is true when we come from a page lower in the pages-sequence rather then higher.

leavingWizard

protected void leavingWizard(boolean successfull)

Called when leaving the wizard. The specified boolean indicates whether the wizard is left on cancel or finish.

Parameters:

successfull - true if the wizard is left on finish, false otherwise

addPage

public void addPage(JComponent page)

Add a page to the end of the list of pages.

Parameters:

page - the component that represents a page; notice that the page title is fetched from the name of the page.

See Also:

Component.setName(String)

insertPage

public void insertPage(JComponent page,
                       int index)
                throws IndexOutOfBoundsException

Insert a page somewhere in the list.

Parameters:

page - the new page; notice that the page title is fetched from the name of the page.

index - a 1-based index in the page sequence. On -1 the page will be added at the end.

Throws:

IndexOutOfBoundsException - when index falls outside of the current set.

removePage

public void removePage(JComponent page)

Remove a page from the list of pages. when a page is not found; this method will return silently.

Parameters:

page - the old page

getCurrentPage

public JComponent getCurrentPage()

Return the currently showing page.

Returns:

the currently showing page, or null when no page is being shown.

isAppropriate

public boolean isAppropriate(JComponent page)

A page will only be shown when it is appropriate. Find out if a certain page will be shown or skipped when the next or prev button is pressed that would make the argument page the current page.

Parameters:

page - a page previously added or inserted.

Returns:

wheater the page will be shown

setAppropriate

public void setAppropriate(JComponent page,
                           boolean appropriate)

A page will only be shown when it is appropriate. Set a certain page to be shown or skipped when the next or prev button is pressed that would make the argument page the current page.

Parameters:

page - a page previously added or inserted.

appropriate - true means that page will be shown

getPage

public JComponent getPage(int index)

Returns:

the page at index, or null when no page could be found.

setVerified

public void setVerified(JComponent page,
                        boolean verified)

Alter the next button being enabled at the argument page. While a panel is not verified the next button is not enabled. The panels are all verified when added by default.

Parameters:

page - the page to set to verified

verified - value for panel verification.

isVerified

public boolean isVerified(JComponent page)

buttonPrevPressedSlot

protected void buttonPrevPressedSlot()

a slot which is called by the button

buttonNextPressedSlot

protected void buttonNextPressedSlot()

a slot which is called by the button

showWizard

public boolean showWizard(Window parent,
                          String title,
                          boolean modal)

Open a new dialog with the first appropriate page being shown.

Call this method to launch the wizard in its own window and return only after the wizard has finished (i.e. the dialog has been closed).

Notice that since this method will not immidiately return it is unwise to start it in the EventDispatch Thread. The EventDispatch thread is used when you call this method from code that is initiated from user-inter action. Button presses are a good example. In the case of a modal dialog the problem will be solved by AWT internals, in other cases you must create a new thread which will show this wizard.

An example call for a non-modal dialog (a non-modal dialog should be used in all but the most extreme cases)

          if(myWizard.showWizard(null, "myWizard", false)) {
              // get data from wizard and do something with it.
              newAssignment(myWizard.getAssignment());
          }
  

In the case you call the showWizard from a buttonPress or other GUI action you have to do a little extra; here is some example code:

      final UICWizard daWizard = myWizard;
      Thread handling = new Thread("WizardHandler") {
          public void run() {
              if(! daWizard.showWizard(null, "myWizard", false))
                  return; // was cancelled
              // after we return we get all the info from the wizard, for example
              // by calling a custom method on myWizard that extends from UICWizard
              newAssignment(myWizard.getAssignment());
          }
      };
      handling.start();
  

Parameters:

parent - the parent Window that the new dialog will beloing to.

title - the string that will be used as the title of the new dialog.

modal - true means the parent window will be locked as long as the wizard is open.

Returns:

success of the Wizard. Will return true when the finished button has been pressed.

Throws:

IllegalStateException - since this method will not return until the wizard has been closed we can not be non-modal (modal = false) and be called from the EventDispatch Thread.

showWizard

public boolean showWizard(Window parent,
                          String title,
                          boolean modal,
                          Dimension sizeHint)

Open a new dialog with the first appropriate page being shown.

Parameters:

parent - the parent Window that the new dialog will beloing to.

title - the string that will be used as the title of the new dialog.

modal - true means the parent window will be locked as long as the wizard is open.

sizeHint - A size hint for the Wizard. This will be used as a preferred size.

Returns:

success of the Wizard. Will return true when the finished button has been pressed.

Throws:

IllegalStateException - since this method will not return until the wizard has been closed we can not be non-modal (modal = false) and be called from the EventDispatch Thread.

See Also:

showWizard(Window,String,boolean)

translate

public TranslationInterface translate()

The translator that translates texts into foreign languages.

See Also:

Translate