org.freixas.jwizard
Class JWizardDialog

java.lang.Object
  extended by java.awt.Component
      extended by java.awt.Container
          extended by java.awt.Window
              extended by java.awt.Dialog
                  extended by javax.swing.JDialog
                      extended by org.freixas.jwizard.JWizardDialog
All Implemented Interfaces:
ImageObserver, MenuContainer, Serializable, Accessible, RootPaneContainer, WindowConstants

public class JWizardDialog
extends JDialog

This class creates a Wizard dialog.

I wrote this class because I couldn't find a good, free, easy-to-use, well-documented Java Wizard dialog. I hope this one is both flexible and easy-to-use.

A wizard is a dialog that leads a user through a procedure step-by-step. Some Wizards only gather information until the very last step, when they execute some tasks. Others will perform actions as they go.

To create a Wizard, you need two deal with two classes: JWizardDialog (this class) and JWizardPanel. The basic steps are:

Each JWizardPanel consists of a step title (which should be specific to each step) and a set of components which you layout as you wish. If possible, you should try to create and layout all panel components at construction time (so that the Wizard size can be accurately determined). If you need some dynamic layout, the method makingVisible() is called each time prior to making the JWizardPanel step visible.

The Wizard has four buttons which always appear, although they may at times be disabled. The buttons are Back, Next, Finish and Cancel. You can also add a Help button with addHelpButton().

When the buttons are pressed, they call the methods back(), next(), finish(), cancel() and help(), respectively. You can override any of these. The default finish() and cancel() methods call dispose(); when you override these, you would usually finish by calling super.finish() or super.cancel().

The default back(), next() and help() methods call equivalent methods in the current JWizardPanel. You would not normally override these methods, but the hooks are there if you need them.

In the JWizardPanel, the default back() and next() methods usally go to the previous or next panel. You can change the panel they go to by calling setBackPanel() or setNextPanel(), giving the index of the panel to go to. A value of -1 disables the corresponding button. Again, you can override these and then finish by calling super.back() or super.next(). The default help() method does nothing.

The Finish button is normally enabled only on the last step. If you allow an early exit from the Wizard, call setEarlyFinish() and the Finish button will be enabled.

The Cancel button is normally always enabled. To disable it on the last step, call disableCancelAtEnd().

Just prior to switching steps, switchToStep() is called in JWizardDialog. This method supplies the current and new step indices. The return value is the index of the panel which will actually be displayed. The default method returns the input value, but you can override this if you need special flow control in the JWizardDialog rather than the JWizardPanel.

When the dialog is displayed, it is normally centered over its parent. If there is no Frame parent, it is centered on the screen. You can disable this with disableCentering(), which must be called before the JWizardDialog is made visible.

That's about all there is to it.


This program is free software; you can redistribute it and/or modify it under the terms of the Artistic License. You should have received a copy of the Artistic License along with this program. If not, a copy is available at opensource.org.

Author:
Antonio Freixas
See Also:
JWizardPanel, Serialized Form

Nested Class Summary
 
Nested classes/interfaces inherited from class javax.swing.JDialog
JDialog.AccessibleJDialog
 
Nested classes/interfaces inherited from class java.awt.Dialog
Dialog.AccessibleAWTDialog
 
Nested classes/interfaces inherited from class java.awt.Window
Window.AccessibleAWTWindow
 
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.JDialog
accessibleContext, rootPane, rootPaneCheckingEnabled
 
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
JWizardDialog()
          Creates a non-modal JWizardDialog without a title and without a specified Frame owner.
JWizardDialog(Dialog owner)
          Creates a non-modal JWizardDialog without a title with the specified Dialog as its owner.
JWizardDialog(Dialog owner, boolean modal)
          Creates a modal or non-modal JWizardDialog without a title and with the specified owner Dialog.
JWizardDialog(Dialog owner, String title)
          Creates a non-modal JWizardDialog with the specified title and with the specified owner frame.
