Package ca.spatial.util

Class Wizard

java.lang.Object
java.awt.Component
java.awt.Container
javax.swing.JComponent
javax.swing.JPanel
ca.spatial.util.Wizard
All Implemented Interfaces:
ActionListener, ImageObserver, MenuContainer, Serializable, EventListener, Observer, Accessible
public class Wizard extends JPanel implements ActionListener, Observer
This class contains a 'wizard' style component. A Wizard is a specialized JPanel component. Typically you would not instantiate a wizard directly, but instead you would create a WizardDialog or WizardFrame, and then access the Wizard that is embedded inside of those objects.

A Wizard should contain one or more steps. Steps are encapsulated in WizardPane objects. WizardPane's are panels on which you may add instructions and input controls. You would not usually add components directly to the panel, instead use the WizardPane methods to control how specialized components are added to the panes. The specialized controls include text input fields, combo boxes, lists, file choosers, etc., and include the event handlers needed to capture the input.

The first step (pane) in the process can be retrieved from the Wizard using the getFirstStep() method. Subsequent steps are chained to each WizardPane, and are created using the WizardPane.addNextStep() method. Ultimately a wizard is composed of a frame or dialog and a chain of WizardPanes.

Progress from step to step can be controlled through the use of WizardCompletionTester completion test handlers. These test handlers can be assigned to each step, or to the component as a whole. The test handlers will be called each time a control is changed, and each time a pane is entered. A global test handler will control the behaviour of the finish button. If the handler returns true, the finish button will be enabled. If false, the finish button will be disabled.

If a completetion test handler is assigned to a step, it will control the behaviour of the next button. If the test handler on the step returns true then the next button will be enabled. If false, the next button will be disabled. Step handlers are only invoked if the step is visible. If the final step is visible, the step handler will also control the behaviour of the finish button.

After configuring the steps, call start to activate the wizard. The start2() method will return with either FINISHED or CANCELLED depending on the method of termination. After the wizard has terminated use the get() methods to extract values. Alternatively, the translate(String) method provides a convenient way to interpolate values into a string.

You may optionally assign a task to be run when the finish button on the wizard is clicked. The task is specified as an object that implements the Runnable interface. In this case the wizard will display a interterminable JProgressBar. If the obs parameter is non-null, a determinate progress bar will be used instead.

