Package ca.spatial.util

Class WizardPane

java.lang.Object
java.awt.Component
java.awt.Container
javax.swing.JComponent
javax.swing.JPanel
ca.spatial.util.WizardPane
All Implemented Interfaces:
WizardCompletionTester, ActionListener, ImageObserver, MenuContainer, Serializable, EventListener, Accessible, ChangeListener, DocumentListener, ListSelectionListener, TableModelListener, TreeSelectionListener
public class WizardPane extends JPanel implements ActionListener, ChangeListener, DocumentListener, ListSelectionListener, TableModelListener, TreeSelectionListener, WizardCompletionTester
A WizardPane represents a panel that can contain elements that display values and obtain user input.

A WizardPane is simply a container (JPanel) having additional methods that support convenient addition of input fields, check boxes, file choosers, number spinners, etc. These input methods are pre-connected with a set of event handlers. When a value is changed in the user interface, the event handlers will perform error checking and set the value in the Wizard dictionary.

Each input field is associated with a variable label. The varaible label is the key that is used to retrieve the value from the dictionary.

Here are some of the controls that are supported by the WizardPane

WizardPane methods
MethodPurposeImplemented by
addLabelAdd a centered labelJLabel
addSpaceAdd white space between elementsBox
addTextAdd a text input field, surrounded by a bordered frameJTextField
addTextAreaAdd a text input area, surrounded by a bordered frameJTextArea
addBooleanAdd a checkboxJCheckBox
addIntegerAdd a number spinner for integersJSpinner
addDoubleAdd a number spinner for doublesJSpinner
addComboBoxAdd a ComboBox type of widget to select a single item from a listJComboBox
addListBoxAdd a List type of widget to select multiple items from a listJList
addExpressionAdd a combination of text entry and query builderQueryBuilder
addFileAdd a file selector, including a file selection dialogJFileChooser
addCoverageAdd a coverage selector, including a coverage selection dialogJFileChooser
addPanelAdd a bordered frame, and within it a nested WizardPaneWizardPane
addOptionAdd a checkbox and a nested WizardPane. The checkbox controls if the nested pane is enabled or disabled.WizardPane
addTabbedPaneAdd a tabbed pane. WizardPane objects are used to implement each tab.WizardTabbedPane
addProgressBarAdd a progress bar.JProgressBar
addTreeAdd a tree widget.PathTree
addButtonAdd a button.JButton
addToggleButtonAdd a toggle button.JToggleButton
addExclusiveOptionAdd a group of radio buttons that provide a set of mutally exclusive options.JRadioButton
addTableAdd a simple table widget.JTable
addColorAdd a color chooser.JColorChooser

WizardPane panels are usually used as a sequence of 'steps' in in a wizard. The flow of control is handled by the Wizard object that contains the WizardPanes. The order of the steps is defined by chaining one WizardPane to the next. The first WizardPane in the sequence is obtained from the Wizard object, using the Wizard.getFirstStep() method. Subsequent steps in the sequence are generated by successively using the addNextStep() method in each WizardPane in the chain.

The sequence of steps in a Wizard is usually linear. Forks in the sequence can be generated using the addExclusiveOption(java.lang.String, java.lang.String) method.

A WizardPane object can be embedded inside another WizardPane. This is convenient to allow enabling and disabling of groups of components.

