|
||||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | |||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |
java.lang.Objectorg.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:
WizardPage
- use or subclass WizardPage, and pass an array
of instances, or an array of the Class
objects of your subclasses
to WizardPage.createWizard()
. This class offers the added
convenience that standard Swing components will be listened to automatically,
and if their Name property is set, the value from the component will be
automatically put into the settings map.
WizardPanelProvider
- subclass this to create a Wizard
with a fixed set of steps. You provide a set of unique ID strings to the
constructor, for all of the steps in the wizard, and override
createPanel() to create the GUI component that should be displayed for
each step - it will be called on demand as the user moves through the
wizardWizardBranchController
- this is for creating complex
wizards with decision points after which the future steps change, depending
on what the user chooses. Create a simple wizard using WizardPage or
WizardPanelProvider to represent the initial steps.
Then override getWizardForStep()
or
getPanelProviderForStep()
to return a different Wizard to
represent the remaining steps at any point where the set of future steps
changes. You can have as many branch points as you want, simply by
using WizardBranchController to create the wizards for different decision
points.
In other words, a wizard with a different set of panels (or number of steps) depending on the user's decision is really three wizards composed into one - one wizard that provides the initial set of steps, and then two others, one or the other of which will actually provide the steps/panels after the decision point (the Wizards are created on demand, for efficiency, so if the user never changes his or her mind at the decision point, only two of the three Wizards are ever actually created).
WizardDisplayer
,
WizardPage
,
WizardPanelProvider
,
WizardBranchController
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. |
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 |
---|
public static final int MODE_CAN_CONTINUE
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).
public static final int MODE_CAN_FINISH
getForwardNavigationMode
to indicate
that the Finish button can be enabled if the problem string is null.
public static final int MODE_CAN_CONTINUE_OR_FINISH
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
public static final java.lang.String UNDETERMINED_STEP
Method Detail |
---|
public javax.swing.JComponent navigatingTo(java.lang.String id, java.util.Map wizardData)
id
.
id
- The id of the panel being navigated towizardData
- 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.id
of the Wizard
public java.lang.String getCurrentStep()
navigatingTo()
.
public java.lang.String getNextStep()
getCurrentStep()
.
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.public java.lang.String getPreviousStep()
getCurrentStep()
, or null if the current step is the
first page of the wizard.
public java.lang.String getProblem()
public java.lang.String[] getAllSteps()
UNDETERMINED_STEP
if subsequent steps of the
wizard depend on the user's interaction beyond that point.
navigatingTo
to change the current step of the wizardpublic java.lang.String getLongDescription(java.lang.String stepId)
stepId
- The ID of the step for which a description is requestedpublic java.lang.String getStepDescription(java.lang.String id)
id
- A step id among those returned by getAllSteps()
public java.lang.Object finish(java.util.Map settings) throws WizardException
settings
- The complete set of key-value pairs gathered by the
various panels as the user proceeded through the wizardWizardException
public boolean cancel(java.util.Map settings)
settings
- The (possibly incomplete) set of key-value pairs gathered by the
various panels as the user proceeded through the wizardpublic java.lang.String getTitle()
public boolean isBusy()
public int getForwardNavigationMode()
MODE_CAN_CONTINUE
,
MODE_CAN_FINISH
, or MODE_CAN_CONTINUE_OR_FINISH
.public void addWizardObserver(WizardObserver observer)
observer
- A WizardObserverpublic void removeWizardObserver(WizardObserver observer)
observer
- A WizardObserverpublic int hashCode()
hashCode
in class java.lang.Object
public boolean equals(java.lang.Object o)
equals
in class java.lang.Object
public void show()
public java.lang.Object show(Wizard wizard, javax.swing.Action help)
public java.lang.Object show(Wizard wizard, java.awt.Rectangle r)
public java.lang.Object show(Wizard wizard, java.awt.Rectangle r, javax.swing.Action help)
|
||||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | |||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |