org.peace_tools.generic
Class WizardDialog

java.lang.Object
  java.awt.Component
      java.awt.Container
          java.awt.Window
              java.awt.Dialog
                  javax.swing.JDialog
                      org.peace_tools.generic.WizardDialog

All Implemented Interfaces:

java.awt.event.ActionListener, java.awt.image.ImageObserver, java.awt.MenuContainer, java.io.Serializable, java.util.EventListener, javax.accessibility.Accessible, javax.swing.RootPaneContainer, javax.swing.WindowConstants

Direct Known Subclasses:

DataSetWizard, JobWizard, ServerWizard

public class WizardDialog
extends javax.swing.JDialog
implements java.awt.event.ActionListener

A extended wizard dialog class. This class extends the features of a standard JDialog class and provides some custom graphics and capabilities to develop a Wizard. A wizard is essentially a series of dialogs that guide the user through a sequence of steps that are needed to accomplish a specific task. The specific features of this class include:

• Ability to add one or more WizardPanel objects in a specific sequence to the pagePanel of this wizard dialog class. The page panel has a CardLayout manager that displays only one WizardPanel at a time. The WizardPanel objects are displayed in the order in which they are present in the content pane.
• A custom title image that is displayed as the header for this wizard dialog.
• A custom column image that is shared/reused by all the wizard pages added to this dialog. This image is displayed on the left hand side of the dialog (below the list of steps in the wizard)
• A custom display of the sequence of steps in this wizard along with indication on which sequence have already been completed.

See Also:

Serialized Form

Nested Class Summary

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

javax.swing.JDialog.AccessibleJDialog

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

java.awt.Dialog.AccessibleAWTDialog, java.awt.Dialog.ModalExclusionType, java.awt.Dialog.ModalityType

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

java.awt.Window.AccessibleAWTWindow

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

java.awt.Container.AccessibleAWTContainer

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

java.awt.Component.AccessibleAWTComponent, java.awt.Component.BaselineResizeBehavior, java.awt.Component.BltBufferStrategy, java.awt.Component.FlipBufferStrategy

Field Summary

private javax.swing.JButton	cancelButton The "Cancel" button that is displayed at the bottom of the wizard in a separate panel.
private int	currentPage The current page that is being displayed by this wizard.
private javax.swing.JButton	finishButton The "Finish" button that is displayed at the bottom of the wizard in a separate panel.
private javax.swing.JButton	helpButton The "Help" button that is displayed at the bottom of the wizard in a separate panel.
private java.lang.String	helpURL The URL to the online help page associated with this wizard.
private javax.swing.JButton	nextButton The "Next" button that is displayed at the bottom of the wizard in a separate panel.
private CustomPanel	pagePanel A custom panel that is used to hold all the pages of this wizard.
private java.util.ArrayList<WizardPage>	pages The array list containing the set of pages to be displayed by this wizard in the same sequence as they are to be displayed.
private javax.swing.JButton	prevButton The "Prev" button that is displayed at the bottom of the wizard in a separate panel.
private javax.swing.JLabel[]	seqTitles The array of sequence titles that are displayed to the left of the wizard dialog.
private CustomPanel	sequencePanel A custom column panel that is displayed to the left of the wizard.
private static long	serialVersionUID Generated serial version ID for serializing this class.
private CustomPanel	titlePanel A custom panel that is used as the title panel for this wizard.
private javax.swing.JLabel[]	titles The array of two titles that are displayed at the top of this wizard dialog.
private java.util.ArrayList<java.lang.Thread>	workerThreads The list of worker threads that various pages may have spawned.

Fields inherited from class javax.swing.JDialog

accessibleContext, rootPane, rootPaneCheckingEnabled

Fields inherited from class java.awt.Dialog

DEFAULT_MODALITY_TYPE

Fields inherited from class java.awt.Component

BOTTOM_ALIGNMENT, CENTER_ALIGNMENT, LEFT_ALIGNMENT, RIGHT_ALIGNMENT, TOP_ALIGNMENT

Fields inherited from interface javax.swing.WindowConstants

DISPOSE_ON_CLOSE, DO_NOTHING_ON_CLOSE, EXIT_ON_CLOSE, HIDE_ON_CLOSE

Fields inherited from interface java.awt.image.ImageObserver

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

Constructor Summary

protected