See Also:
WizardPane, WizardFrame, WizardDialog, Serialized Form

  • Field Details

  • Constructor Details

    • Wizard

      public Wizard​(Window parent, Icon appIcon)
      The only constructor. Most applications should not instantiate this directly, but should instead use WizardDialog or WizardFrame.

  • Method Details

    • getParentWindow

      public Window getParentWindow()
      Get a reference to the parent window container for this Wizard.

    • getAppIcon

      public Icon getAppIcon()

    • setContent

      public void setContent​(Component component)
      Set the component inside the content pane. Most applications will not use this method.
      Parameters:
      component - The component to display inside of the wizard.

    • setFinalTask

      public void setFinalTask​(String label, Runnable task, Observable obs)
      Set the task that will be executed when the finish button is clicked.
      Parameters:
      label - A String label to be displayed above the progress bar.
      task - A object of type Runnable that will be invoked when the finish button is clicked.
      obs - A object of type Observable that will emit progress notifications from the final task. This value may be null, in which case the progress bar will be indeterminant-style. The argument passed in the notification event shold be an Integer in the range of 0 to 100.

    • setHelp

      public void setHelp​(String topic)
      Set the default help associated with this wizard. The default help will be available on every pane, unless overridden by the custom help on an individual panel.
      Parameters:
      topic - The help topic to display

    • setStatus

      public void setStatus​(String message)
      Set a status message to be displayed on the bottom of the wizard, just above the navigation buttons.
      Parameters:
      message - The status message to display.

    • setStatusOk

      public boolean setStatusOk()

    • setCloseWhenFinished

      public void setCloseWhenFinished​(boolean state)
      Set a flag so that the window will automatically close when the task is finished. The default value is true.

    • getCloseWhenFinished

      public boolean getCloseWhenFinished()

    • requestClose

      public void requestClose()
      Request the window be closed. This will call the interrupt mechanism first.

    • update

      public void update​(Observable object, Object arg)
      Implements Observer interface to listen to progress messages from the final task. If the final task has set an Observable object, then this method will receive the notifications. The argument from the Observable is expected to be an Integer object that ranges in value between 0 and 100. The progress bar will be set to the resulting value.
      Specified by:
      update in interface Observer

    • setStatus

      public void setStatus​(int status)
      Set the status code. Applications should usually not set the status code. Valid values are FINISHED or CANCELLED.

    • getStatus

      public int getStatus()
      Get the status code. Values are FINISHED or CANCELLED.

    • setCompletionTest

      public void setCompletionTest​(WizardCompletionTester test)
      Set a global conpletion test that will determine when the finish button is enabled. If the value is null, then the finish button will be enabled when the last step is visible and the step completion handler (if not null) returns true. If non-null, the finish button will be enabled if the current step completion handler returns true and the global completion handler returns true.

    • setCurrentPane

      public void setCurrentPane​(WizardPane pane)
      Programatically set the current pane. Do not automatically execute leave and entry actions. Caller is responsible to set up 'pane.prev' and 'currentPane.next' relationships.

    • getCurrentPane

      public WizardPane getCurrentPane()
      Get the current pane in this wizard.

    • putItem

      public void putItem​(String label, Object value)
      Set a data value in the wizard. Applications should generally not need to do this, but if they do they should take care. If you update a value that is being used by a control, the control will not update.

    • removeItem

      public Object removeItem​(String label)
      Remove a data value from the wizard.

    • getItem

      public Object getItem​(String label)
      Retrieve an attribute from the wizard.
      Parameters:
      label - A string label used as a key to retrieve a stored value from the wizard
      Returns:
      An object reference to the stored value.

    • isDefined

      public boolean isDefined​(String label)
      Test if the key is found in the dictionary
      Parameters:
      label - A string label used as a key to retrieve a stored value from the wizard

    • getComponent

      public JComponent getComponent​(String var)

    • isEnabled

      public boolean isEnabled​(String var)

    • getInt

      public int getInt​(String label)
      Retrieve an integer value from the wizard.
      Parameters:
      label - A string label used as a key to retrieve a stored value from the wizard
      Returns:
      An int-valued interpretation of the stored object.

    • getDouble

      public double getDouble​(String label)
      Retrieve a double value from the wizard.
      Parameters:
      label - A string label used as a key to retrieve a stored value from the wizard
      Returns:
      A double-valued interpretation of the stored object.

    • getBoolean

      public boolean getBoolean​(String label)
      Retrieve a boolean value from the wizard.
      Parameters:
      label - A string label used as a key to retrieve a stored value from the wizard
      Returns:
      A boolean-valued interpretation of the stored object.

    • getString

      public String getString​(String label)
      Retrieve a string value from the wizard.
      Parameters:
      label - A string label used as a key to retrieve a stored value from the wizard
      Returns:
      A string-valued interpretation of the stored object.

    • getFile

      public File getFile​(String label)
      Retrieve a File value from the wizard.
      Parameters:
      label - A string label used as a key to retrieve a stored value from the wizard
      Returns:
      A file-valued interpretation of the stored object.

    • getIntArray

      public int[] getIntArray​(String label)

    • getFirstStep

      public WizardPane getFirstStep()
      Return the initial step of the Wizard
      Returns:
      The first WizardPane object in the chain of steps for this wizard.

    • resetFirstStep

      public WizardPane resetFirstStep()
      Reset the wizard with a new (blank) first step. All other steps are lost.
      Returns:
      A new WizardPane object.

    • setFirstStep

      public WizardPane setFirstStep​(WizardPane step)
      Set the wizard with a new first step. The current first step (and all others that are chained to it) will be discarded.
      Parameters:
      step - The step that is to be used as the first step in this wizard.
      Returns:
      The reference to the first step.

    • start2

      public void start2()
      Start the wizard. This will set the first pane, set up the navigation buttons, and show the the containing frame or dialog.

      If this is a dialog then this method will not return until the wizard has completed its actions and the window has been closed. If it is a frame then it will return right away.

      The window will close upon the following conditions:

      • the setCloseWhenFinished method has been set to true (default)
      • the cancel or intterupt buttons have been pressed.
      • the finish button has been clicked, and the final task (if any) has completed on a background thread.
      If the setCloseWhenFinished method has bee set to false then the window will not close after these events. This can only be set on frames because dialogs would permanently block if their window could not close.

      Due to Swing threading rules this method must be invoked from the event dispatch thread.

      See Also:
      setFinalTask(java.lang.String, java.lang.Runnable, java.util.Observable)

    • actionPerformed

      public void actionPerformed​(ActionEvent e)
      The ActionListener interface is implemented in this class to catch the events generated by the navigation buttons on the main panel.
      Specified by:
      actionPerformed in interface ActionListener

    • translate

      public String translate​(String command)
      Translate a string by replacing all sequences of %var% with the value of variable 'var' taken from the attribute hash table.

      If an attribute has not been defined then an empty string will be returned instead.

      Parameters:
      command - A String containing embedded substitution symbols. Each substitution symbol is of the form %var% where var is the label of the variable.
      Returns:
      An interpolated string containing the results of the symbol substitution.