JWizardDialog(Dialog owner, String title, boolean modal)
          Creates a modal or non-modal JWizardDialog with the specified title and the specified owner Dialog.
JWizardDialog(Dialog owner, String title, boolean modal, GraphicsConfiguration gc)
          Creates a modal or non-modal JWizardDialog with the specified title, owner Dialog, and GraphicsConfiguration.
JWizardDialog(Frame owner)
          Creates a non-modal JWizardDialog without a title with the specified Frame as its owner.
JWizardDialog(Frame owner, boolean modal)
          Creates a modal or non-modal JWizardDialog without a title and with the specified owner Frame.
JWizardDialog(Frame owner, String title)
          Creates a non-modal JWizardDialog with the specified title and with the specified owner frame.
JWizardDialog(Frame owner, String title, boolean modal)
          Creates a modal or non-modal JWizardDialog with the specified title and the specified owner Frame.
JWizardDialog(Frame owner, String title, boolean modal, GraphicsConfiguration gc)
          Creates a modal or non-modal JWizardDialog with the specified title, owner Frame, and GraphicsConfiguration.
 
Method Summary
 void addHelpButton()
          This adds a help button to the wizard.
 void addWizardPanel(JWizardPanel panel)
          Add a panel representing a step in the wizard.
protected  void back()
          Called when the Back button is pressed.
protected  void cancel()
          Called when the Cancel button is pressed.
 void disableCancelAtEnd()
          If this method is called, the Cancel button is disabled when on the last step.
 void disableCentering()
          Don't center the dialog.
protected  void finish()
          Called when the Finish button is pressed.
 int getCurrentStep()
          Returns the current step being displayed by the wizard.
 int getLastStep()
          Returns the last step displayed by the wizard.
protected  void help()
          Called when the Help button is pressed.
 boolean isFinished()
          Returns true if the wizard finished (the user pressed the Finish) button).
protected  void next()
          Called when the Next button is pressed.
 void setEarlyFinish()
          If this method is called, the Finish button is enabled immediately.
 void setWizardIcon(Icon icon)
          Add an image which displays on the left side of the wizard.
 void show()
          Deprecated. As of JDK version 1.1, replaced by setVisible(boolean).
protected  int switchToStep(int currentIndex, int newIndex)
          This method is called just prior to switching from one step to another (after any next() or back() method is called).
 
Methods inherited from class javax.swing.JDialog
addImpl, createRootPane, dialogInit, getAccessibleContext, getContentPane, getDefaultCloseOperation, getGlassPane, getJMenuBar, getLayeredPane, getRootPane, isDefaultLookAndFeelDecorated, isRootPaneCheckingEnabled, paramString, processWindowEvent, remove, setContentPane, setDefaultCloseOperation, setDefaultLookAndFeelDecorated, setGlassPane, setJMenuBar, setLayeredPane, setLayout, setRootPane, setRootPaneCheckingEnabled, update
 
Methods inherited from class java.awt.Dialog
addNotify, getTitle, hide, isModal, isResizable, isUndecorated, setModal, setResizable, setTitle, setUndecorated
 