WizardDialog(java.awt.Frame parent) The constructor.

Method Summary

void	actionPerformed(java.awt.event.ActionEvent event)
void	addPage(WizardPage page) Adds a new wizard page to the list of wizard dialog pages.
void	addThread(java.lang.Thread t) Adds a given worker thread to the wizard.
protected boolean	cancel() Helper method invoked when user clicks cancel button.
void	changePage(int currPage, int nextPage) Helper method to perform the tasks related with page switching.
protected void	checkChangePage(int currPage, int nextPage) Helper method to perform the tasks related with page switching.
protected void	done(boolean success) Helper method invoked once the wizard is done.
int	getCurrentPage() Obtain the index of the current page being displayed in this wizard.
WizardPage	getPage(int index) Obtain wizard page associated with the given index.
CustomPanel	getPagePane() Obtain the page pane to which wizard pages must be added.
protected java.awt.Component	layoutButtons() Helper method to layout the button panel to the bottom of the wizard.
protected void	layoutSequencePanel() Helper method to layout the sequence panel in the wizard.
protected void	layoutTitlePanel() Helper method to layout the title panel in the wizard.
protected void	layoutWizard() This method is called from the showWizard method just before the wizard is made visible.
void	removeThread(java.lang.Thread t) Remove a given worker thread from the list of worker threads.
private void	setButtonStatus() Method to suitably set status of buttons in the wizard.
void	setButtonStatus(int prev, int next, int cancel) Method to enable or disable back and/or next buttons.
void	setSequenceBackground(java.lang.String fileName) Set an image to be used for the sequence panel.
void	setTitleBackground(java.lang.String fileName, java.awt.Color bgColor) Set an image to be used for the title panel.
void	showWizard(java.lang.String helpURL) The main method that lays out the components in this wizard and displays the wizard.
private void	updateSequence(int currPage) Helper method to update the current sequence information and highlight the current step in the wizard.

Methods inherited from class javax.swing.JDialog

addImpl, createRootPane, dialogInit, getAccessibleContext, getContentPane, getDefaultCloseOperation, getGlassPane, getGraphics, getJMenuBar, getLayeredPane, getRootPane, getTransferHandler, isDefaultLookAndFeelDecorated, isRootPaneCheckingEnabled, paramString, processWindowEvent, remove, repaint, setContentPane, setDefaultCloseOperation, setDefaultLookAndFeelDecorated, setGlassPane, setJMenuBar, setLayeredPane, setLayout, setRootPane, setRootPaneCheckingEnabled, setTransferHandler, update

Methods inherited from class java.awt.Dialog

addNotify, getModalityType, getTitle, hide, isModal, isResizable, isUndecorated, setModal, setModalityType, setResizable, setTitle, setUndecorated, setVisible, show, toBack

Methods inherited from class java.awt.Window

addPropertyChangeListener, addPropertyChangeListener, addWindowFocusListener, addWindowListener, addWindowStateListener, applyResourceBundle, applyResourceBundle, createBufferStrategy, createBufferStrategy, dispose, getBufferStrategy, getFocusableWindowState, getFocusCycleRootAncestor, getFocusOwner, getFocusTraversalKeys, getGraphicsConfiguration, getIconImages, getInputContext, getListeners, getLocale, getModalExclusionType, getMostRecentFocusOwner, getOwnedWindows, getOwner, getOwnerlessWindows, getToolkit, getWarningString, getWindowFocusListeners, getWindowListeners, getWindows, getWindowStateListeners, isActive, isAlwaysOnTop, isAlwaysOnTopSupported, isFocusableWindow, isFocusCycleRoot, isFocused, isLocationByPlatform, isShowing, pack, postEvent, processEvent, processWindowFocusEvent, processWindowStateEvent, removeNotify, removeWindowFocusListener, removeWindowListener, removeWindowStateListener, reshape, setAlwaysOnTop, setBounds, setBounds, setCursor, setFocusableWindowState, setFocusCycleRoot, setIconImage, setIconImages, setLocationByPlatform, setLocationRelativeTo, setMinimumSize, setModalExclusionType, setSize, setSize, toFront

Methods inherited from class java.awt.Container

