com.sas.swing.visuals.wizard
Class WizardPageDeck

com.sas.swing.visuals.wizard.WizardPageDeck

All Implemented Interfaces:

java.awt.image.ImageObserver, java.awt.MenuContainer, java.io.Serializable, javax.accessibility.Accessible

public class WizardPageDeck

WizardPageDeck is responsible for containing, displaying, and managing the pages in a Wizard object.

One of the main duties of the WizardPageDeck is management of the path. The path is a vector of wizard page names that defines the traversal order of the pages in the wizard. Multiple paths through the pages in the Wizard are supported by allowing the path to be dynamically changed. Wizard pages may be added in any order, and then the order the pages are shown may be explicitly managed through the path object. See Wizard methods setPath and appendPath for more information.

The WizardPageDeck contains the pages of the wizard, and employs a CardLayout layout manager for displaying them. Applications do not directly call the WizardPageDeck method addPage(String pageName, WizardPageInterface page) to add pages to a WizardPageDeck object. Wizard pages are added to the WizardPageDeck by calling one of the following Wizard methods:

        Wizard.addPage(String pageName, WizardPageInterface page),

        Wizard.addPage(String pageName), or

        Wizard.addPages(String[] pageNames)

 

These methods then call the WizardPageDeck's method addPage(String pageName, WizardPageInterface page) to add the pages.

The following methods are available to access the names of page objects contained in the WizardPageDeck:
getCurrentPageName,
getFirstPageName,
getLastPageName,
getPreviousPageName, and
getNextPageName
Once the page name is known, the page instance can be obtained through the method getPage(String pageName)

See Also:

Serialized Form

Field Summary

protected java.awt.CardLayout	cardLayout The layout manager for this WizardPageDeck.
protected java.lang.String	currentPageName The name of the current page being shown.
protected java.util.Vector	pageShownList A vector containing pages that have been shown for the first time.
protected com.sas.collection.Dictionary	pageTable A pool of available pages in this WizardPageDeck.
protected java.util.Vector	path A vector of page names that specifies the order in which pages are shown
static java.lang.String	RB_KEY
protected Wizard	wizard The Wizard object that contains this WizardPageDeck.

Constructor Summary

WizardPageDeck(Wizard wizard)
Creates a WizardPageDeck object to be contained in a Wizard.

Method Summary

void	addPage(java.lang.String pageName, WizardPageInterface page) Adds a WizardPageInterface object and its corresponding name to the pageTable.
protected void	addPagesToDeck(java.lang.String[] pageNames) Adds the correspoding WizardPageInterface objects to names pageNames to this WizardPageDeck.
void	addToPath(java.lang.String[] pageNames) The path defines the traversal order of the pages in the wizard.
void	appendPath(java.lang.String[] pageNames) The path defines the traversal order of the pages in the wizard.
void	clearPath() Removes all elements from the current path.
java.lang.String	getCurrentPageName() Returns the name of the page currently being shown in the wizard.
int	getCurrentPageNumber() If the current page name is not null, the value of the page number of the current page being shown is returned.
java.lang.String	getFirstPageName() Returns the name of the first page in the path, or null if path is empty.
java.lang.String	getLastPageName() Returns the name of the last page in the path, or null if path is empty.
java.lang.String	getNextPageName() Returns the name of the page after the current page in the path, or null if the current page is the last page in the path.
WizardPageInterface	getPage(java.lang.String pageName) Returns a WizardPageInterface object corresponding to name pageName, or null if the object has not yet been created.
int	getPageCount() Returns the final page number on the path.
java.lang.String	getPageName(WizardPageInterface page) Returns the name of the WizardPageInterface object page.
WizardPageInterface[]	getPages() Returns an array of all instantiated pages in the wizard.
java.lang.String[]	getPath() Returns an array containing the names of the pages in the path.
java.lang.String	getPreviousPageName() Returns the name of the page before the current page in the path, or null if the current page is the first page of the path.
void	removePage(java.lang.String pageName) Removes the wizard page corresponding to name pageName from the available pool of pages in this WizardPageDeck.
void	showPage(java.lang.String pageName, int directionFlag) Shows the WizardPageInterface object corresponding to page name pageName in this WizardPageDeck.

