docking.wizard.WizardStep<T>

Type Parameters:: T - the custom data object for wizard

Direct Known Subclasses:: ProjectAccessStep, ProjectTypeStep, RepositoryStep, SelectProjectStep, ServerStep

public abstract class WizardStep<T> extends Object

This is the base class for defining a step in a WizardModel to be displayed using a WizardDialog.

A wizard dialog collects information from a user in a step by step process. Each step presents a Gui panel to the user that must be completed and validated before advancing to the next step.

Each step in the wizard must implement several methods to support the wizard step's life cycle. The basic life cycle for a step that is shown is initialize(), getComponent(), then repeated calls to isValid() and populateData() while it is showing and being modified, followed by the apply() method when moving on to the next step.

In addition, there are several methods that step's must implement that are called when the step is not showing and should not consider any Gui state that it may have (The Gui state may be stale if the user back tracked or it may never have been created or initialized) such as the isApplicable() and canFinish().

Each step must implement the following methods:

initialize(T data) - This method is called just before the step's Gui component is shown. This is were the step should use the information in the passed in data object to populate its Gui data fields. The component can be lazily created in this method if not created in the constructor, as the getComponent() will not be called before the initialize method is called. Note that the initialize method can possibly be called multiple times if the user goes back to a previous panel and then forward again.
isValid() - This method is called repeatedly while the step is showing as the step calls back to the model as any Gui component is modified. When the step reports back that it is valid, then the next and finish buttons can be enabled. Also, if valid, this step's populateData(Object) will be called so its data can be seen by follow-on steps in their canFinish(Object) calls.
canFinish(T data) - This method is called on steps that follow the current step if the current step is valid. When implementing this method, the data in the step's Gui should be ignored (it may not have been initialized yet or it may be stale if the user back tracked) and its determination if it can finish should be done purely based on the information in the passed in data object. The idea is that if a step returns true for canFinish(), it does not need to be shown before the wizard can complete.
populateData(T data) - This method is called on the current step whenever the isValid() method of the current step returns true. The step should simply transfer data from it's Gui component to the data component. It should not do any time consuming operations in this method.
apply(T data) - This method is called on each step when it is the current step and the next button is pressed. It is also called on each follow-on step when the finish button is pressed. Expensive operations should be done here when a step is completed and moving to the next step. Typically, the implementer of the apply method should perform the operation in a task. One example, might be the user is picking files to open, the populateData() method might copy the file names to the data object, but the apply() method is used to actually open the files and put them into the data object. Most wizard steps should just return true here.
isApplicable(T data) - this method is called to see if a step is applicable based on choices made in previous steps.

Constructor Summary

Constructors

Modifier

Constructor

Description

protected

WizardStep(WizardModel<T> model, String title, HelpLocation help)

Constructor
Method Summary

Modifier and Type

Method

Description

abstract boolean

apply(T data)

This method is called on the current step when advancing to the next step.

abstract boolean

canFinish(T data)

Reports true if the information in the given data object is sufficient enough that this step does not need to be shown in order to complete the wizard.

protected void

clearStatus()

Clears the current status message for this step.

protected void

dispose(T data)

Called for steps to possibly do any clean up.

abstract JComponent

getComponent()

Get the panel object

Component

getDefaultFocusComponent()

Returns the component, if any, that should receive focus when this panel is shown.

HelpLocation

getHelpLocation()

Returns the help content location for this panel.

protected String

getStatusMessage()

Returns the current status message to be displayed in the wizard dialog for this step.

String

getTitle()

Get the title for this step.

abstract void

initialize(T data)

Initialize the panel as though this is the first time it is being displayed.

boolean

isApplicable(T data)

Returns true if a step is applicable base on the information in the given data object.

abstract boolean

isValid()

Checks if the Gui component has completed and has valid information.

protected void

notifyStatusChanged()

Subclasses can call this method to notify the wizard dialog that the user made some change to the current step's Gui state.

abstract void

populateData(T data)

This method should populate the given data object with information from its Gui component.

protected void

setHelpLocation(HelpLocation help)

Sets the help location for this step.

protected void

setStatusMessage(String message)

Sets the current status message to be displayed in the wizard dialog for this step.

protected void

setTitle(String title)

Sets the title for this step.

Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Details
- WizardStep
  
  protected WizardStep(WizardModel<T> model, String title, HelpLocation help)
  
  Constructor
  
  Parameters:
  
  model - the wizard model
  
  title - the title for the wizard step (can be null and set later)
  
  help - the help location for the wizard step (can be null and set later)
Method Details
- setTitle
  
  protected void setTitle(String title)
  
  Sets the title for this step. Typically, this method is only used if the title is data dependent.
  
  Parameters:
  
  title - the new title for the step.