add, add, add, add, add, addContainerListener, applyComponentOrientation, areFocusTraversalKeysSet, countComponents, deliverEvent, doLayout, findComponentAt, findComponentAt, getAlignmentX, getAlignmentY, getComponent, getComponentAt, getComponentAt, getComponentCount, getComponents, getComponentZOrder, getContainerListeners, getFocusTraversalPolicy, getInsets, getLayout, getMaximumSize, getMinimumSize, getMousePosition, getPreferredSize, insets, invalidate, isAncestorOf, isFocusCycleRoot, isFocusTraversalPolicyProvider, isFocusTraversalPolicySet, layout, list, list, locate, minimumSize, paint, paintComponents, preferredSize, print, printComponents, processContainerEvent, remove, removeAll, removeContainerListener, setComponentZOrder, setFocusTraversalKeys, setFocusTraversalPolicy, setFocusTraversalPolicyProvider, setFont, 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, contains, createImage, createImage, createVolatileImage, createVolatileImage, disable, disableEvents, dispatchEvent, enable, enable, enableEvents, enableInputMethods, firePropertyChange, firePropertyChange, firePropertyChange, firePropertyChange, firePropertyChange, firePropertyChange, firePropertyChange, firePropertyChange, firePropertyChange, getBackground, getBaseline, getBaselineResizeBehavior, getBounds, getBounds, getColorModel, getComponentListeners, getComponentOrientation, getCursor, getDropTarget, getFocusListeners, getFocusTraversalKeysEnabled, getFont, getFontMetrics, getForeground, getHeight, getHierarchyBoundsListeners, getHierarchyListeners, getIgnoreRepaint, getInputMethodListeners, getInputMethodRequests, getKeyListeners, getLocation, getLocation, getLocationOnScreen, getMouseListeners, getMouseMotionListeners, getMousePosition, getMouseWheelListeners, getName, getParent, getPeer, getPropertyChangeListeners, getPropertyChangeListeners, getSize, getSize, getTreeLock, getWidth, getX, getY, gotFocus, handleEvent, hasFocus, imageUpdate, inside, isBackgroundSet, isCursorSet, isDisplayable, isDoubleBuffered, isEnabled, isFocusable, isFocusOwner, isFocusTraversable, isFontSet, isForegroundSet, isLightweight, isMaximumSizeSet, isMinimumSizeSet, isOpaque, isPreferredSizeSet, isValid, isVisible, keyDown, keyUp, list, list, list, location, lostFocus, mouseDown, mouseDrag, mouseEnter, mouseExit, mouseMove, mouseUp, move, nextFocus, paintAll, prepareImage, prepareImage, printAll, processComponentEvent, processFocusEvent, processHierarchyBoundsEvent, processHierarchyEvent, processInputMethodEvent, processKeyEvent, processMouseEvent, processMouseMotionEvent, processMouseWheelEvent, remove, removeComponentListener, removeFocusListener, removeHierarchyBoundsListener, removeHierarchyListener, removeInputMethodListener, removeKeyListener, removeMouseListener, removeMouseMotionListener, removeMouseWheelListener, removePropertyChangeListener, removePropertyChangeListener, repaint, repaint, repaint, requestFocus, requestFocus, requestFocusInWindow, requestFocusInWindow, resize, resize, setBackground, setComponentOrientation, setDropTarget, setEnabled, setFocusable, setFocusTraversalKeysEnabled, setForeground, setIgnoreRepaint, setLocale, setLocation, setLocation, setMaximumSize, setName, setPreferredSize, show, size, toString, transferFocus, transferFocusBackward, transferFocusUpCycle

Methods inherited from class java.lang.Object

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

Field Detail

pagePanel

private CustomPanel pagePanel

A custom panel that is used to hold all the pages of this wizard. This panel is added to the center of the wizard and uses a CardLayout to display one wizard page at a time.

titlePanel

private CustomPanel titlePanel

A custom panel that is used as the title panel for this wizard. The title panel is displayed on top of the wizard.

titles

private javax.swing.JLabel[] titles

The array of two titles that are displayed at the top of this wizard dialog. These values are automatically set whenever a new page is displayed by this wizard. The labels are created when the showWizard() method is invoked.

seqTitles

private javax.swing.JLabel[] seqTitles

The array of sequence titles that are displayed to the left of the wizard dialog. These values are automatically updated whenever a new page is displayed by this wizard. The labels are created when the showWizard() method is invoked.

prevButton