Field Detail

RB_KEY

public static final java.lang.String RB_KEY

See Also:

Constant Field Values

path

protected java.util.Vector path

A vector of page names that specifies the order in which pages are shown

pageTable

protected com.sas.collection.Dictionary pageTable

A pool of available pages in this WizardPageDeck. The pageTable is used to store and retrieve wizard page objects by their name. The key is the page name, and the corresponding value is WizardPageInterface object. The value corresponding to the page name is null if the page has not yet been created. The page name/page pair is added to the pageTable whenever pages are added through the method addPage.

See Also:

addPage(java.lang.String, com.sas.swing.visuals.wizard.WizardPageInterface)

pageShownList

protected java.util.Vector pageShownList

A vector containing pages that have been shown for the first time.

currentPageName

protected java.lang.String currentPageName

The name of the current page being shown.

cardLayout

protected java.awt.CardLayout cardLayout

The layout manager for this WizardPageDeck.

wizard

protected Wizard wizard

The Wizard object that contains this WizardPageDeck.

Constructor Detail

WizardPageDeck

public WizardPageDeck(Wizard wizard)

Creates a WizardPageDeck object to be contained in a Wizard. Creates an empty path.

Parameters:

wizard - the Wizard object that contains this WizardPageDeck

Method Detail

getFirstPageName

public java.lang.String getFirstPageName()

Returns the name of the first page in the path, or null if path is empty.

Returns:

the name of the first page in the path, or null if path is empty

getLastPageName

public java.lang.String getLastPageName()

Returns the name of the last page in the path, or null if path is empty.

Returns:

the name of the last page in the path, or null if path is empty

getPreviousPageName

public java.lang.String getPreviousPageName()

Returns the name of the page before the current page in the path, or null if the current page is the first page of the path.

Returns:

the name of the page before the current page in the path, or null if the current page is the first page of the path

getNextPageName

public java.lang.String getNextPageName()

Returns the name of the page after the current page in the path, or null if the current page is the last page in the path.

Returns:

the name of the page after the current page in the path, or null if the current page is the last page in the path

getCurrentPageName

public java.lang.String getCurrentPageName()

Returns the name of the page currently being shown in the wizard. Will return null if the path has not been set.

Returns:

the name of the page currently being shown in the wizard, or null if the path has not been set

showPage

public void showPage(java.lang.String pageName,
                     int directionFlag)

Shows the WizardPageInterface object corresponding to page name pageName in this WizardPageDeck. An IllegalArgumentException is thrown if the page name pageName is not in the path. If the WizardPageInterface object corresponding to pageName has not been created because delayed instantiation was selected in wizard, then it is first created by calling the Wizard method createNamedPage, and is then added to the WizardPageDeck.

This method is called from the actionPerformed method of the wizard's ButtonNavigationPanel object. It may also be called directly, in which case directionFlag should be equal to WizardPageInterface.EXPLICIT_SET. If this method is called directly, with the EXPLICIT_SET bit set, then the current page's hidePage method is invoked, with directionFlag passing directly through.

Before the page is shown, the current page name and number are set, and the wizard title and image are updated. Also, the page's own showPage method is invoked passing the directionFlag parameter. If it is the first time the page has been shown, then directionFlag is bitwise inclusive ORed with WizardPageInterface.FIRST_TIME_SHOWN, before it is passed.

Parameters:

pageName - the name of the page to show, this name must be in the path

directionFlag - an integer flag whose bits specify the page that was shown before, relative to page pageName on the path. Valid values are WizardPageInterface.PREVIOUS, WizardPageInterface.NEXT, or WizardPageInterface.EXPLICIT_SET

See Also:

WizardPageInterface.PREVIOUS, WizardPageInterface.NEXT, WizardPageInterface.EXPLICIT_SET, Wizard.createNamedPage(java.lang.String)

clearPath

public void clearPath()

Removes all elements from the current path.

addToPath

public void addToPath(java.lang.String[] pageNames)