Methods inherited from class java.awt.Window
addPropertyChangeListener, addPropertyChangeListener, addWindowFocusListener, addWindowListener, addWindowStateListener, applyResourceBundle, applyResourceBundle, createBufferStrategy, createBufferStrategy, dispose, finalize, getBufferStrategy, getFocusableWindowState, getFocusCycleRootAncestor, getFocusOwner, getFocusTraversalKeys, getGraphicsConfiguration, getInputContext, getListeners, getLocale, getMostRecentFocusOwner, getOwnedWindows, getOwner, getToolkit, getWarningString, getWindowFocusListeners, getWindowListeners, getWindowStateListeners, isActive, isAlwaysOnTop, isFocusableWindow, isFocusCycleRoot, isFocused, isLocationByPlatform, isShowing, pack, postEvent, processEvent, processWindowFocusEvent, processWindowStateEvent, removeWindowFocusListener, removeWindowListener, removeWindowStateListener, setAlwaysOnTop, setBounds, setCursor, setFocusableWindowState, setFocusCycleRoot, setLocationByPlatform, setLocationRelativeTo, toBack, 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, removeNotify, setComponentZOrder, setFocusTraversalKeys, setFocusTraversalPolicy, setFocusTraversalPolicyProvider, setFont, 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, contains, createImage, createImage, createVolatileImage, createVolatileImage, disable, disableEvents, dispatchEvent, enable, enable, enableEvents, enableInputMethods, firePropertyChange, firePropertyChange, firePropertyChange, firePropertyChange, firePropertyChange, firePropertyChange, firePropertyChange, firePropertyChange, firePropertyChange, getBackground, getBounds, getBounds, getColorModel, getComponentListeners, getComponentOrientation, getCursor, getDropTarget, getFocusListeners, getFocusTraversalKeysEnabled, getFont, getFontMetrics, getForeground, getGraphics, 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, repaint, requestFocus, requestFocus, requestFocusInWindow, requestFocusInWindow, reshape, resize, resize, setBackground, setBounds, setComponentOrientation, setDropTarget, setEnabled, setFocusable, setFocusTraversalKeysEnabled, setForeground, setIgnoreRepaint, setLocale, setLocation, setLocation, setMaximumSize, setMinimumSize, setName, setPreferredSize, setSize, setSize, setVisible, show, size, toString, transferFocus, transferFocusUpCycle
 
Methods inherited from class java.lang.Object
clone, equals, getClass, hashCode, notify, notifyAll, wait, wait, wait
 

Constructor Detail

JWizardDialog

public JWizardDialog()
              throws HeadlessException
Creates a non-modal JWizardDialog without a title and without a specified Frame owner. A shared, hidden frame will be set as the owner of the dialog.

This constructor sets the component's locale property to the value returned by JComponent.getDefaultLocale().

Throws:
HeadlessException - If GraphicsEnvironment.isHeadless() returns true.

JWizardDialog

public JWizardDialog(Frame owner)
              throws HeadlessException
Creates a non-modal JWizardDialog without a title with the specified Frame as its owner. If owner is null, a shared, hidden frame will be set as the owner of the dialog.

This constructor sets the component's locale property to the value returned by JComponent.getDefaultLocale().

Parameters:
owner - The Frame owning the dialog.
Throws:
HeadlessException - If GraphicsEnvironment.isHeadless() returns true.

JWizardDialog

public JWizardDialog(Frame owner,
                     boolean modal)
              throws HeadlessException
Creates a modal or non-modal JWizardDialog without a title and with the specified owner Frame. If owner is null, a shared, hidden frame will be set as the owner of the dialog. This constructor sets the component's locale property to the value returned by JComponent.getDefaultLocale().

Parameters:
owner - The Frame owning the dialog.
modal - True for a modal dialog, false for one that allows others windows to be active at the same time.
Throws:
HeadlessException - If GraphicsEnvironment.isHeadless() returns true.

JWizardDialog

public JWizardDialog(Frame owner,
                     String title)
              throws HeadlessException
Creates a non-modal JWizardDialog with the specified title and with the specified owner frame. If owner is null, a shared, hidden frame will be set as the owner of the dialog.

This constructor sets the component's locale property to the value returned by JComponent.getDefaultLocale().

Parameters:
owner - The Frame owning the dialog.
title - The String to display in the dialog's title bar.
Throws:
HeadlessException - If GraphicsEnvironment.isHeadless() returns true.

JWizardDialog

public JWizardDialog(Frame owner,
                     String title,
                     boolean modal)
              throws HeadlessException
Creates a modal or non-modal JWizardDialog with the specified title and the specified owner Frame. If owner is null, a shared, hidden frame will be set as the owner of this dialog. All constructors defer to this one.

