org.netbeans.spi.wizard
Class WizardPanelProvider

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

public abstract class WizardPanelProvider
extends java.lang.Object

(Note: WizardPage offers somewhat simpler functionality for creating a wizard than does WizardPanelProvider; the only advantage of WizardPanelProvider is that it does not require one to subclass a panel component).

A simple interface for providing a fixed set of panels for a wizard. To use, simply implement createPanel() to create the appropriate UI component for a given step (a unique String ID - one of the ones passed in the constructor in the steps array), and implement finish() to do whatever should be done when the wizard is finished.

To control whether the Next/Finish buttons are enabled, components created in createPanel() should call methods on the WizardController passed. The created panels should listen on the UI components they create, updating the settings Map when the user changes their input.

Super-simple one-pane wizard example - if the checkbox is checked, the user can continue:

 public class MyProvider extends WizardPanelProvider {
    public MyProvider() {
       //here we pass a localized title for the wizard, 
       //the ID of the one step it will have, and a localized description
       //the wizard can show for that one step
       super ("Click the box", "click", "Click the checkbox");
    }
    protected JComponent createPanel (final WizardController controller, String id, final Map settings) {
       //A quick sanity check
       assert "click".equals (id);
       //Remember this method will only be called once for any panel
       final JCheckBox result = new JCheckBox();
       result.addActionListener (new ActionListener() {
          public void actionPerformed (ActionEvent ae) {
             //Typically you want to write the result of some user 
             //action into the settings map as soon as they do it 
             settings.put ("boxSelected", result.isSelected() ? Boolean.TRUE : Boolean.FALSE);
             if (result.isSelected()) {
                controller.setProblem(null);
             } else {
                controller.setProblem("The box is not checked");
             }
             controller.setCanFinish(true); //won't matter if we called setProblem() with non-null
          }
       });
       return result;
    }

    protected Object finish (Map settings) throws WizardException {
       //if we had some interesting information (Strings a user put in a 
       //text field or something, we'd generate some interesting object or
       //create some files or something here
       return null;
    }
 }
 

Author:
Tim Boudreau

Constructor Summary
Modifier Constructor and Description
protected WizardPanelProvider(java.lang.String[] steps, java.lang.String[] descriptions)
          Create a WizardPanelProvider.
protected WizardPanelProvider(java.lang.String title, java.lang.String[] steps, java.lang.String[] descriptions)
          Create a WizardPanelProvider with the provided title, steps and descriptions.
protected WizardPanelProvider(java.lang.String title, java.lang.String singleStep, java.lang.String singleDescription)
          Convenience constructor to create a WizardPanelProvider which has only one step to it.
 
Method Summary
Modifier and Type Method and Description
 boolean cancel(java.util.Map settings)
          Called if the user invokes cancel.
protected abstract  javax.swing.JComponent createPanel(WizardController controller, java.lang.String id, java.util.Map settings)
          Create a panel that represents a named step in the wizard.
 Wizard createWizard()
          Create a Wizard for this PanelProvider.
protected  java.lang.Object finish(java.util.Map settings)
          Instantiate whatever object (if any) the wizard creates from its gathered data.
 java.lang.String getLongDescription(java.lang.String stepId)
          This method can optionally be overridden to provide a longer description of a step to be shown in the top of its panel.
protected  int indexOfStep(java.lang.String id)
          Convenience method to get the index into the array of steps passed to the constructor of a specific step id.
protected  void recycleExistingPanel(java.lang.String id, WizardController controller, java.util.Map wizardData, javax.swing.JComponent panel)
          The method provides a chance to call setProblem() or setCanFinish() when the user re-navigates to a panel they've already seen - in the case that the user pressed the Previous button and then the Next button.
 java.lang.String toString()
           
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait
 

Constructor Detail

WizardPanelProvider

protected WizardPanelProvider(java.lang.String[] steps,
                              java.lang.String[] descriptions)
Create a WizardPanelProvider. The passed array of steps and descriptions will be used as IDs and localized descriptions of the various steps in the wizard. Use this constructor (which passes not title) for sub-wizards used in a WizardBranchController, where the first pane will determine the title, and the titles of the sub-wizards will never be shown.

Parameters:
steps - A set of unique IDs identifying each step of this wizard. Each ID must occur only once in the array of steps.
descriptions - A set of human-readable descriptions corresponding 1:1 with the unique IDs passed as the steps parameter

WizardPanelProvider

protected WizardPanelProvider(java.lang.String title,
                              java.lang.String[] steps,
                              java.lang.String[] descriptions)
