sos.wizard
Class DefaultWizardModel

java.lang.Object
  |
  +--sos.wizard.AbstractModel
        |
        +--sos.wizard.AbstractWizardModel
              |
              +--sos.wizard.DefaultWizardModel

All Implemented Interfaces:

javax.swing.ComboBoxModel, javax.swing.ListModel, Model, java.io.Serializable, WizardModel

public class DefaultWizardModel

extends AbstractWizardModel

implements java.io.Serializable

A general-purpose wizard model that can handle both static (unconditional) and dynamic (conditional) pages.

The model maintains a list of pages, their corresponding transitions, and a current position. When stepNext is called, the model applies the transition corresponding to the current page and then increments its position. When stepBack is called, the model decrements its position and then applies the transition corresponding to the revisited page. When it reaches the page that is denoted as "last", the finish operation becomes enabled. When the finish operation is executed, the model runs the finish task and optionally sets the current page to a "progress page." If the task completes successfully, the model optionally sets the current page to a summary page.

To establish the sequence of pages that this wizard model should step the user through, use addLast, push, and removeLast. To denote a page as the "last" page, use setLastPage. To set the summary page, use setSummaryPage.

Static Model

If the wizard pages are known upfront and do not change based on the user's input, then you have a static model. You do not need to concern yourself with transitions. You can make use of the constructor that takes all the pages upfront, as in the following example:

   // create the pages
   Page page1 = ...
   Page page2 = ...
   Page page3 = ...

   // store the pages in an array
   Page[] pages = new Page[3];
   pages[0] = page1;
   pages[1] = page2;
   pages[2] = page3;

   // create the wizard's task
   Task task = ...

   // create the optional summary page
   Page summaryPage = ...

   // create the static model
   WizardModel model = new DefaultWizardModel( pages, task, summaryPage );
 

Dynamic Model

If the sequence of pages depends on the user's input, then you have a dynamic model and must supply custom transitions. For each page that influences the model, you provide an action to carry out when the user leaves that page. This action is allowed to modify the model dynamically. The typical action will create new pages, insert them into the model, and update the finish task and last page as appropriate. The following skeleton demonstrates this:

   // create an empty model
   final DefaultWizardModel model = new DefaultWizardModel();

   // create the first page, which will determine
   // subsequent pages
   final CustomPage page1 = ...

   // create a transition that will update the model
   // depending on the user's choice in page 1
   DefaultWizardModelTransition transition 
                     = new DefaultWizardModel.TransitionAdapter() {
     public void stepNext()
     {
       if( page1.isOption1Selected() )
       {
         Page page2 = ...
         Page page3 = ...

         model.push( page2 );       // page2 becomes the next page
         model.addLast( page3 );    // page3 comes after page2
         model.setLastPage( page3 );

         Task task = ...
         model.setFinishTask( task );
       }
       else
       {
         Page page2 = ...
         Page page3 = ...
         Page page4 = ...

         model.push( page2 );       // page2 becomes the next page
         model.addLast( page3 );    // page3 comes after page2
         model.addLast( page4 );    // page4 comes after page3
         model.setLastPage( page4 );

         Task task = ...
         model.setFinishTask( task );
       }
     }
   };

  // add the first page with a custom transition
  model.addLast( page1, transition );
 

Options

DefaultWizardModel provides some methods to customize its behavior:

setSupportsLast - Call this with true if you want your model to have the ability to bypass intermediate pages and jump to the page currently denoted as "last".

setProgressPageIsUsed - Call this with true if you want your model to use a progress page while the finish task is executing. This only applies if the finish task is not null.

setProgressPageName - Use this to set the name of the progress page. This only applies if the progress page is used.

Since:

1.0

Nested Class Summary

static interface	DefaultWizardModel.Transition An action to carry out when the wizard leaves or returns to a page.
static class	DefaultWizardModel.TransitionAdapter A convenience class that implements the Transition interface with empty methods.

Field Summary

Fields inherited from interface sos.wizard.WizardModel

BACK_PROPERTY, CANCEL_PROPERTY, CURRENT_PAGE_PROPERTY, FINISH_PROPERTY, LAST_PROPERTY, NEXT_PROPERTY, STATE_PROPERTY, SUPPORTS_LAST_PROPERTY, WIZARD_CANCELED, WIZARD_FINISHED, WIZARD_FINISHING, WIZARD_IN_PROGRESS

Constructor Summary

DefaultWizardModel()
Creates a DefaultWizardModel with no pages.

DefaultWizardModel(Page[] pages, Task finishTask, Page summaryPage)
Creates a DefaultWizardModel with the specified pages and finish task.