The path defines the traversal order of the pages in the wizard. This method adds the pages names in the pageNames array to the end of the current path. If the correspoding WizardPageInterface objects to the names pageNames have been created, then they are added to this WizardPageDeck.

Called from Wizard's setPath and addPage methods.

An IllegalStateException is thrown if pageNames is null.

Parameters:

pageNames - the names of the pages to add to the path

See Also:

appendPath(java.lang.String[])

addPagesToDeck

protected void addPagesToDeck(java.lang.String[] pageNames)

Adds the correspoding WizardPageInterface objects to names pageNames to this WizardPageDeck. Called from addToPath and appendPath, if the CREATE_IN_ADVANCE option is selected in the Wizard. Called from showPage, after the page is created, if CREATE_WHEN_SHOWN is selected in the Wizard.

Parameters:

pageNames - the names of the pages to add to this WizardPageDeck

See Also:

addToPath(java.lang.String[]), appendPath(java.lang.String[]), showPage(java.lang.String, int), Wizard.CREATE_WHEN_SHOWN, Wizard.CREATE_IN_ADVANCE

appendPath

public void appendPath(java.lang.String[] pageNames)

The path defines the traversal order of the pages in the wizard. This method first removes any page names following the current page name in the path, and then appends the names of the pages in pageNames to the end.

If the correspoding WizardPageInterface objects to names pageNames have been created, then they are added to this WizardPageDeck.

Called from Wizard method appendPath.

An IllegalStateException is thrown if pageNames is null.

Parameters:

pageNames - an array of page names to be added to the path following the current page name, replacing any names currently there.

addPage

public void addPage(java.lang.String pageName,
                    WizardPageInterface page)

Adds a WizardPageInterface object and its corresponding name to the pageTable. The object page may have a null value if it has not been instantiated yet.

If the pageTable contains another page with the same pageName, or page was already added under another name, then an IllegalArgumentException will be thrown.

Called from Wizard methods:

• Wizard.addPage(String pageName, WizardPageInterface page)
• Wizard.addPage(String pageName)
• Wizard.addPages(String[] pageNames)

Parameters:

pageName - the name of the page

page - the instance of the page corresponding to the name pageName, may have a null value if it has not yet been instantiated

See Also:

pageTable, Wizard

removePage

public void removePage(java.lang.String pageName)

Removes the wizard page corresponding to name pageName from the available pool of pages in this WizardPageDeck. An IllegalArgumentException is thrown if pageName is in the path.

Parameters:

pageName - the name of the page to remove

getPageName

public java.lang.String getPageName(WizardPageInterface page)

Returns the name of the WizardPageInterface object page. Throws an IllegalArgumentException if the pageTable does not contain page, indicating page was not added to the WizardPageDeck.

Parameters:

page - a WizardPageInterface object

See Also:

pageTable

getPage

public WizardPageInterface getPage(java.lang.String pageName)

Returns a WizardPageInterface object corresponding to name pageName, or null if the object has not yet been created. An IllegalArgumentException is thrown if the page corresponding to pageName is not found in pageTable.

Parameters:

pageName - the name of a WizardPageInterface object

See Also:

pageTable

getPages

public WizardPageInterface[] getPages()

Returns an array of all instantiated pages in the wizard. Pages that were added to pageTable, but never created are not returned.

Returns:

an WizardPageInterface array of all instantiated pages in the wizard

getCurrentPageNumber

public int getCurrentPageNumber()

If the current page name is not null, the value of the page number of the current page being shown is returned. Otherwise -1 is returned. The numbering of the pages is 1-based, that is the first page is page number 1.

Returns:

if the current page name is not null, an int value is returned representing the current page number being shown. Otherwise a value of -1 is returned.

getPageCount

public int getPageCount()

Returns the final page number on the path. The numbering of the pages is 1-based, that is the first page is page number 1.

Returns:

an int value representing the final page number the path

getPath

public java.lang.String[] getPath()

Returns an array containing the names of the pages in the path. The order of the names specifies the order the pages are shown.

Returns:

an array containing the names of the pages in the path

See Also:

path