Create a WizardPanelProvider with the provided title, steps and descriptions. The steps parameter are unique IDs of panels, which will be passed to createPanel to create panels for various steps in the wizard, as the user navigates it. The descriptions parameter is a set of localized descriptions that can appear in the Wizard to describe each step.

Parameters:
title - A human readable title for the wizard dialog
steps - An array of unique IDs for the various panels of this wizard
descriptions - An array of descriptions corresponding 1:1 with the unique IDs. These must be human readable, localized strings.

WizardPanelProvider

protected WizardPanelProvider(java.lang.String title,
                              java.lang.String singleStep,
                              java.lang.String singleDescription)
Convenience constructor to create a WizardPanelProvider which has only one step to it. Mainly useful for initial steps in a WizardBranchController.

Parameters:
title - A human readable title for the wizard dialog
singleStep - The unique ID of the only step this wizard has
singleDescription - The human-readable description of what the user should do in the one step of this one-step wizard or sub-wizard
Method Detail

createPanel

protected abstract javax.swing.JComponent createPanel(WizardController controller,
                                                      java.lang.String id,
                                                      java.util.Map settings)
Create a panel that represents a named step in the wizard. This method will be called exactly once in the life of a wizard. The panel should retain the passed settings Map, and add/remove values from it as the user enters information, calling setProblem() and setCanFinish() as appropriate in response to user input.

Parameters:
controller - - the object which controls whether the Next/Finish buttons in the wizard are enabled, and what instructions are displayed to the user if they are not
id - The name of the step, one of the array of steps passed in the constructor
settings - A Map containing settings from earlier steps in the wizard. It is safe to retain a reference to this map and put values in it as the user manipulates the UI; the reference should be refreshed whenever this method is called again.
Returns:
A JComponent that should be displayed in the center of the wizard

finish

protected java.lang.Object finish(java.util.Map settings)
                           throws WizardException
Instantiate whatever object (if any) the wizard creates from its gathered data. The default implementation is a no-op that returns null.

If an instance of Summary is returned from this method, the UI shall display it on a final page and disable all navigation buttons except the Close/Cancel button.

If an instance of DeferredWizardResult is returned from this method, the UI shall display some sort of progress bar while the result is computed in the background. If that DeferredWizardResult produces a Summary object, that summary shall be displayed as described above.

The default implementation returns the settings map it is passed.

Parameters:
settings - The settings map, now fully populated with all settings needed to complete the wizard (this method will only be called if setProblem(null) and setCanFinish(true) have been called on the WizardController passed to createPanel().
Returns:
an object composed based on what the user entered in the wizard - somethingmeaningful to whatever code invoked the wizard, or null. Note special handling if an instance of DeferredWizardResult or Summary is returned from this method.
Throws:
WizardException

recycleExistingPanel

protected void recycleExistingPanel(java.lang.String id,
                                    WizardController controller,
                                    java.util.Map wizardData,
                                    javax.swing.JComponent panel)
The method provides a chance to call setProblem() or setCanFinish() when the user re-navigates to a panel they've already seen - in the case that the user pressed the Previous button and then the Next button.

The default implementation does nothing, which is sufficient for most cases. If whether this panel is valid or not could have changed because of changed data from a previous panel, or it displays data entered on previous panes which may have changed, you may want to override this method to ensure validity and canFinish are set correctly, and that the components have the correct text.

This method will not be called when a panel is first instantiated - createPanel() is expected to set validity and canFinish appropriately.

The settings Map passed to this method will always be the same Settings map instance that was passed to createPanel() when the panel was created.

If you are implementing WizardPanelProvider and some of the pages are WizardPages, you should call the super implementation if you override this method.


createWizard

public final Wizard createWizard()
Create a Wizard for this PanelProvider. The instance created by this method is cached and the same instance will be returned on subsequent calls.


getLongDescription

public java.lang.String getLongDescription(java.lang.String stepId)
This method can optionally be overridden to provide a longer description of a step to be shown in the top of its panel. The default implementation returns null, indicating that the short description should be used.

Parameters:
stepId - a unique id for one step of the wizard
Returns:
An alternate description for use in the top of the wizard page when this page is the current one, or null

indexOfStep

protected final int indexOfStep(java.lang.String id)
Convenience method to get the index into the array of steps passed to the constructor of a specific step id.


cancel

public boolean cancel(java.util.Map settings)
Called if the user invokes cancel. The default impl returns true.

Returns:
false to abort cancellation (almost all implementations will want to return true - this is really only applicable in cases such as an OS installer or such).

toString

public java.lang.String toString()
Overrides:
toString in class java.lang.Object