Defining Wizard Pages

You must extend the abstract class jas.util.JASWizardPage, which extends JPanel.   There are two interfaces that your class may typically implement.  Implelent jas.util.HasNextPages if your wizard could potentially lead to other pages, and implement jas.util.Finishable if your page could potentially be the final page on the wizard.   You may implement one or both, but it would be unusual to implement neither, because then your page would be a 'dead end' where nothing can happen from it.

Notes on Extending jas.util.JASWizardPage

• You must provide to the super constructor a layout manager for the page.  For example, you might have
  final class HippoWizardPage extends jas.util.JASWizardPage implements jas.util.Finishable
{
    HippoWizardPage()
    {
       super( new java.awt.BorderLayout() );
       // other constructor code
    }
}
In the remainder of the constructor body, set up the page by calling the add(..) method, just as you would normally add components to a JPanel.  The package jas.util has a number of useful components that you can use in addition to the swing classes.   See the documentation on the jas.util convenience classes.
• The wizard has a next button that links to the next page in the sequence, and it has a finish button that closes the wizard once all user input has been collected.   Whether these buttons are enabled is controlled by the definitions given for these methods:
  protected boolean getNextEnabled()
protected boolean getFinishEnabled()
  • By default, getNextEnabled() returns true for an class that implements jas.util.HasNextPages and false otherwise, and getFinishEnabled() returns true for a class that implements jas.util.Finishable and false otherwise.  However, you can override these methods to provide customized functionality.  The methods getNextEnabled() and getFinishEnabled() are called once when the page is brought to the screen, but are called again every time doEnable() is called.  You can call doEnable() whenever you want, but a built-in function described in the next section allows you to have doEnable() called for each key event on one or more components on the page.
  • Note that no matter how you override the above mehtods, the 'Next' button will never be enabled for a page that does not implement jas.util.HasNextPages, and the 'Finish' button will never be enabled for a page that does not implement jas.util.Finishable.   Therefore, there is no point in overriding getNextEnabled() if you do not implement jas.util.HasNextPages, and there is no point in overriding getFinishEnabled() if you do not implement jas.util.Finishable.
• JASWizardPage implements the java.awt.event.KeyListener interface with virtual non-final methods (which means that you can override them if you wish, and have something different happen when a key event is generated).  You do not have to use this implementation if you don't want to.  If you add a JASWizardPage as a KeyListener to a Componrnt (a JTextField, for example), the doEnable() method is called every time a key is released, and the page updates the button states according to the getNextEnabled() and getFinishEnabled() implementations.  Therefore, if you have two text fields and you want the 'Next' button to be enabled when there is at least one letter in each, you might do something like this:
  import com.sun.java.swing.*;
final class HippoWizardPage extends JASWizardPage implements HasNextPages
{
    HippoWizardPage()
    {
        super( new java.awt.GridLayout(2, 2) );
        m_fieldA = new JTextField();
        m_fieldB = new JTextField();
        add( new JLabel("A: ") );
        add(m_fieldA);
        add( new JLabel("B: ") );
        add(m_fieldB);

        fieldA.addKeyListener(this);
        fieldB.addKeyListener(this);
    }
    protected boolean getNextEnabled()
    {
        return m_fieldA.getText().length() > 0 && m_fieldB.getText().length() > 0;
    }
    private final JTextField m_fieldA, m_fieldB;
}
• Override the method
public void onCancel()
if there is some cleanup you have to do if the user clicks cancel.  (The default definition of this method does nothing.)  For example, if one page opened a file, it would be appropriate to close the file in the onCancel() method.  Note that the onCancel() method is called on each page that is part of the wizard, following a preorder traversal of the tree structure (i.e., it does the last levels first and works back to the root through each branch).
• Override the method
  public void beforeShowing()
  if there is some final setup you want done before your page is shown.  This method is called each before time a page is shown.

Notes on implementing jas.util.Finishable

• All you have to do is provide a definition for
  public void onFinish()
  which is called when the user clicks on the 'Finish' button.
  • If the user has specified options on previous pages, you must somehow access these variables to use them in the onFinish() method.  The easiest way to do this is to make one page an internal or nested class of all the previous pages.  In Java, an internal class inherits all variables and methods (even the private ones) from the external class.
  • If an error is generated in the onFinish() method (for example, a file that the user specified could not be opened), simply return from the method without calling dispose() and the wizard will remain on the screen as the user left it.  Of course you should notify the user of the error (I recommend the class JOptionPane for this).
  • You must call dispose() if you wish to have the wizard disappear.  Normally you would call dispose() at the end of the onFinish() method if no errors occurred during its execution.
  • Override the default definition for the method getFinishEnabled() if you would like to control whether the 'Finish' button is enabled.

Notes on implementing jas.util.HasNextPages

• You must provide a list of the possible next pages.  These pages must be returned in an array by the method
  public JASWizardPage[] getNextWizardPages()
This method will be called before the wizard appears on the screen so that the dialog can assume the correct size and shape for all of the possible pages.
• When the user clicks on the 'Next' button, the method
  public JASWizardPage getNext()
  will be called.  Obviously, if there is only one possible next page, then return that page.  If, however, there are several possiblilties, determine from user input which is appropriate.  You know that when this method is called, the user is finished with the current page.   You may wish at this point to check the validity of the user's input (e.g., check if a given file name exists).  If an error occurs (e.g., the file given does not exist), return null from this method, and the wizard will remain on the same page.  Of course you should notify the user of the error (I recommend the class JOptionPane for this).  You may also wish to pass on user specifications to the next page, so that object is aware of what the user has specified on previous pages.  Do not return from this method an object that was not in the array returned by getNextWizardPages().
• Override the default definition for the method getNextEnabled() if you would like to control whether the 'Next' button is enabled.

Page maintained by Jonas Gifford.   Last updated 01/14/04.