DefaultWizardModel(Page initialPage, DefaultWizardModel.Transition initialTransition)
Creates a DefaultWizardModel with the specified initial page and initial transition.

Method Summary

void	addLast(Page page) Adds the specified page to the end of the current list of pages.
void	addLast(Page page, DefaultWizardModel.Transition transition) Adds the specified page to the end of the current list of pages and assigns it the specified transition.
boolean	canCancel() Returns true if this wizard can be canceled.
void	cancel() Cancels this wizard.
boolean	canFinish() Returns true if this wizard allows the user to finish, given the current state.
boolean	canStepBack() Returns true if this wizard has a previous page.
boolean	canStepLast() Returns true if this wizard can accept the current values and advance to the last page.
boolean	canStepNext() Returns true if this wizard has a subsequent page.
protected ProgressPage	createProgressPage(java.lang.String name, Task finishTask) Creates and returns a progress page with the specified name and task.
void	finish() Ends this wizard.
Page	getCurrentPage() Retrieves the page currently being processed.
java.lang.Object	getElementAt(int index) Returns the step at the specified index.
Task	getFinishTask() Returns the task to execute when the client "finishes" this model.
Page	getLastPage() Returns the page currently denoted as "last".
boolean	getProgressPageIsUsed() Returns true if this model uses a "progress page" while the finish task is executing.
java.lang.String	getProgressPageName() Returns the name to use for the progress page.
java.lang.Object	getSelectedItem() Returns the current step.
int	getSize() Returns the length of the list of steps.
int	getState() Returns the state of this wizard.
void	push(Page page) Removes any subsequent pages and appends the specified page to the end of the list.
void	push(Page page, DefaultWizardModel.Transition transition) Removes any subsequent pages and appends the specified page to the end of the list and assigns it the specified transition.
void	removeLast() Removes this model's last page and transition.
void	setFinishTask(Task finishTask) Sets the action to carry out when this model is finished.
void	setLastPage(Page lastPage) Informs this wizards that the specified page serves as the last page.
void	setProgressPageIsUsed(boolean use) Sets whether or not this model uses a "progress page" while the finish task is executing.
void	setProgressPageName(java.lang.String progressPageName) Sets the name to use for the progress page.
void	setSelectedItem(java.lang.Object anItem) Set the selected item.
void	setSummaryPage(Page summaryPage) Sets the page to display after the finish task has completed successfully.
void	setSupportsLast(boolean supportsLast) Sets whether or not this model should have the ability to bypass all intermediate pages and just to the last page.
void	stepBack() Advances this wizard to the previous page.
void	stepLast() Advances this wizard to the last step.
void	stepNext() Advances this wizard to the next step.
boolean	supportsLast() Returns true if this wizard has the ability to skip intermediate pages and advance to the last page.

Methods inherited from class sos.wizard.AbstractWizardModel

addListDataListener, firePageChanged, fireStepsAdded, fireStepsChanged, fireStepsRemoved, removeListDataListener

Methods inherited from class sos.wizard.AbstractModel

addPropertyChangeListener, addPropertyChangeListener, firePropertyChange, firePropertyChange, firePropertyChange, firePropertyChange, firePropertyChange, firePropertyChange, removePropertyChangeListener, removePropertyChangeListener

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Methods inherited from interface sos.wizard.Model

addPropertyChangeListener, addPropertyChangeListener, removePropertyChangeListener, removePropertyChangeListener

Constructor Detail

DefaultWizardModel

public DefaultWizardModel()

Creates a DefaultWizardModel with no pages.

DefaultWizardModel

public DefaultWizardModel(Page initialPage,
                          DefaultWizardModel.Transition initialTransition)

Creates a DefaultWizardModel with the specified initial page and initial transition.

Parameters:

initialPage - first step in this wizard model

initialTransition - action to carry out to transition from the initial page

Throws:

java.lang.NullPointerException - if initialPage or initialTransition is null

See Also:

DefaultWizardModel( Page[], Task, Page )

DefaultWizardModel

public DefaultWizardModel(Page[] pages,
                          Task finishTask,
                          Page summaryPage)

Creates a DefaultWizardModel with the specified pages and finish task. The wizard's last page is set to the last page in the array. Use this constructor when all of the wizard's steps are unconditional.

finishTask may be null, but a non-null task must be supplied to setFinishTask before the wizard is finished. A null summaryPage indicates that there is no summary page to display. This can be changed later with setSummaryPage.

Parameters:

pages - all of the unconditional steps of this wizard model

finishTask - task to carry out when the last page is completed

summaryPage - page to display after finishedTask has completed

Throws:

java.lang.NullPointerException - if pages is null or any element of pages is null

See Also:

DefaultWizardModel( Page, DefaultWizardModel.Transition )

Method Detail

addLast

public void addLast(Page page)

Adds the specified page to the end of the current list of pages. The page will unconditionally lead to the next page in the list unless it is designated as the last page.

Parameters:

page - step to add to this wizard

Throws:

java.lang.NullPointerException - if page is null

See Also:

addLast( Page, DefaultWizardModel.Transition ), push( Page )

addLast

public void addLast(Page page,
                    DefaultWizardModel.Transition transition)

Adds the specified page to the end of the current list of pages and assigns it the specified transition.

Parameters:

page - step to add to this wizard

transition - action to carry out when page is finished

Throws:

java.lang.NullPointerException - if page or transition is null

See Also:

addLast( Page ), push( Page, DefaultWizardModel.Transition )

canCancel

public boolean canCancel()

Description copied from interface: WizardModel

Returns true if this wizard can be canceled.

Specified by:

canCancel in interface WizardModel

Overrides:

canCancel in class AbstractWizardModel

Returns:

true if this wizard can be canceled.

See Also:

WizardModel.cancel()

canFinish

public boolean canFinish()

Description copied from interface: WizardModel

Returns true if this wizard allows the user to finish, given the current state. If this wizard is not in progress, false is returned.

Specified by:

canFinish in interface WizardModel

Returns:

true if this wizard allows the user to finish

See Also:

WizardModel.finish()

canStepBack

public boolean canStepBack()

Description copied from interface: WizardModel

Returns true if this wizard has a previous page. If this wizard is not in progress, false is returned.

Specified by:

canStepBack in interface WizardModel

Returns:

true if this wizard has a previous page

See Also:

WizardModel.canStepNext()

canStepLast

public boolean canStepLast()

Description copied from interface: WizardModel

Returns true if this wizard can accept the current values and advance to the last page. If this wizard is not in progress or if this wizard does not support last, false is returned.

Specified by:

canStepLast in interface WizardModel

Overrides:

canStepLast in class AbstractWizardModel

Returns:

true if this wizard can advance to the last page

See Also:

WizardModel.stepLast(), WizardModel.supportsLast()

canStepNext

public boolean canStepNext()

Description copied from interface: WizardModel

Returns true if this wizard has a subsequent page. If this wizard is not in progress, false is returned.

Specified by:

canStepNext in interface WizardModel

Returns:

true if this wizard has a subsequent page

See Also:

WizardModel.canStepBack()

cancel

public void cancel()
            throws java.lang.IllegalStateException

Description copied from interface: WizardModel

Cancels this wizard.

Specified by:

cancel in interface WizardModel

Throws:

java.lang.IllegalStateException - if this wizard is not in progress or canCancel returns false

See Also:

WizardModel.canCancel()

createProgressPage

protected ProgressPage createProgressPage(java.lang.String name,
                                          Task finishTask)

Creates and returns a progress page with the specified name and task.

Parameters:

name - name of the progress page

finishTask - task for whose progress will be monitored

Returns:

a new progress page

finish

public void finish()
            throws java.lang.IllegalStateException

Description copied from interface: WizardModel

Ends this wizard.

Specified by:

finish in interface WizardModel

Throws:

java.lang.IllegalStateException - if this wizard is not in progress or canFinish returns false

See Also:

WizardModel.canFinish()

getCurrentPage

public Page getCurrentPage()

Description copied from interface: WizardModel

Retrieves the page currently being processed.

Specified by:

getCurrentPage in interface WizardModel

Returns:

the current page

getElementAt

public java.lang.Object getElementAt(int index)

Description copied from interface: WizardModel

Returns the step at the specified index.

Specified by:

getElementAt in interface WizardModel

Parameters:

index - the requested index

Returns:

the step at index

getFinishTask

public Task getFinishTask()

Returns the task to execute when the client "finishes" this model.

Returns:

the finish task

See Also:

setFinishTask(sos.wizard.Task)

getProgressPageIsUsed

public boolean getProgressPageIsUsed()

Returns true if this model uses a "progress page" while the finish task is executing.

Returns:

true if a progress page is used

See Also:

setProgressPageIsUsed(boolean)

getProgressPageName

public java.lang.String getProgressPageName()

Returns the name to use for the progress page.

Returns:

the progress page's name

See Also:

setProgressPageName(java.lang.String), getProgressPageIsUsed()

getSelectedItem

public java.lang.Object getSelectedItem()

Description copied from interface: WizardModel

Returns the current step.

Specified by:

getSelectedItem in interface WizardModel

