Package ca.cgjennings.ui.wizard
Interface WizardModel
-
- All Known Implementing Classes:
AbstractWizardModel
,DefaultWizardModel
public interface WizardModel
Models the steps and step transitions in a wizard dialog.- Since:
- 3.0
- Author:
- Chris Jennings
-
-
Method Summary
All Methods Instance Methods Abstract Methods Modifier and Type Method Description void
aboutToHide(int index, javax.swing.JComponent page)
Called before the current page is hidden when switching pages.void
aboutToShow(int index, javax.swing.JComponent page)
Called before a page is displayed.void
addWizardListener(WizardListener li)
Adds a listener that will receiveWizardEvent
s from the model.int
backward()
Causes the model's internal representation to move to the previous page.boolean
canFinish()
Returnstrue
if the wizard can be finished in its current state.boolean
canGoBackward()
Returnstrue
if there is a page before the current page.boolean
canGoForward()
Returnstrue
if there is a page after the current page.java.lang.Object
finish()
Completes the wizard, causing any relevant actions to take place.int
forward()
Causes the model's internal representation to move to the next page.int
getCurrentPage()
Returns the index of the current page.int
getPageCount()
Returns the number of pages in the current set of pages.javax.swing.JComponent[]
getPageOrder()
Returns the current order of pages in the wizard.boolean
isProgressBlocked()
Returnstrue
if progress is currently blocked.void
removeWizardListener(WizardListener li)
Removes a listener from the list of listeners so that it no longer receivesWizardEvent
s from the model.void
reset()
Resets the model.void
setCurrentPage(int index)
Sets the current page of the internal model.void
setProgressBlocked(boolean block)
Sets whether or not progress is blocked.
-
-
-
Method Detail
-
reset
void reset()
Resets the model. This is called when the model is installed in a dialog. It allows the model to be reused in multiple dialogs. This will reset the current page to its initial value and will typically reset the interface components that represent the wizard pages to an initial state. (Alternatively, any existing page components may be thrown out and a new set created.)
-
getPageOrder
javax.swing.JComponent[] getPageOrder()
Returns the current order of pages in the wizard. This method is called to set up the panel and before each page transition. This allows the model to change the page order in response to user choices.Unless otherwise stated, the caller must assume that the returned array should be considered immutable. Changing the values of elements in the array is forbidden.
- Returns:
- an array of components (typically panels) in the order they should be displayed
-
getCurrentPage
int getCurrentPage()
Returns the index of the current page.- Returns:
- the index of the element in
getPageOrder()
that represents the current page
-
setCurrentPage
void setCurrentPage(int index)
Sets the current page of the internal model.- Parameters:
index
- the new page index- Throws:
java.lang.IndexOutOfBoundsException
- if the index does not fall within
-
getPageCount
int getPageCount()
Returns the number of pages in the current set of pages.- Returns:
- the number of pages in the wizard
-
canGoForward
boolean canGoForward()
Returnstrue
if there is a page after the current page. This method must always returnfalse
when progress is blocked.- Returns:
- whether the next button should be enabled
- See Also:
isProgressBlocked()
-
canGoBackward
boolean canGoBackward()
Returnstrue
if there is a page before the current page.- Returns:
- whether the previous button should be enabled
-
canFinish
boolean canFinish()
Returnstrue
if the wizard can be finished in its current state. This method must always returnfalse
when progress is blocked.- Returns:
- whether the finish button should be enabled
- See Also:
isProgressBlocked()
-
forward
int forward()
Causes the model's internal representation to move to the next page.- Returns:
- the new page index
- Throws:
java.lang.IllegalStateException
- if there is no next page- See Also:
canGoForward()
-
backward
int backward()
Causes the model's internal representation to move to the previous page.- Returns:
- the new page index
- Throws:
java.lang.IllegalStateException
- if there is no previous page- See Also:
canGoBackward()
-
finish
java.lang.Object finish()
Completes the wizard, causing any relevant actions to take place. It may optionally return an arbitrary object to represent this result.- Returns:
- an optional result, or
null
- Throws:
java.lang.IllegalStateException
- if finishing is not currently possible- See Also:
canFinish()
-
setProgressBlocked
void setProgressBlocked(boolean block)
Sets whether or not progress is blocked. When progress is blocked,canGoForward()
andcanFinish()
must always returnfalse
. The progress blocking state can be cleared by calling this method with false, and is cleared automatically if the page changes. Blocking provides a mechanism for individual pages to prevent progress if they are missing required information.- Parameters:
block
- iftrue
, prevents the user from going to the next page or finishing the dialog.
-
isProgressBlocked
boolean isProgressBlocked()
Returnstrue
if progress is currently blocked.- Returns:
true
if the user is blocked from continuing
-
aboutToShow
void aboutToShow(int index, javax.swing.JComponent page)
Called before a page is displayed. The following procedure describes how the model is consulted when moving to a new page:- User clicks next (or back).
-
aboutToHide(int, javax.swing.JComponent)
called for current page. -
forward()
(orbackward()
) is called. -
getPageOrder()
andgetCurrentPage()
called to determine which page to display. -
aboutToShow(int, javax.swing.JComponent)
called for new current page. - New page is displayed. Back, next, and finish buttons are updated to
enable them based on
canGoBackward()
and related methods.
- Parameters:
index
- the index of the page to be shownpage
- the page component that corresponds to the index- See Also:
aboutToHide(int, javax.swing.JComponent)
-
aboutToHide
void aboutToHide(int index, javax.swing.JComponent page)
Called before the current page is hidden when switching pages. After this is called, but beforeaboutToShow(int, javax.swing.JComponent)
is called,getPageOrder()
will be called to determine if the page order has changed.- Parameters:
index
- the index of the currently displayed pagepage
- the page component that corresponds to the index- See Also:
aboutToShow(int, javax.swing.JComponent)
-
addWizardListener
void addWizardListener(WizardListener li)
Adds a listener that will receiveWizardEvent
s from the model.- Parameters:
li
- the listener to add- Throws:
java.lang.NullPointerException
- if the listener isnull
-
removeWizardListener
void removeWizardListener(WizardListener li)
Removes a listener from the list of listeners so that it no longer receivesWizardEvent
s from the model.- Parameters:
li
- the listener to removes- Throws:
java.lang.NullPointerException
- if the listener isnull
-
-