private javax.swing.JButton prevButton

The "Prev" button that is displayed at the bottom of the wizard in a separate panel. This button is created in the constructor but are organized into a panel only when the showWizard() method is called.

nextButton

private javax.swing.JButton nextButton

The "Next" button that is displayed at the bottom of the wizard in a separate panel. This button is created in the constructor but are organized into a panel only when the showWizard() method is called.

cancelButton

private javax.swing.JButton cancelButton

The "Cancel" button that is displayed at the bottom of the wizard in a separate panel. This button is created in the constructor but is organized into a panel only when the showWizard() method is called.

finishButton

private javax.swing.JButton finishButton

The "Finish" button that is displayed at the bottom of the wizard in a separate panel. This button is created in the constructor but are organized into a panel only when the showWizard() method is called. By default this button is hidden and is displayed only when the last panel is shown (instead of the next button).

helpButton

private javax.swing.JButton helpButton

The "Help" button that is displayed at the bottom of the wizard in a separate panel. This button is created in the constructor but are organized into a panel only when the showWizard() method is called. By default this button is hidden and is displayed only if a valid help URL is specified.

sequencePanel

private CustomPanel sequencePanel

A custom column panel that is displayed to the left of the wizard. This panel displays the sequence of configuration steps associated with this wizard.

pages

private java.util.ArrayList<WizardPage> pages

The array list containing the set of pages to be displayed by this wizard in the same sequence as they are to be displayed. Entries are appended to this list via the addPage() method.

currentPage

private int currentPage

The current page that is being displayed by this wizard. This value is set to zero and works it way up to the last page in this wizard.

helpURL

private java.lang.String helpURL

The URL to the online help page associated with this wizard. This value is set via the showWizard() method. If the Help URL is set then the "Help" button is displayed.

workerThreads

private java.util.ArrayList<java.lang.Thread> workerThreads

The list of worker threads that various pages may have spawned. This list is maintained so that the threads can be killed when this wizard exits. Various pages may add and remove threads as they are created and destroyed.

serialVersionUID

private static final long serialVersionUID

Generated serial version ID for serializing this class.

See Also:

Constant Field Values

Constructor Detail

WizardDialog

protected WizardDialog(java.awt.Frame parent)

The constructor. The constructor merely passes the parameters to the base class and initializes the shared (by all the WizardPage objects added to this wizard) static bitmap images in this class (if they have not yet been initialized).

Parameters:

parent - The parent window to which this wizard dialog logically belongs.

Method Detail

setTitleBackground

public void setTitleBackground(java.lang.String fileName,
                               java.awt.Color bgColor)

Set an image to be used for the title panel. This image is displayed in the background of the title panel. The title(s) are displayed on top of this image.

Parameters:

fileName - The file name of the image to be set as the background for the title of this wizard.

bgColor - The default background color for the title panel. If this parameter is null, then the default color is used.

setSequenceBackground

public void setSequenceBackground(java.lang.String fileName)

Set an image to be used for the sequence panel. This image is displayed in the background of the sequence panel that is displayed to the left of the wizard. The sequence panel displays an overview of the various sequences involved in this wizard.

Parameters:

fileName - The file name of the image to be set as the background for the sequence panel.

addPage

public void addPage(WizardPage page)

Adds a new wizard page to the list of wizard dialog pages. This method adds the given wizard page to the set of pages to be displayed by this

Parameters:

page - The wizard page to be added to the list of pages.

addThread

public void addThread(java.lang.Thread t)

Adds a given worker thread to the wizard. This method can be used to add a worker thread used by a wizard page. When the thread exits it must remove itself via the remoteThread method. The threads are interrupted on the user decided to cancel out of the wizard.

Parameters:

t - The thread to be added (and deleted when aborting) to the list of worker threads associated with this wizard.

removeThread

public void removeThread(java.lang.Thread t)

Remove a given worker thread from the list of worker threads. This method may be used to remove a worker thread from the list of worker threads associated with this wizard.

Parameters:

t -

showWizard

public void showWizard(java.lang.String helpURL)

The main method that lays out the components in this wizard and displays the wizard.

Parameters:

helpURL - The help URL to be used for this wizard if any. This parameter can be null.

updateSequence

private void updateSequence(int currPage)

Helper method to update the current sequence information and highlight the current step in the wizard.

