org.netbeans.spi.wizard
Class Wizard

java.lang.Object
  extended by org.netbeans.spi.wizard.Wizard

public final class Wizard
extends java.lang.Object

Encapsulates the logic and state of a Wizard. A Wizard gathers information into a Map, and then performs some action with that information when the user clicks Finish. To display a wizard, pass it to one of the methods on WizardDisplayer.getDefault().

A Wizard is a series of one or more steps represented by panels in the user interface. Each step is identified by a unique String ID. Panels are created, usually on-demand, as the user navigates through the UI of the wizard. Panels typically listen on components they contain and put values into the Map where the wizard gathers data. Note that if the user navigates backward, data entered on pages after the current one disappears from the Map.

To create a Wizard, you do not implement or instantiate this class directly, but rather, use one of the convenience classes in this package. There are three:

Author:
Timothy Boudreau
See Also:
WizardDisplayer, WizardPage, WizardPanelProvider, WizardBranchController

Field Summary
Modifier and Type Field and Description
static int MODE_CAN_CONTINUE
          Constant that can be returned by getForwardNavigationMode() to indicate that the Next button can be enabled (or the Finish button if the current panel is the last one in the wizard).
static int MODE_CAN_CONTINUE_OR_FINISH
          Constant that can be returned by getForwardNavigationMode to indicate that both the Finish and Next buttons can be enabled if the problem string is null.
static int MODE_CAN_FINISH
          Constant that can be returned by getForwardNavigationMode to indicate that the Finish button can be enabled if the problem string is null.
static java.lang.String UNDETERMINED_STEP
          Special panel ID key indicating a branch point in the wizard, after which the next step(s) are unknown.
 
Method Summary
Modifier and Type Method and Description
 void addWizardObserver(WizardObserver observer)
          Add a WizardObserver that will be notified of navigability and step changes.
 boolean cancel(java.util.Map settings)
          Called when the user has clicked the Cancel button in the wizard UI or otherwise closed the UI component without completing the wizard.
 boolean equals(java.lang.Object o)
           
 java.lang.Object finish(java.util.Map settings)
          Called when the user has clicked the finish button.
 java.lang.String[] getAllSteps()
          Get the string IDs of all known steps in this wizard, terminating with UNDETERMINED_STEP if subsequent steps of the wizard depend on the user's interaction beyond that point.
 java.lang.String getCurrentStep()
          Get the current step the wizard is on, as determined by the most recent call to navigatingTo().
 int getForwardNavigationMode()
          Get the navigation mode, which determines the enablement state of the Next and Finish buttons.
 java.lang.String getLongDescription(java.lang.String stepId)
          Get a long description for this panel.
 java.lang.String getNextStep()
          Get the id of the step that comes after current step returned by getCurrentStep().
 java.lang.String getPreviousStep()
          Get the id of the preceding step to the current one as returned by getCurrentStep(), or null if the current step is the first page of the wizard.
 java.lang.String getProblem()
          Get the problem string that should be displayed to the user.
 java.lang.String getStepDescription(java.lang.String id)
          Get a localized String description of the step for the passed id, which may be displayed in the UI of the wizard.
 java.lang.String getTitle()
          Get the title of the Wizard that should be displayed in its dialog titlebar (if any).
 int hashCode()
           
 boolean isBusy()
          Determine if the wizard is busy doing work in a background thread and all navigation controls should be disabled.
 javax.swing.JComponent navigatingTo(java.lang.String id, java.util.Map wizardData)
          Notify the wizard that the user is navigating to a different panel, as identified by the passed id.
 void removeWizardObserver(WizardObserver observer)
          Remove a WizardObserver.
 void show()
          Delegates to WizardDisplayer.showWizard()
 java.lang.Object show(Wizard wizard, javax.swing.Action help)
          Delegates to WizardDisplayer.showWizard()
 java.lang.Object show(Wizard wizard, java.awt.Rectangle r)
          Delegates to WizardDisplayer.showWizard()
 java.lang.Object show(Wizard wizard, java.awt.Rectangle r, javax.swing.Action help)
          Delegates to WizardDisplayer.showWizard()
 
Methods inherited from class java.lang.Object
clone, finalize, getClass, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

MODE_CAN_CONTINUE

public static final int MODE_CAN_CONTINUE
Constant that can be returned by getForwardNavigationMode() to indicate that the Next button can be enabled (or the Finish button if the current panel is the last one in the wizard).

See Also:
Constant Field Values

MODE_CAN_FINISH

public static final int MODE_CAN_FINISH
Constant that can be returned by getForwardNavigationMode to indicate that the Finish button can be enabled if the problem string is null.

See Also:
Constant Field Values

MODE_CAN_CONTINUE_OR_FINISH

public static final int MODE_CAN_CONTINUE_OR_FINISH
Constant that can be returned by getForwardNavigationMode to indicate that both the Finish and Next buttons can be enabled if the problem string is null. This value is a bitmask - i.e. MODE_CAN_CONTINUE_OR_FINISH == MODE_CAN_CONTINUE | MODE_CAN_FINISH