See Also:
Wizard, Serialized Form

  • Field Details

  • Constructor Details

    • WizardPane

      public WizardPane​(Wizard wiz)
      Construct a new WizardPane opbject, specifying the parent wizard that contains the dictionary and controls the flow of steps.
      Parameters:
      wiz - the parent Wizard

  • Method Details

    • isComplete

      public boolean isComplete​(Wizard wiz)
      Specified by:
      isComplete in interface WizardCompletionTester

    • setIcon

      public void setIcon​(Icon icon)

    • getIcon

      public Icon getIcon()

    • addLabel

      public JLabel addLabel​(String text)
      Add a display label to the pane. The display text can be HTML and will be centered in the display area.
      Parameters:
      text - The text to display
      Returns:
      The JLabel component the implements the display

    • addText

      public JTextField addText​(String label, String var, String init)
      Add a text input field, surrounded by a bordered frame.
      Parameters:
      label - A label to be displayed in the bordered frame
      var - The dictionary key associated with the result.
      init - The initial value to be placed in the field.

    • addTextArea

      public JTextArea addTextArea​(String label, String var, String init)
      Add a text input area, surrounded by a bordered frame.
      Parameters:
      label - A label to be displayed in the bordered frame. If the label is null then no border is added.
      var - The dictionary key associated with the result.
      init - The initial value to be placed in the field.

    • addHTML

      public void addHTML​(String label, String var, ReportWriter rw, String folder, String init)
      Add an HTML edit area, surrounded by a bordered frame.
      Parameters:
      label - A label to be displayed in the bordered frame. If the label is null then no border is added.
      var - The dictionary key associated with the editor.
      rw - A reference to the ReportWriter object that will be the container for the associated report, or null if this wizard is not being used for a report.
      folder - the folder that the report will be placed in to, or null if this wizard is not being used for a report.
      init - The initial value to be placed in the editor.

    • addBoolean

      public JCheckBox addBoolean​(String label, String var, boolean def)
      Add a checkbox for booleans
      Parameters:
      label - A label to be displayed to the left of the checkbox
      var - The dictionary key associated with the result.
      def - The initial value to be placed in the field.
      Returns:
      A reference to the JCheckBox object

    • addInteger

      public JSpinner addInteger​(String label, String var, int init, int low, int high, int step)
      Add a number spinner for integers
      Parameters:
      label - A label to be displayed to the left of the spinner
      var - The dictionary key associated with the result.
      init - The initial value to be placed in the field.
      low - The lower range for the spinner
      high - The upper range for the spinner
      step - The step size for the spinner
      Returns:
      A reference to the JSpinner object

    • addDouble

      public JSpinner addDouble​(String label, String var, double init, double low, double high, double step)
      Add a number spinner for doubles.
      Parameters:
      label - A label to be displayed to the left of the spinner
      var - The dictionary key associated with the result.
      init - The initial value to be placed in the field.
      low - The lower range for the spinner
      high - The upper range for the spinner
      step - The step size for the spinner
      Returns:
      A reference to the JSpinner object

    • addComboBox

      public JComboBox addComboBox​(String label, String var, Object init, Object[] def)
      Add a ComboBox type of widget to select items from a list.
      Parameters:
      label - A label to be displayed to the left of the ComboBox
      var - The dictionary key associated with the result.
      init - The initial selected value to be placed in the field.
      def - A list of objects that will be displayed in the ComboBox
      Returns:
      A reference to the JComboBox object

    • addListBox

      public JList addListBox​(String label, String var, Object[] init, Object[] def)
      Add a ListBox type of widget to select items from a list. The default ListBox supports multiple selections. If you want singel selections then
      • set the JList selection mode to ListSelectionModel.SINGLE_SELECTION
      • set the item in the dictionary to the correct value (by default it will contain an array).
      Here is an example: 
        Object[] stores = new Object[] {"a", "b", "c"};
  JList jl = wp.addListBox("Select", "table", new Object[] {"a"}, stores);
  jl.setSelectionMode(ListSelectionModel.SINGLE_SELECTION);
  wiz.putItem("table", "a");
      Parameters:
      label - A label to be displayed in a border surrounding the list.
      var - The dictionary key associated with the result.
      init - The initially values to be selected in the list.
      def - The initial list of objects
      Returns:
      A reference to the JList object

    • addExpression

      public JTextField addExpression​(String label, String var, String def, AttributeStore as)
      Add an expression input field, with a query builder button
      Parameters:
      label - A label to be displayed in a border surrounding the input field.
      var - The dictionary key associated with the result.
      def - The initial expression.
      as - An AttributeStore object that the expression will be compiled against.
      Returns:
      A reference to the JTextField object that will contain the expression string.

    • addFile

      public WizardFetch addFile​(String label, String var, Object def, int type)
      Add a file selection entry
      Parameters:
      label - A label to be displayed in a border surrounding the input field.
      var - The dictionary key associated with the result.
      def - The initial file value.
      type - A constant value indicating the type of file open operation. The value should be one of FILE_OPEN, FILE_SAVE, DIRECTORY_OPEN, or DIRECTORY_SAVE.
      Returns:
      A reference to the file selection control. You can use the control to add filters and other custom file selection behaviour.

    • addCoverage

      public void addCoverage​(String label, String var, Object def)
      Add a coverage selection entry
      Parameters:
      label - A label to be displayed in a border surrounding the input field.
      var - The dictionary key associated with the result.
      def - The initial coverage value.

    • addCoverage

      public void addCoverage​(String label, String var, Object def, int type)

    • addOpenTable

      public JList addOpenTable​(String label, String var, AttributeStore def, Class type)

    • addSpace

      public void addSpace()
      Add some space between entries. This space is implemented using Box.createVerticalGlue(), so it will expand to consume any leftover space in the panel.

    • addOption

      public WizardPane addOption​(String label, String var, boolean def)
      Add a sub-pane, with a check box that enables and disables the embedded controls. When you add this control you will receive a reference to another WizardPane. You can add more controls to that sub-pane. When the checkbox is check all controls in the sub-pane are enabled. When the checkbox is unchecked then all controls in the sub-pane become disabled.
      Parameters:
      label - A label to be displayed in a border surrounding the sub-pane. If the label starts with a | character then the panel will be surrounded with a border.
      var - The dictionary key associated with whether the sub-pane is enabled or disabled.
      def - The initial value of the checkbox.
      Returns:
      A reference to a Wizardpane object, that can then be filled with other controls.

    • addOption

      public WizardPane addOption​(String label, String var, boolean def, boolean expand)
      Add a sub-pane, with a check box that enables and disables the embedded controls. When you add this control you will receive a reference to another WizardPane. You can add more controls to that sub-pane. When the checkbox is check all controls in the sub-pane are enabled. When the checkbox is unchecked then all controls in the sub-pane become disabled.
      Parameters:
      label - A label to be displayed in a border surrounding the sub-pane. If the label starts with a | character then the panel will be surrounded with a border.
      var - The dictionary key associated with whether the sub-pane is enabled or disabled.
      def - The initial value of the checkbox.
      expand - A boolean to indicate if the panel should expand to take all extra space.
      Returns:
      A reference to a Wizardpane object, that can then be filled with other controls.

    • addPanel

      public WizardPane addPanel​(String label, boolean expand)
      Add a sub-panel, with an optional titled border. This is used for grouping.
      Parameters:
      label - A label to be displayed in a border surrounding the sub-pane.
      expand - Controls if the sub-panel should be expanded to consume all left-over space in the parent pane.
      Returns:
      A WizardPane object that can then be filled with additional controls.

    • addTabbedPane

      public WizardTabbedPane addTabbedPane()
      Add a Tabbed panel to the container. Use the returned WizardTabbedPane object to set up the tabs to be displayed.

    • addProgressBar

      public JProgressBar addProgressBar()
      Add a progress bar widget.

    • addTree

      public JTree addTree​(String label, String var, PathTree model, boolean single)
      Add a tree widget. This Object does not create a variable, but puts up a control that can be used to manipulate the PathTree structure.
      Parameters:
      label - A label to be displayed in a border surrounding the tree widget.
      var - A dictionary key, not currently associated with anything.
      model - A data model to be used with the Tree.
      single - A flag to indicate if single or musltiple selections are allowed

    • addButton

      public JButton addButton​(String label)
      Add a button. There are no default actions on the button.
      Parameters:
      label - A label to be displayed to the left of the button.
      Returns:
      A reference to the JButton object.

    • addToggleButton

      public JToggleButton addToggleButton​(String label)
      Add a toggle button. There are no default actions on the button.
      Parameters:
      label - A label to be displayed to the left of the button.
      Returns:
      A reference to the JButton object.

    • addNextStep

      public WizardPane addNextStep()
      Add a 'next' step to follow the current step.
      Returns:
      A reference to the WizardPane object that will be chained to the current step.

    • setNextStep

      public WizardPane setNextStep​(WizardPane step)
      Set a 'next' step to follow the current step. Any existing next step will be forgotten.
      Parameters:
      step - The step that should override the currently established following step.
      Returns:
      The new following step.

    • setPrev

      public void setPrev​(WizardPane prev)

    • addExclusiveOption

      public JRadioButton addExclusiveOption​(String label, String group)
      Add a set of radio buttons to display mutally exclusive options. The wizard dictionary will contain a string item with a key of "_EXCLUSIVE_"+group that will hold the label of the currently selected fork.
      Parameters:
      label - A label to be displayed to the right of the radio button.
      group - The name of the group object.
      Returns:
      The JRadioButton object.

    • addTable

      public JTable addTable​(String label, String var, TableModel model, boolean addRows)
      Add a table widget to the panel. The resulting table will have edit controls if the TableModel is an instance of EditableTableModel.
      Parameters:
      label - A label to be displayed in a border surrounding the table widget.
      var - A dictionary key, not currently associated with anything.
      model - A data model to be used with the JTable. If the TableModel implements the EditableTableModel interface then the widget will display editing controls.
      addRows - Indicate if controls for adding rows should be added to the widget. This only works if the TableModel object implements the EditableTableModel interface.
      Returns:
      The JTable widget that displays records from the TableModel.

    • addTable

      public JTable addTable​(String label, String var, TableModel model, boolean addRows, boolean upDown)

    • tableWithControls

      public static JTable tableWithControls​(JPanel jp, TableModel model, boolean addRows, boolean upDown, boolean isEnabled)

    • addColor

      public JButton addColor​(String label, String var, Color def)
      A color selector widget.

    • hasNext

      public boolean hasNext()
      Test if there is a following step. This returns false if this is the last step in the sequence.

    • getNext

      public WizardPane getNext()
      Get a reference to the next step.

    • getLastStep

      public WizardPane getLastStep()

    • hasPrev

      public boolean hasPrev()
      Test if there is a preceeding step. This returns false if this is the last step in the sequence.

    • getPrev

      public WizardPane getPrev()
      Get a reference to the preceeding step.

    • actionPerformed

      public void actionPerformed​(ActionEvent e)
      Specified by:
      actionPerformed in interface ActionListener

    • stateChanged

      public void stateChanged​(ChangeEvent e)
      Specified by:
      stateChanged in interface ChangeListener

    • valueChanged

      public void valueChanged​(ListSelectionEvent e)
      Specified by:
      valueChanged in interface ListSelectionListener

    • valueChanged

      public void valueChanged​(TreeSelectionEvent e)
      Specified by:
      valueChanged in interface TreeSelectionListener

    • insertUpdate

      public void insertUpdate​(DocumentEvent e)
      Specified by:
      insertUpdate in interface DocumentListener

    • removeUpdate

      public void removeUpdate​(DocumentEvent e)
      Specified by:
      removeUpdate in interface DocumentListener

    • changedUpdate

      public void changedUpdate​(DocumentEvent e)
      Specified by:
      changedUpdate in interface DocumentListener

    • tableChanged

      public void tableChanged​(TableModelEvent e)
      Specified by:
      tableChanged in interface TableModelListener

    • updateTableListeners

      public static void updateTableListeners​(AbstractTableModel oldModel, AbstractTableModel newModel)
      Update the listeners when a table model is replaced in table widget.
      Parameters:
      oldModel - The old model that should be removed
      newModel - The new model that should be added

    • setEnabled

      public void setEnabled​(boolean state)
      Enable or disable the components on this pane
      Overrides:
      setEnabled in class JComponent
      Parameters:
      state - The new state of the components

    • setCompletionTest

      public void setCompletionTest​(WizardCompletionTester vt)
      Set the completion tester for this pane
      Parameters:
      vt - The tester to use to determine if the values entered in this pane are valid.

    • setNavigateAction

      public void setNavigateAction​(WizardNavigateAction ac)
      Set an action to perform when entering or leaving this pane
      Parameters:
      ac - The action to carry out

    • getWizard

      public Wizard getWizard()
      Get the Wizard object for this item
      Returns:
      A reference to the Wizard object

    • test

      public boolean test()
      Test the value of top-most pane. This implies that completion testers are not allowed on Panel or Option sub-panes. (TabbedPanes are OK because they are not sub-panes).
      Returns:
      true if the test succeeds

    • setHelp

      public void setHelp​(String topic)
      Set the custom help associated with this WizardPane. The custom help will be available only on this pane. Note that this help reference is not dynamic. You must set the help before the pane is shown. If you change the help while the pane is being shown the status of the button will not change.
      Parameters:
      topic - The help topic to display

    • getHelp

      public String getHelp()
      Get information about the custom help topic set for this pane.
      Returns:
      a custom help string