Returns:

The current step or null if there is none

getSize

public int getSize()

Description copied from interface: WizardModel

Returns the length of the list of steps.

Specified by:

getSize in interface WizardModel

Returns:

the length of the list of steps

getState

public int getState()

Description copied from interface: WizardModel

Returns the state of this wizard.

Specified by:

getState in interface WizardModel

Returns:

the state of this wizard, one of WIZARD_IN_PROGRESS, WIZARD_FINISHED, WIZARD_FINISHING, and WIZARD_CANCELED

getLastPage

public Page getLastPage()

Returns the page currently denoted as "last".

Returns:

this model's last page

See Also:

setLastPage(sos.wizard.Page)

push

public void push(Page page)

Removes any subsequent pages and appends the specified page to the end of the list. The page will unconditionally lead to the next page in the list unless it is designated as the last page.

Parameters:

page - step to add to this wizard

Throws:

java.lang.NullPointerException - if page is null

See Also:

push( Page, DefaultWizardModel.Transition ), addLast( Page )

push

public void push(Page page,
                 DefaultWizardModel.Transition transition)

Removes any subsequent pages and appends the specified page to the end of the list and assigns it the specified transition.

Parameters:

page - step to add to this wizard

transition - action to carry out when page is finished

Throws:

java.lang.NullPointerException - if page or transition is null

See Also:

push( Page ), addLast( Page, DefaultWizardModel.Transition )

removeLast

public void removeLast()

Removes this model's last page and transition.

Throws:

java.util.NoSuchElementException - if there are no pages in this model

setFinishTask

public void setFinishTask(Task finishTask)

Sets the action to carry out when this model is finished.

Parameters:

finishTask - the finish task

See Also:

getFinishTask()

setLastPage

public void setLastPage(Page lastPage)

Informs this wizards that the specified page serves as the last page. The user can Finish this wizard once the page has been completed and validated. A null lastPage indicates that no last page has yet been specified.

Parameters:

lastPage - last step in this wizard (may be null)

See Also:

getLastPage()

setProgressPageIsUsed

public void setProgressPageIsUsed(boolean use)

Sets whether or not this model uses a "progress page" while the finish task is executing.

Parameters:

use - true if this model should use a progress page

See Also:

getProgressPageIsUsed()

setProgressPageName

public void setProgressPageName(java.lang.String progressPageName)

Sets the name to use for the progress page. This only applies if the progress page is used.

Parameters:

progressPageName - the name to use for the progress page

See Also:

getProgressPageName(), getProgressPageIsUsed()

setSelectedItem

public void setSelectedItem(java.lang.Object anItem)

Description copied from interface: WizardModel

Set the selected item. This method is here only because it is a part of ComboBoxModel. Clients should assume this method throws an UnsupportedOperationException.

Specified by:

setSelectedItem in interface WizardModel

Overrides:

setSelectedItem in class AbstractWizardModel

Parameters:

anItem - the list object to select or null to clear the selection

setSupportsLast

public void setSupportsLast(boolean supportsLast)

Sets whether or not this model should have the ability to bypass all intermediate pages and just to the last page.

Parameters:

supportsLast - true if this wizard can jump to the last page

See Also:

supportsLast()

setSummaryPage

public void setSummaryPage(Page summaryPage)

Sets the page to display after the finish task has completed successfully.

Parameters:

summaryPage - this model's summary page (may be null)

stepBack

public void stepBack()

Description copied from interface: WizardModel

Advances this wizard to the previous page.

Specified by:

stepBack in interface WizardModel

See Also:

WizardModel.canStepBack(), WizardModel.stepNext()

stepLast

public void stepLast()

Description copied from interface: WizardModel

Advances this wizard to the last step.

Specified by:

stepLast in interface WizardModel

See Also:

WizardModel.canStepLast(), WizardModel.supportsLast()

stepNext

public void stepNext()

Description copied from interface: WizardModel

Advances this wizard to the next step.

Specified by:

stepNext in interface WizardModel

See Also:

WizardModel.canStepNext(), WizardModel.stepBack()

supportsLast

public boolean supportsLast()

Description copied from interface: WizardModel

Returns true if this wizard has the ability to skip intermediate pages and advance to the last page. Note that this method ignores the current state of this wizard. To check if this wizard can jump to the last page given the current state, use canStepLast. JWizard uses this property to determine if it should show the Last button.

Specified by:

supportsLast in interface WizardModel

Overrides:

supportsLast in class AbstractWizardModel

Returns:

true if this wizard has the ability to skip intermediate pages and advance to the last page

See Also:

WizardModel.canStepLast()