sos.wizard
Interface WizardModel

All Superinterfaces:

javax.swing.ComboBoxModel, javax.swing.ListModel, Model

All Known Implementing Classes:

AbstractWizardModel

public interface WizardModel

extends javax.swing.ComboBoxModel, Model

The model that controls the pages and steps in a wizard.

A wizard takes the user through a sequence of steps to accomplish a task. A step may involve one or more pages in which the user must read and/or enter information. The WizardModel interface controls the steps and pages. It has

• A current page
• A state
• A list of steps
• A current step
• The ability to advance to the next, last, and previous pages
• The ability to finish and cancel

Pages

To determine the model's current page, invoke getCurrentPage. To receive a notification that the current page has changed, register a property change listener that reponds to CURRENT_PAGE_PROPERTY.

Steps

The steps that a wizard model has may not be a one-to-one relationship to its pages but often times it is. The methods that relate to the model's steps are:

• int getSize()
• Object getElementAt(int)
• Object getSelectedItem()

These methods deal with steps of type java.lang.Object. There is no restriction as to the type; however, models with a one-to-one relationship typically return the pages themselves as the steps. Clients should not assume pages are returned, though.

Actions

Wizard models can perform the following actions:

Method	Action
stepBack	Return to the previous page
stepNext	Advance to the next page
stepLast	Jump to the last page
finish	End this model and perform the desired task
cancel	Abort this model

The ability to perform these methods, however, depends on the model's state, as described next.

State

The normal progression is as follows. The model starts in the WIZARD_IN_PROGRESS state. In this state, clients have the ability to advance to different pages. Eventually, finish is called on this model and its state changes to WIZARD_FINISHING. When the task completes, the state changes to WIZARD_FINISHED. If cancel is called instead of finish or if the task fails to complete, the model's state changes to WIZARD_CANCELED. The following state diagram illustrates this:

Event Notification

Since this class implements Model, it has the ability to notify listeners that a property has changed. Implementations of this interface should handle the following properties:

Property	Values
BACK_PROPERTY	Boolean
CANCEL_PROPERTY	Boolean
CURRENT_PAGE_PROPERTY	Page
FINISH_PROPERTY	Boolean
LAST_PROPERTY	Boolean
NEXT_PROPERTY	Boolean
STATE_PROPERTY	Integer: One of WIZARD_CANCELED, WIZARD_FINISHED, WIZARD_FINISHING, and WIZARD_IN_PROGRESS
SUPPORTS_LAST_PROPERTY	Boolean

Besides handling PropertyChangeListeners, this interface manages ListDataListeners.

Since:

1.0

Field Summary

static java.lang.String	BACK_PROPERTY Constant used by property change events to signal that the wizard's ability to return to the previous step has changed.
static java.lang.String	CANCEL_PROPERTY Constant used by property change events to signal that the wizard's ability to cancel has changed.
static java.lang.String	CURRENT_PAGE_PROPERTY Constant used by property change events to signal that this wizard's current page has changed.
static java.lang.String	FINISH_PROPERTY Constant used by property change events to signal that the wizard's ability to finish has changed.
static java.lang.String	LAST_PROPERTY Constant used by property change events to signal that the wizard's ability to jump to the last step has changed.
static java.lang.String	NEXT_PROPERTY Constant used by property change events to signal that the wizard's ability to advance to the next step has changed.
static java.lang.String	STATE_PROPERTY Constant used by property change events to signal that the state of this wizard has changed.
static java.lang.String	SUPPORTS_LAST_PROPERTY Constant used by property change events to signal that the wizard's support of jumping to the last step has changed.
static int	WIZARD_CANCELED Constant signifying that the wizard has been canceled.
static int	WIZARD_FINISHED Constant signifying that the wizard has finished.
static int	WIZARD_FINISHING Constant signifying that the wizard is in the process of finishing.
static int	WIZARD_IN_PROGRESS Constant signifying that the wizard is in progress.

Method Summary

void	addListDataListener(javax.swing.event.ListDataListener listener) Adds a listener to the list that is notified each time a change to the data model occurs.
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.
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.
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	removeListDataListener(javax.swing.event.ListDataListener listener) Removes a listener from the list that is notified each time a change to the data model occurs.
void	setSelectedItem(java.lang.Object anItem) Set the selected item.
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 interface sos.wizard.Model

addPropertyChangeListener, addPropertyChangeListener, removePropertyChangeListener, removePropertyChangeListener

Field Detail

BACK_PROPERTY

public static final java.lang.String BACK_PROPERTY

Constant used by property change events to signal that the wizard's ability to return to the previous step has changed.

See Also:

Constant Field Values

CANCEL_PROPERTY

public static final java.lang.String CANCEL_PROPERTY

Constant used by property change events to signal that the wizard's ability to cancel has changed.

See Also:

Constant Field Values

CURRENT_PAGE_PROPERTY

