com.ehsbe.commons.gui.wizard
Class Wizard

java.lang.Object
  com.ehsbe.commons.gui.wizard.Wizard

All Implemented Interfaces:

TaskControlListener, ActionListener, EventListener

public class Wizard
extends Object
implements TaskControlListener, ActionListener

The controller which manages all elements a wizard usually needs. It is designed to be simple to understand, simple to use and just in case simple to debug. Also it is designed to provide a maximum of flexibility, to avoid the usual boiler plate code, and to provide language support. Furthermore it tries to guide the user to make the wizard as thread-safe as possible since especially since Nimbus aka Synth-Look&Feel appearance it is also more important than before, to create the UIs within the EventDispatchThread (EDT).

The wizard manages one main panel (getContentPane(), which consists of:

• a banner panel (see getBanner()) on the top, which is used to display the task's title, description and optiinally an image for decoration
• a navigation panel (see getButtons()) at the bottom with all available navigation buttons
• an optional sidebar (see getSidebar()) aka overview on the left side, which is per default used to display the names of the task, which need to be done, and an optional background image
• a wizard page (see wizardPage) at the center, which contains all the UI elements needed to collect the user information required to finish the current task in action (see TaskControl.get())

All components except the wizard page are created per default automatically and get an update as soon as a switch to the next task has been made, using the appropriate getter methods of the correpsonding task.

The wizard uses a mediator called TaskControl to:

• determine, which task is active, next, previous
• initiate an actual task switch
• prepare the execution of a task
• get the wizard page for the current task in action and start its execution
• notify the current task in action about the users intentention to switch to another task or finish/cancel the wizard
• receive information about state changes of the current task in action
• receive information about what navigation buttons should be enabled/disabled
• fire up an optional help UI (if available)

The wizard uses the ButtonPanel to:

• enable/disable navigation buttons on demand
• receive "button click events" and initiate the appropriate action(s)

The wizard uses the getter methods of the currently active task to:

• update the banner panel
• update the optional sidebar

Version:

$Revision: 502 $

Author:

Jens Elkner

See Also:

TaskControl.getPage(HashMap, EnumSet), TaskControl.showHelp(HashMap, JComponent)

Field Summary

protected JComponent

wizardPage the current wizard page in action

Constructor Summary

	Wizard(Task main, boolean sidebar, boolean help) Create a new wizard and initialize its main UI elements.
	Wizard(TaskControl control, boolean sidebar, boolean help) Create a new wizard and initialize its main UI elements.
protected	Wizard(Task main, TaskControl control, boolean sidebar, boolean help) Create a new wizard, its default task control and initialize its main UI elements.

Method Summary

void	actionPerformed(ActionEvent e) Listens to the navigation buttons.
void	attachTo(JDialog dlg) Attaches the main wizard panel to the given dialog.
Boolean	cancelled() Check, whether the wizard has been cancelled.
protected void	close() Cleanup, i.e. per default dispose the task controler.
static JDialog	createDialog(Task main, boolean sidebar, boolean help, JFrame owner) Create a new modal, resizable wizard dialog.
static JDialog	createDialog(TaskControl control, boolean sidebar, boolean help, JFrame owner) Create a new modal, resizable wizard dialog.
protected void	ctrlBusy() Handles task controller notifications the busy state change of the currently executing task.
protected void	ctrlLocale() Handles task controller notifications about the preferred locale to use.
protected void	ctrlNavMode(EnumSet<NavMode> modes) Handles task controller notifications about requested navigation button state changes.
protected void	ctrlTaskFinshed(NavMode next) Handles task controller notifications about an active task has finished its work, i.e. switching to another task is allowed, if the corresponding navigation buttons are enabled.
protected void	ctrlTasklist() Handles task controller notifications about tasklist structure changes.
protected void	ctrlTaskPrepared() Handles task controller notifications about the currently active task: it has finished its preparation and is ready to execute.
protected void	ctrlTaskSwitched() Handles task controller notifications about an active task change.
protected void	enableUI(boolean enable) [un]block all input events and show a wait/normal cursor.
BannerPanel	getBanner() Get the banner panel currently in use.
ButtonPanel	getButtons() Get the navigation button pannel currently in use.
AbstractAction	getCloseAction() Get the action, which should be used to programatically shutdown the wizard, by calling its actionPerformed(null) method.
JPanel	getContentPane() Get the panel, which contains all wizard elements.
HashMap<Task,HashMap<? extends Object,? extends Object>>	getSettings() Get a reference to all the settings gathered in the wizard pages so far.
Sidebar	getSidebar() Get the sidebar currently in use.
void	setBanner(BannerPanel banner) Set the banner panel to be used.
void	setButtons(ButtonPanel buttons) Set the navigation button panel to be used.
void	setSidebar(Sidebar sidebar) Set the sidebar to be used.
void	stateChanged(TaskControlEvent e) Invoked when the state of the task controller has been changed.
protected void	updateBanner(Task t) update banner image, title and description.
protected void	updateSidebar(Task t) update sidebar background image .

Methods inherited from class java.lang.Object

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

Field Detail

wizardPage

protected JComponent wizardPage

the current wizard page in action

Constructor Detail

Wizard

public Wizard(TaskControl control,
              boolean sidebar,
              boolean help)
       throws Exception

Create a new wizard and initialize its main UI elements.

UI components are automatically and immediately created within the EDT.

Parameters:

control - the task controller to use.

sidebar - if true, enable the sidebar.

help - if true show the help button as well (otherwise it is hidden).

Throws:

Exception

Wizard

public Wizard(Task main,
              boolean sidebar,
              boolean help)
       throws Exception

Create a new wizard and initialize its main UI elements.

UI components are automatically and immediately created within the EDT.

Parameters:

main - the top level task of all tasks to execute

sidebar - if true, enable the sidebar.

help - if true show the help button as well (otherwise it is hidden).

Throws:

Exception

Wizard

protected Wizard(Task main,
                 TaskControl control,
                 boolean sidebar,
                 boolean help)
          throws Exception

Create a new wizard, its default task control and initialize its main UI elements.

UI components are automatically and immediately created within the EDT.

Parameters:

main - the top level task of all tasks to execute. Use null, if control is not null.

control - the task controller to use. Use null to use the default implementation.

sidebar - if true, enable the sidebar.

help - if true show the help button as well (otherwise it is hidden).

Throws:

Exception

Method Detail

createDialog

public static JDialog createDialog(Task main,
                                   boolean sidebar,
                                   boolean help,
                                   JFrame owner)
                            throws Exception

Create a new modal, resizable wizard dialog.

Parameters:

main - the main task.

help - if true, show the help button as well.

sidebar - if true, enable the sidebar.

owner - where to anchor the new dialog.

Returns:

a new dialog with disposes on close.

Throws:

Exception - if the given task is null

createDialog

public static JDialog createDialog(TaskControl control,
                                   boolean sidebar,
                                   boolean help,
                                   JFrame owner)
                            throws Exception

Create a new modal, resizable wizard dialog.

Parameters:

control - the task controller to use.

help - if true, show the help button as well.

sidebar - if true, enable the sidebar.

owner - where to anchor the new dialog.

Returns:

a new dialog with disposes on close.

Throws:

Exception - if the given control is null

attachTo

public void attachTo(JDialog dlg)

Attaches the main wizard panel to the given dialog. All components from its content pane gets replaced by the main panel and the dialogs default close operation is set to WindowConstants.DISPOSE_ON_CLOSE.

Parameters:

dlg - where to attach the main wizard panel

Throws:

IllegalArgumentException - if the given dialog is null

getContentPane

public JPanel getContentPane()

Get the panel, which contains all wizard elements.

Returns:

the main wizard panel.

getSidebar

public Sidebar getSidebar()

Get the sidebar currently in use. Adjustments to its properties via its getter/setter methods are usually safe. However, adjustments should be made before the dialog gets shown to avoid artifcats/multi-threading issues.

Returns:

the sidebar in use, which might be null if none is used.

setSidebar

public void setSidebar(Sidebar sidebar)

Set the sidebar to be used. Use it only, if the default sidebar is not sufficient/fancy enough for your needs. The wizard takes care, that the panel modifications are made on the EDT (see SwingUtilities2.invokeLater(Runnable)), so calling outside the EDT is ok.

Parameters:

sidebar - sidebar to set. If null, it removes the current sidebar in from the main panel.

getBanner

public BannerPanel getBanner()

Get the banner panel currently in use.

Returns:

the banner currently in use, but never null.

setBanner

public void setBanner(BannerPanel banner)

Set the banner panel to be used. Use it only, if the default banner panel is not sufficient/fancy enough for your needs. The wizard takes care, that the panel modifications are made on the EDT (see SwingUtilities2.invokeLater(Runnable)), so calling outside the EDT is ok.

Parameters:

banner - banner panel to set.

Throws:

IllegalArgumentException - if the argument is null.

getButtons

public ButtonPanel getButtons()

Get the navigation button pannel currently in use.

Returns:

the navigation button currently in use, but never null.

setButtons

public void setButtons(ButtonPanel buttons)

Set the navigation button panel to be used. Use it only, if the default navigation button panel is not sufficient/fancy enough for your needs. The wizard takes care, that the panel modifications are made on the EDT (see SwingUtilities2.invokeLater(Runnable)), so calling outside the EDT is ok.

Parameters:

buttons - ther navigation button panel to set.

Throws:

IllegalArgumentException - if the argument is null.

cancelled

public Boolean cancelled()

Check, whether the wizard has been cancelled.

Returns:

null if the final result was not yet determined (wizard is still running), Boolean.TRUE if the wizard was not finished using the finish button.

getSettings

public HashMap<Task,HashMap<? extends Object,? extends Object>> getSettings()

Get a reference to all the settings gathered in the wizard pages so far.

Returns:

a possible empty map, but not null.

close

protected void close()

Cleanup, i.e. per default dispose the task controler. Gets usally called, when the window is closing, i.e. dialog gets closed.

getCloseAction

public AbstractAction getCloseAction()

Get the action, which should be used to programatically shutdown the wizard, by calling its actionPerformed(null) method.

Returns:

null if the wizard is not yet attached to a dialog, the close action otherwise.

enableUI

protected void enableUI(boolean enable)

[un]block all input events and show a wait/normal cursor.

Parameters:

enable - if true block, otherwise unblock.

ctrlBusy

protected void ctrlBusy()

Handles task controller notifications the busy state change of the currently executing task. If the task is busy, all input events are blocked and the busy mode gets visualized, otherwise unblock.

ctrlNavMode

protected void ctrlNavMode(EnumSet<NavMode> modes)

Handles task controller notifications about requested navigation button state changes.

Parameters:

modes - buttons to enable.

ctrlTaskFinshed

protected void ctrlTaskFinshed(NavMode next)

Handles task controller notifications about an active task has finished its work, i.e. switching to another task is allowed, if the corresponding navigation buttons are enabled.

Parameters:

next - the intention, what to do next.

updateSidebar

protected void updateSidebar(Task t)

update sidebar background image .

Parameters:

t - the current task in action

updateBanner

protected void updateBanner(Task t)

update banner image, title and description.

Parameters:

t - the current task in action

ctrlTaskSwitched

protected void ctrlTaskSwitched()

Handles task controller notifications about an active task change.

ctrlTaskPrepared

protected void ctrlTaskPrepared()

Handles task controller notifications about the currently active task: it has finished its preparation and is ready to execute.

ctrlLocale

protected void ctrlLocale()

Handles task controller notifications about the preferred locale to use.

ctrlTasklist

protected void ctrlTasklist()

Handles task controller notifications about tasklist structure changes.

stateChanged

public void stateChanged(TaskControlEvent e)

Invoked when the state of the task controller has been changed. It may or may not being invoked from the EDT, so this listener should check, if it wants to modify UI related components/states.

Specified by:

stateChanged in interface TaskControlListener

Parameters:

e - the triggering event.

actionPerformed

public void actionPerformed(ActionEvent e)

Listens to the navigation buttons. This is the primary control for page switching. To prevent a user from going forward, backward, etc. one needs to enable/disable the appropriate buttons.

Specified by:

actionPerformed in interface ActionListener

See Also:

TaskControl.setNavMode(Task, java.util.EnumSet)