See Also:
Constant Field Values

UNDETERMINED_STEP

public static final java.lang.String UNDETERMINED_STEP
Special panel ID key indicating a branch point in the wizard, after which the next step(s) are unknown.

See Also:
Constant Field Values
Method Detail

navigatingTo

public javax.swing.JComponent navigatingTo(java.lang.String id,
                                           java.util.Map wizardData)
Notify the wizard that the user is navigating to a different panel, as identified by the passed id.

Parameters:
id - The id of the panel being navigated to
wizardData - The data gathered thus far as the user has progressed through the wizard. The contents of this map should not contain any key/values that were assigned on future panels, if the user is navigating backward.
Returns:
The component that should be shown for step id of the Wizard

getCurrentStep

public java.lang.String getCurrentStep()
Get the current step the wizard is on, as determined by the most recent call to navigatingTo().


getNextStep

public java.lang.String getNextStep()
Get the id of the step that comes after current step returned by getCurrentStep().

Returns:
Null if this is the last step of the wizard; UNDETERMINED_STEP if this is a branch point and the user yet needs to do some interaction with the UI of the current panel to trigger computation of the id of the next step; otherwise, the unique id of the next step.

getPreviousStep

public java.lang.String getPreviousStep()
Get the id of the preceding step to the current one as returned by getCurrentStep(), or null if the current step is the first page of the wizard.

Returns:
the id of the previous step or null

getProblem

public java.lang.String getProblem()
Get the problem string that should be displayed to the user.

Returns:
A string describing what the user needs to do to enable the Next or Finish buttons, or null if the buttons may be enabled

getAllSteps

public java.lang.String[] getAllSteps()
Get the string IDs of all known steps in this wizard, terminating with UNDETERMINED_STEP if subsequent steps of the wizard depend on the user's interaction beyond that point.

Returns:
an array of strings which may individually be passed to navigatingTo to change the current step of the wizard

getLongDescription

public java.lang.String getLongDescription(java.lang.String stepId)
Get a long description for this panel. The long description should be used in preference to the short description in the top of a wizard panel in the UI, if it returns non-null.

Parameters:
stepId - The ID of the step for which a description is requested
Returns:
A more detailed localized description or null

getStepDescription

public java.lang.String getStepDescription(java.lang.String id)
Get a localized String description of the step for the passed id, which may be displayed in the UI of the wizard.

Parameters:
id - A step id among those returned by getAllSteps()

finish

public java.lang.Object finish(java.util.Map settings)
                        throws WizardException
Called when the user has clicked the finish button. This method computes whatever the result of the wizard is.

Parameters:
settings - The complete set of key-value pairs gathered by the various panels as the user proceeded through the wizard
Returns:
An implementation-dependent object that is the outcome of the wizard. May be null. Special return values are instances of DeferredWizardResult and Summary which will affect the behavior of the UI.
Throws:
WizardException

cancel

public boolean cancel(java.util.Map settings)
Called when the user has clicked the Cancel button in the wizard UI or otherwise closed the UI component without completing the wizard.

Parameters:
settings - The (possibly incomplete) set of key-value pairs gathered by the various panels as the user proceeded through the wizard
Returns:
true if the UI may indeed be closed, false if closing should not be permitted

getTitle

public java.lang.String getTitle()
Get the title of the Wizard that should be displayed in its dialog titlebar (if any).

Returns:
A localized string

isBusy

public boolean isBusy()
Determine if the wizard is busy doing work in a background thread and all navigation controls should be disabled.

Returns:
whether or not the wizard is busy

getForwardNavigationMode

public int getForwardNavigationMode()
Get the navigation mode, which determines the enablement state of the Next and Finish buttons.

Returns:
one of the constants MODE_CAN_CONTINUE, MODE_CAN_FINISH, or MODE_CAN_CONTINUE_OR_FINISH.

addWizardObserver

public void addWizardObserver(WizardObserver observer)
Add a WizardObserver that will be notified of navigability and step changes.

Parameters:
observer - A WizardObserver

removeWizardObserver

public void removeWizardObserver(WizardObserver observer)
Remove a WizardObserver.

Parameters:
observer - A WizardObserver

hashCode

public int hashCode()
Overrides:
hashCode in class java.lang.Object

equals

public boolean equals(java.lang.Object o)
Overrides:
equals in class java.lang.Object

show

public void show()
Delegates to WizardDisplayer.showWizard()


show

public java.lang.Object show(Wizard wizard,
                             javax.swing.Action help)
Delegates to WizardDisplayer.showWizard()


show

public java.lang.Object show(Wizard wizard,
                             java.awt.Rectangle r)
Delegates to WizardDisplayer.showWizard()


show

public java.lang.Object show(Wizard wizard,
                             java.awt.Rectangle r,
                             javax.swing.Action help)
Delegates to WizardDisplayer.showWizard()