public static final java.lang.String CURRENT_PAGE_PROPERTY

Constant used by property change events to signal that this wizard's current page has changed.

See Also:

Constant Field Values

FINISH_PROPERTY

public static final java.lang.String FINISH_PROPERTY

Constant used by property change events to signal that the wizard's ability to finish has changed.

See Also:

Constant Field Values

LAST_PROPERTY

public static final java.lang.String LAST_PROPERTY

Constant used by property change events to signal that the wizard's ability to jump to the last step has changed.

See Also:

Constant Field Values

NEXT_PROPERTY

public static final java.lang.String NEXT_PROPERTY

Constant used by property change events to signal that the wizard's ability to advance to the next step has changed.

See Also:

Constant Field Values

STATE_PROPERTY

public static final java.lang.String STATE_PROPERTY

Constant used by property change events to signal that the state of this wizard has changed.

See Also:

Constant Field Values

SUPPORTS_LAST_PROPERTY

public static final java.lang.String SUPPORTS_LAST_PROPERTY

Constant used by property change events to signal that the wizard's support of jumping to the last step has changed.

See Also:

Constant Field Values

WIZARD_CANCELED

public static final int WIZARD_CANCELED

Constant signifying that the wizard has been canceled.

See Also:

Constant Field Values

WIZARD_FINISHED

public static final int WIZARD_FINISHED

Constant signifying that the wizard has finished.

See Also:

Constant Field Values

WIZARD_FINISHING

public static final int WIZARD_FINISHING

Constant signifying that the wizard is in the process of finishing.

See Also:

Constant Field Values

WIZARD_IN_PROGRESS

public static final int WIZARD_IN_PROGRESS

Constant signifying that the wizard is in progress.

See Also:

Constant Field Values

Method Detail

addListDataListener

public void addListDataListener(javax.swing.event.ListDataListener listener)

Adds a listener to the list that is notified each time a change to the data model occurs.

Specified by:

addListDataListener in interface javax.swing.ListModel

Parameters:

listener - the ListDataListener to be added

cancel

public void cancel()
            throws java.lang.IllegalStateException

Cancels this wizard.

Throws:

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

See Also:

canCancel()

canCancel

public boolean canCancel()

Returns true if this wizard can be canceled.

Returns:

true if this wizard can be canceled.

See Also:

cancel()

canFinish

public boolean canFinish()

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

Returns:

true if this wizard allows the user to finish

See Also:

finish()

canStepBack

public boolean canStepBack()

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

Returns:

true if this wizard has a previous page

See Also:

canStepNext()

canStepLast

public boolean canStepLast()

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.

Returns:

true if this wizard can advance to the last page

See Also:

stepLast(), supportsLast()

canStepNext

public boolean canStepNext()

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

Returns:

true if this wizard has a subsequent page

See Also:

canStepBack()

finish

public void finish()
            throws java.lang.IllegalStateException

Ends this wizard.

Throws:

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

See Also:

canFinish()

getCurrentPage

public Page getCurrentPage()

Retrieves the page currently being processed.

Returns:

the current page

getElementAt

public java.lang.Object getElementAt(int index)

Returns the step at the specified index.

Specified by:

getElementAt in interface javax.swing.ListModel

Parameters:

index - the requested index

Returns:

the step at index

getSelectedItem

public java.lang.Object getSelectedItem()

Returns the current step.

Specified by:

getSelectedItem in interface javax.swing.ComboBoxModel

Returns:

The current step or null if there is none

getSize

public int getSize()

Returns the length of the list of steps.

Specified by:

getSize in interface javax.swing.ListModel

Returns:

the length of the list of steps

getState

public int getState()

Returns the state of this wizard.

Returns:

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

removeListDataListener

public void removeListDataListener(javax.swing.event.ListDataListener listener)

Removes a listener from the list that is notified each time a change to the data model occurs.

Specified by:

removeListDataListener in interface javax.swing.ListModel

Parameters:

listener - the ListDataListener to be removed

See Also:

addListDataListener(javax.swing.event.ListDataListener)

setSelectedItem

public void setSelectedItem(java.lang.Object anItem)

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 javax.swing.ComboBoxModel

Parameters:

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

stepLast

public void stepLast()
              throws java.lang.IllegalStateException

Advances this wizard to the last step.

Throws:

java.lang.IllegalStateException - if this wizard is not in progress, canStepLast returns false, or this wizard does not support advancing to the last step

See Also:

canStepLast(), supportsLast()

stepNext

public void stepNext()
              throws java.lang.IllegalStateException

Advances this wizard to the next step.

Throws:

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

See Also:

canStepNext(), stepBack()

stepBack

public void stepBack()
              throws java.lang.IllegalStateException

Advances this wizard to the previous page.

Throws:

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

See Also:

canStepBack(), stepNext()

supportsLast

public boolean supportsLast()

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.

Returns:

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

See Also:

canStepLast()