NOTE: Any popup components (JComboBox, JPopupMenu, JMenuBar) created within a modal dialog will be forced to be lightweight.

This constructor sets the component's locale property to the value returned by JComponent.getDefaultLocale().

Parameters:
owner - The Frame owning the dialog.
title - The String to display in the dialog's title bar.
modal - True for a modal dialog, false for one that allows others windows to be active at the same time.
Throws:
HeadlessException - If GraphicsEnvironment.isHeadless() returns true.

JWizardDialog

public JWizardDialog(Frame owner,
                     String title,
                     boolean modal,
                     GraphicsConfiguration gc)
              throws HeadlessException
Creates a modal or non-modal JWizardDialog with the specified title, owner Frame, and GraphicsConfiguration.

NOTE: Any popup components (JComboBox, JPopupMenu, JMenuBar) created within a modal dialog will be forced to be lightweight.

This constructor sets the component's locale property to the value returned by JComponent.getDefaultLocale.

Parameters:
owner - The Frame owning the dialog.
title - The String to display in the dialog's title bar.
modal - True for a modal dialog, false for one that allows others windows to be active at the same time.
gc - The GraphicsConfiguration of the target screen device. If gc is null, the same GraphicsConfiguration as the owning Frame is used.
Throws:
HeadlessException - If GraphicsEnvironment.isHeadless() returns true.

JWizardDialog

public JWizardDialog(Dialog owner)
              throws HeadlessException
Creates a non-modal JWizardDialog without a title with the specified Dialog as its owner. If owner is null, a shared, hidden frame will be set as the owner of the dialog.

This constructor sets the component's locale property to the value returned by JComponent.getDefaultLocale().

Parameters:
owner - The Dialog owning the dialog.
Throws:
HeadlessException - If GraphicsEnvironment.isHeadless() returns true.

JWizardDialog

public JWizardDialog(Dialog owner,
                     boolean modal)
              throws HeadlessException
Creates a modal or non-modal JWizardDialog without a title and with the specified owner Dialog. If owner is null, a shared, hidden frame will be set as the owner of the dialog. This constructor sets the component's locale property to the value returned by JComponent.getDefaultLocale().

Parameters:
owner - The Dialog owning the dialog.
modal - True for a modal dialog, false for one that allows others windows to be active at the same time.
Throws:
HeadlessException - If GraphicsEnvironment.isHeadless() returns true.

JWizardDialog

public JWizardDialog(Dialog owner,
                     String title)
              throws HeadlessException
Creates a non-modal JWizardDialog with the specified title and with the specified owner frame. If owner is null, a shared, hidden frame will be set as the owner of the dialog.

This constructor sets the component's locale property to the value returned by JComponent.getDefaultLocale().

Parameters:
owner - The Dialog owning the dialog.
title - The String to display in the dialog's title bar.
Throws:
HeadlessException - If GraphicsEnvironment.isHeadless() returns true.

JWizardDialog

public JWizardDialog(Dialog owner,
                     String title,
                     boolean modal)
              throws HeadlessException
Creates a modal or non-modal JWizardDialog with the specified title and the specified owner Dialog. If owner is null, a shared, hidden frame will be set as the owner of this dialog. All constructors defer to this one.

NOTE: Any popup components (JComboBox, JPopupMenu, JMenuBar) created within a modal dialog will be forced to be lightweight.

This constructor sets the component's locale property to the value returned by JComponent.getDefaultLocale().

Parameters:
owner - The Dialog owning the dialog.
title - The String to display in the dialog's title bar.
modal - True for a modal dialog, false for one that allows others windows to be active at the same time.
Throws:
HeadlessException - If GraphicsEnvironment.isHeadless() returns true.

JWizardDialog

public JWizardDialog(Dialog owner,
                     String title,
                     boolean modal,
                     GraphicsConfiguration gc)
              throws HeadlessException