- setHelpLocation
  
  protected void setHelpLocation(HelpLocation help)
  
  Sets the help location for this step. Typically, this method is only used if the help is data dependent.
  
  Parameters:
  
  help - the new help location for the step.
- initialize
  
  public abstract void initialize(T data)
  
  Initialize the panel as though this is the first time it is being displayed. This is where the step should initialize all Gui fields from the given data object.
  Creating the Gui component can be done lazily in this method if not done in the constructor, as the initialize() method will always be called before the getComponent() method is called. Just be careful as this method can be called multiple times if the user backtracks in the wizard dialog.
  
  Parameters:
  
  data - the custom wizard data containing the information from all previous steps.
- isValid
  
  public abstract boolean isValid()
  
  Checks if the Gui component has completed and has valid information. Typically, whenever the Gui state changes, it notifies the model using the statusChangedCallback, which in turn will call the isValid() method on the current step. If the current step is valid, it will in turn trigger additional calls to follow-on steps to see if the wizard can finish.
  
  Returns:
  
  true if the Gui component has completed and valid information and is eligible to continue to the next step.
- canFinish
  
  public abstract boolean canFinish(T data)
  
  Reports true if the information in the given data object is sufficient enough that this step does not need to be shown in order to complete the wizard. It is only called on steps subsequent to the current step. Wizard steps should only make their decisions based on the information in the data object and not their internal GUI, which might not have even been initialized at this point. This method is only called on steps whose isApplicable(Object) method returns true.
  
  Parameters:
  
  data - the custom wizard data containing the information from all previous steps.
  
  Returns:
  
  true if this step does not need to be shown before completing the wizard
- populateData
  
  public abstract void populateData(T data)
  
  This method should populate the given data object with information from its Gui component.
  
  Parameters:
  
  data - the custom wizard data containing the information from all previous steps.
- apply
  
  public abstract boolean apply(T data)
  
  This method is called on the current step when advancing to the next step. It is also called on all subsequent steps when finishing the wizard as those steps are skipped because the finish button was pressed. This method is for steps to perform more extensive operations when moving on to subsequent steps. Most steps can just return true here as simple data will be added during the populateData(Object) method.
  
  Parameters:
  
  data - the custom wizard data containing the information from all previous steps.
  
  Returns:
  
  true if the apply completes successfully.
- isApplicable
  
  public boolean isApplicable(T data)
  
  Returns true if a step is applicable base on the information in the given data object. Data from previous steps may make a subsequent step applicable or not.
  
  Parameters:
  
  data - the custom wizard data containing the information from all previous steps.
  
  Returns:
- getComponent
  
  public abstract JComponent getComponent()
  
  Get the panel object
  
  Returns:
  
  JPanel panel
- getTitle
  
  public String getTitle()
  
  Get the title for this step.
  
  Returns:
  
  the title for this step
- getHelpLocation
  
  public HelpLocation getHelpLocation()
  
  Returns the help content location for this panel.
  
  Returns:
  
  String help location for this panel; return null if default help location should be used.
- getDefaultFocusComponent
  
  public Component getDefaultFocusComponent()
  
  Returns the component, if any, that should receive focus when this panel is shown.
  
  Returns:
  
  the component, if any, that should receive focus when this panel is shown; null if no preferred focus component exists.
- getStatusMessage
  
  protected String getStatusMessage()
  
  Returns the current status message to be displayed in the wizard dialog for this step.
  
  Returns:
  
  the current status message to be displayed in the wizard dialog for this step.
- setStatusMessage
  
  protected void setStatusMessage(String message)
  
  Sets the current status message to be displayed in the wizard dialog for this step.
  
  Parameters:
  
  message - the message to display in the wizard dialog
- clearStatus
  
  protected void clearStatus()
  
  Clears the current status message for this step.
- notifyStatusChanged
  
  protected void notifyStatusChanged()
  
  Subclasses can call this method to notify the wizard dialog that the user made some change to the current step's Gui state. This will trigger calls to the isValid() and possibly populateData(Object)
- dispose
  
  protected void dispose(T data)
  
  Called for steps to possibly do any clean up.
  
  Parameters:
  
  data - the custom data object

Class WizardStep<T>

Constructor Summary

Method Summary

Methods inherited from class java.lang.Object

Constructor Details

WizardStep

Method Details

setTitle

setHelpLocation

initialize

isValid

canFinish

populateData

apply

isApplicable

getComponent

getTitle

getHelpLocation

getDefaultFocusComponent

getStatusMessage

setStatusMessage

clearStatus

notifyStatusChanged

dispose