org.netbeans.spi.wizard
Class WizardBranchController

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

public abstract class WizardBranchController
extends java.lang.Object

Extend this class to create wizards which have branch points in them - either override getWizardForStep to return one or another a wizard which represents the subsequent steps after a decision point, or override getPanelProviderForStep to provide instances of WizardPanelProvider if there are no subsequent branch points and the continuation is a simple wizard.

The basic idea is to supply a base wizard for the initial steps, stopping at the branch point. The panel for the branch point should put enough information into the settings map that the WizardBranchController can decide what to return as the remaining steps of the wizard.

The result is a Wizard which embeds sub-wizards; when the PanelProvider passed to the constructor runs out of steps, the master Wizard will try to find a sub-Wizard by calling getWizardForStep. If non-null, the user seamlessly continues in the returned wizard. To create Wizards with multiple branches, simply override getWizardForStep to create another WizardBranchController and return the result of its createWizard method.

Note that it is important to cache the instances of WizardPanelProvider or Wizard which are returned here - this class's methods may be called frequently to determine if the sequence of steps (the next wizard) have changed.

Author:
Tim Boudreau

Constructor Summary
Modifier Constructor and Description
protected WizardBranchController(WizardPage onlyPage)
          Create a new WizardBranchController using the passed WizardPage as the initial page of the wizard.
protected WizardBranchController(WizardPage[] pages)
          Create a new WizardBranchController using the passed WizardPage instances as the initial pages of the wizard.
protected WizardBranchController(WizardPanelProvider base)
          Create a new WizardBranchController.
 
Method Summary
Modifier and Type Method and Description
 Wizard createWizard()
          Create a Wizard to represent this branch controller.
protected  WizardPanelProvider getPanelProviderForStep(java.lang.String step, java.util.Map settings)
          Override this method to return a WizardPanelProvider representing the steps from here to the final step of the wizard, varying the returned object based on the contents of the map and the step in question.
protected  Wizard getWizardForStep(java.lang.String step, java.util.Map settings)
          Get the wizard which represents the subsequent panes after this step.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Constructor Detail

WizardBranchController

protected WizardBranchController(WizardPanelProvider base)
Create a new WizardBranchController. The base argument provides the initial step(s) of the wizard up; when the user comes to the last step of the base wizard, this WizardBranchController will be asked for a wizard to provide subsequent panes. So the base wizard should put some token into the settings map based on what the user selects on its final pane, which the WizardBranchController can use to decide what the next steps should be.


WizardBranchController

protected WizardBranchController(WizardPage[] pages)
Create a new WizardBranchController using the passed WizardPage instances as the initial pages of the wizard.

Parameters:
pages - An array of WizardPage instances

WizardBranchController

protected WizardBranchController(WizardPage onlyPage)
Create a new WizardBranchController using the passed WizardPage as the initial page of the wizard. The initial page should determine the subsequent steps of the wizard.

Parameters:
onlyPage - An instance of WizardPage
Method Detail

getWizardForStep

protected Wizard getWizardForStep(java.lang.String step,
                                  java.util.Map settings)
Get the wizard which represents the subsequent panes after this step. The UI for the current step should have put sufficient data into the settings map to decide what to return; return null if not.

The default implementation delegates to getPanelProviderForStep() and returns a Wizard representing the result of that call.

Note: This method can be called very frequently, to determine if the sequence of steps has changed - so it needs to run fast. Returning the same instance every time the same arguments are passed is highly recommended. It will typically be called whenever a change is fired by the base wizard (i.e. every call setProblem() should generate a check to see if the navigation has changed).

Note that the wizard for the subsequent steps will be instantiated as soon as it is known what the user's choice is, so the list of pending steps can be updated (this does not mean that all subsequent panel UI components of the wizard will be instantiated, just the Wizard object itself, which will create panels on demand if they have not already been created).

Parameters:
step - The current step the user is on in the wizard
settings - The settings map, which previous panes of the wizard have been writing information into

getPanelProviderForStep

protected WizardPanelProvider getPanelProviderForStep(java.lang.String step,
                                                      java.util.Map settings)
Override this method to return a WizardPanelProvider representing the steps from here to the final step of the wizard, varying the returned object based on the contents of the map and the step in question. The default implementation of this method throws an Error - either override this method, or override getWizardForStep() (in which case this method will not be called).

Note: This method can be called very frequently, to determine if the sequence of steps has changed - so it needs to run fast. Returning the same instance every time called with equivalent arguments is highly recommended.

Parameters:
step - The string ID of the current step
settings - The settings map, which previous panes of the wizard will have written content into

createWizard

public final Wizard createWizard()
Create a Wizard to represent this branch controller. The resulting Wizard instance is cached; subsequent calls to this method will return the same instance.