Parameters:

currPage - The current page being displayed.

setButtonStatus

private void setButtonStatus()

Method to suitably set status of buttons in the wizard. This method can be used to enable/disable the buttons in this wizard panel.

setButtonStatus

public void setButtonStatus(int prev,
                            int next,
                            int cancel)

Method to enable or disable back and/or next buttons. This method can be used to enable or disable the back and/or next buttons in a wizard dialog. This method accepts integers with values -1, 0, and 1 that are used to represent the following three states respectively: unchanged, disable, or enable.

Parameters:

prev - This value must be -1, 0, or 1 to ignore, disable, or enable the back button in the wizard dialog.

next - This value must be -1, 0, or 1 to ignore, disable, or enable the next button in the wizard dialog.

cancel - This value must be -1, 0, or 1 to ignore, disable, or enable the cancel button in the wizard dialog.

getCurrentPage

public int getCurrentPage()

Obtain the index of the current page being displayed in this wizard.

Returns:

The zero-based index of the current page being displayed in this wizard.

getPage

public WizardPage getPage(int index)

Obtain wizard page associated with the given index.

Parameters:

index - The zero-based index of the page being requested.

Returns:

The page associated with this index.

layoutWizard

protected void layoutWizard()

This method is called from the showWizard method just before the wizard is made visible. This method organizes the various components in the wizard in the appropriate locations.

layoutButtons

protected java.awt.Component layoutButtons()

Helper method to layout the button panel to the bottom of the wizard. This method is invoked only once from the layoutWizard() method just before the wizard is about to be displayed on the screen. This method lays out the buttons in a panel to the bottom of the wizard.

Returns:

The button panel containing the buttons.

layoutSequencePanel

protected void layoutSequencePanel()

Helper method to layout the sequence panel in the wizard. This method is invoked only once from the layoutWizard() method just before the wizard is about to be displayed on the screen. This method creates one label for each wizard page and organizes them vertically in the sequence panel.

layoutTitlePanel

protected void layoutTitlePanel()

Helper method to layout the title panel in the wizard. This method is invoked only once from the layoutWizard() method just before the wizard is about to be displayed on the screen. This method creates and lays out the title and the sub-title components for this wizard.

cancel

protected boolean cancel()

Helper method invoked when user clicks cancel button. This is a helper method that derived classes can override. This method is invoked when the user clicks the cancel button in the wizard. This method is used to display a confirmation dialog to ensure that the user really wants to exit out of the wizard.

Note:Derived classes that override this method must call the base class if the user wishes to quit so that any worker threads associated with this wizard are interrupted and deleted (and they don't simply hang around).

Returns:

This method always returns true to indicate the user wants to quit.

done

protected void done(boolean success)

Helper method invoked once the wizard is done. This is a feedback method that derived classes can override. This method is invoked just after the wizard has completed its operations. This method can be used to trigger other operations after the wizard is done.

Note: The default method does absolutely nothing.

Parameters:

success - This flag is true if the wizard completed successfully and the user clicks the finish button. Otherwise this flag is set ot false, indicating an premature exit.

checkChangePage

protected void checkChangePage(int currPage,
                               int nextPage)

Helper method to perform the tasks related with page switching. This is a helper method that is invoked whenever the pages in the wizard need to be switched. This method operates as follows:

1. It checks with the current page to ensure that the change in pages is OK.
2. If the page can be changed, it calls the changePage() method to actually change the page.

Parameters:

currPage - Index of the current page being displayed.

nextPage - The next page that needs to be displayed.

changePage

public void changePage(int currPage,
                       int nextPage)

Helper method to perform the tasks related with page switching. This method can be used whenever the pages in the wizard need to be switched. This method operates as follows:

1. It switches pages and notifies the new page that the change has occurred.
2. It updates the wizard display.

Parameters:

currPage - Index of the current page being displayed.

nextPage - The next page that needs to be displayed.

actionPerformed

public void actionPerformed(java.awt.event.ActionEvent event)

Specified by:

actionPerformed in interface java.awt.event.ActionListener

getPagePane

public CustomPanel getPagePane()

Obtain the page pane to which wizard pages must be added.

Note:The number of pages in this component and the currently visible page determine the behavior or the buttons displayed by this wizard.

Returns:

The page pane which contains all the pages of this wizard.