Creates a modal or non-modal JWizardDialog with the specified title, owner Dialog, and GraphicsConfiguration.

NOTE: Any popup components (JComboBox, JPopupMenu, JMenuBar) created within a modal dialog will be forced to be lightweight.

This constructor sets the component's locale property to the value returned by JComponent.getDefaultLocale.

Parameters:
owner - The Dialog owning the dialog.
title - The String to display in the dialog's title bar.
modal - True for a modal dialog, false for one that allows others windows to be active at the same time.
gc - The GraphicsConfiguration of the target screen device. If gc is null, the same GraphicsConfiguration as the owning Dialog is used.
Throws:
HeadlessException - If GraphicsEnvironment.isHeadless() returns true.
Method Detail

setWizardIcon

public void setWizardIcon(Icon icon)
Add an image which displays on the left side of the wizard. By default, no image is displayed. This must be set before the dialog is made visible.

Parameters:
icon - The icon representing the image to display. If null, no image is displayed.

addWizardPanel

public void addWizardPanel(JWizardPanel panel)
Add a panel representing a step in the wizard. Since removing a panel would force a renumbering of the remaining panels and since you have flexible sequencing control, there is no matching removeWizardPanel() method.

Parameters:
panel - The JWizardPanel to add

addHelpButton

public void addHelpButton()
This adds a help button to the wizard. When the button is pressed, the help() method is called.

See Also:
help()

setEarlyFinish

public void setEarlyFinish()
If this method is called, the Finish button is enabled immediately. By default, it is enabled only on the last step (any step where the next JWizardPanel step is -1).


isFinished

public boolean isFinished()
Returns true if the wizard finished (the user pressed the Finish) button). Returns false otherwise (either the wizard hasn't finished or the user pressed Cancel to exit).

Returns:
True if the wizard finished.

disableCancelAtEnd

public void disableCancelAtEnd()
If this method is called, the Cancel button is disabled when on the last step. If setEarlyFinish() is called, it is still disabled only on the last step.


disableCentering

public void disableCentering()
Don't center the dialog. This method must be called before the dialog is made visible. The default behavior is to center the dialog over its parent, or on the screen if no parent was given.


getCurrentStep

public int getCurrentStep()
Returns the current step being displayed by the wizard. Steps start at 0. If no step is yet displayed, a -1 is returned.

Returns:
The current step being displayed by the wizard.

getLastStep

public int getLastStep()
Returns the last step displayed by the wizard. Steps start at 0. If there is no previous step yet, -1 is returned.

Returns:
The last step being displayed by the wizard.

show

public void show()
Deprecated. As of JDK version 1.1, replaced by setVisible(boolean).

Overrides:
show in class Dialog

back

protected void back()
Called when the Back button is pressed. This calls the back() method in the current JWizardPanel.

See Also:
JWizardPanel.back()

next

protected void next()
Called when the Next button is pressed. This calls the next() method in the current JWizardPanel.

See Also:
JWizardPanel.next()

finish

protected void finish()
Called when the Finish button is pressed. This calls dispose(). You will probably want to override this.


cancel

protected void cancel()
Called when the Cancel button is pressed. This calls dispose().


help

protected void help()
Called when the Help button is pressed. This calls the help() method in the current JWizardPanel. If the help text is the same for all panels, you will want to override this.


switchToStep

protected int switchToStep(int currentIndex,
                           int newIndex)
This method is called just prior to switching from one step to another (after any next() or back() method is called). It receives the current and new indices. By default, it returns the new index. You can override the method if you need to control sequencing from this JWizardDialog class (normally, each step decides what the back and next steps should be).

Parameters:
currentIndex - The index of the current JWizardPanel.
newIndex - The index of the JWizardPanel we are about to display.
Returns:
The index of the JWizardPanel to display.

Copyright © 2004-2005 Antonio Freixas
Licensed under the Artistic License