Wizard (SAS AppDevStudio API Developer Documentation for Java)

Wizard is a class that provides a framework to develop wizards. The main components contained in the Wizard are the deck, the buttonPanel, and the statusImagePanel. Factory methods createWizardPageDeck, createButtonPanel, and createStatusImagePanel are provided to create these components.

The deck is a WizardPageDeck object which is responsible for containing and managing the pages in the wizard. One of the main duties of the deck 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. The framework supports multiple paths through the pages in the wizard 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.

Other responsibilities of the deck include showing the pages, keeping track of whether a page has been shown for the first time, whether pages have yet been instantiated, current page number, and total page count.

Pages contained in the Wizard must implement the WizardPageInterface interface. WizardPageInterface contains the following methods:

showPage
hidePage
cleanup
getPageInfo
isButtonEnabled
getStatusImage

BaseWizardPage, designed to be subclassed, provides a default implementation of the WizardPageInterface interface.

The buttonPanel is a ButtonNavigationPanel object, which contains buttons used to navigate through the pages of the Wizard. It handles the actionEvents generated by the buttons it contains. ActionEvents generated by buttons having action commands ButtonNavigationPanel.BACK_COMMAND and ButtonNavigationPanel.NEXT_FINISH_COMMAND call on the deck to show previous and next pages respectively.

The action commands of other buttons firing ActionEvents are forwarded to the Wizard handleButtonCommand method for handling there. The handleButtonCommand method calls the cancel , help, or finish method, depending on the action command received. Theses methods should be overridden by Wizard subclasses to provide the desired functionality. Subclasses of Wizard that add custom buttons to the ButtonNavigationPanel object should override the handleButtonCommand method to provide needed functionality.

The buttonPanel, a ButtonNavigationPanel object, uses a ButtonLayout layout manager, which allows the spacing between the buttons to be controlled, as well as providing left or right horizontal alignment. Methods are provided to add custom buttons, and to remove buttons.

The statusImagePanel is a JPanel object used to hold an ImageView object, in which images may be displayed. The method setImage can be used to dynamically change the image, or remove the image altogether. If the desired behaviour is to have something other than an image shown in the statusImagePanel, then the method getStatusImagePanel is called to obtain the statusImagePanel object, and then can be used to add other types of components to it.

A default image can be set for the Wizard through method setDefaultImage. Wizard pages implement the getStatusImage method from the WizardPageInterface interface to return the source for obtaining the image to be shown, or return null if the desired behaviour is to have the statusImagePanel empty. The deck calls the getStatusImage method for a page each time it is shown, to display the appropriate image for the page. The default behaviour for BaseWizardPage method getStatusImage is to return the Wizard's default image.

Since there may be multiple paths through a wizard, then there may be pages in the wizard that are never used, depending upon the path chosen by the user. The Wizard framework provides delayed page instantiation capability, where the pages are not created until the time they are shown for the first time. This may be a more efficient option if there are many pages in the Wizard that have a low probability of being used. The other option is to have all of the pages created at the time of Wizard construction, regardless of whether they will be seen by the user or not.

The default Wizard constructor will create the pages in advance of being shown. To use the delayed page instantiation option, the constructor
public Wizard(String wizardName, int whenToCreate)
should be used. For example, the following shows a Wizard subclass, MyWizard, using delayed page instantiation:

                MyWizard wizard = new MyWizard("Wizard Name", Wizard.CREATE_WHEN_SHOWN);

When this delayed instantiation option is chosen, the Wizard method createNamedPage must be overridden in the Wizard subclass, such as:

        public WizardPageInterface createNamedPage(String pageName){
                WizardPageInterface page = null;
                if( pageName.equals("page1") ){
                        page = new WizardPage1(this, "Introduction");
                }
                else if( pageName.equals("page2") ){
                        page = new WizardPage2(this, "Another Page");
                }

                ...

                return page;
        }

Adding Pages to the Wizard:
There are three methods that can be used to add pages to the Wizard. Each page has a unique, identifying name associated with it.


                public void addPage(String pageName, WizardPageInterface page)
                public void addPage(String pageName)
                public void addPages(String[] pageNames)

If either of the last two methods are used, where the page is added by its identifying name only, then the createNamedPage must be overridden. Use one of these last two methods to add pages if delayed instantiation is desired.

Setting the path in the Wizard:
The path contains the wizard page names that define the traversal order of the pages in the wizard. The names of the pages are added to the path when the pages are added to the wizard through one of the above mentioned addPage methods. The order of the names in the path will be in the same order as the pages were added. The path may also be set using the following method:

                public void setPath(String[] pageNames)

This method sets the order of traversal of pages in the wizard to that of the order in the pageNames array, and then shows the first page in the path in the deck.

The appendPath method can be used to dynamically change the path. For example, below is a Wizard page where the path changes according to which JCheckBox the user selects:

                public class ChangePathPage extends BaseWizardPage implements ItemListener{
                        JCheckBox checkBox1, checkBox2;
                        ....

                        public void itemStateChanged(ItemEvent event){
                                if(checkBox1.isSelected()){
                                        wizard.appendPath(new String[] {"summary"} );   
                                }
                                else if(checkBox2.isSelected()){
                                        wizard.appendPath(new String[] {"page8", "page9", "summary"} );
                                }
 
                                ...
  
                        }
                   ...
                }

The appendPath method first removes any page names following the current page name in the path, and then appends the names of the pages in the array passed to it on the end.

A page name may only exist in the path one time. Also, any page names appended to the path should have been previously added through one of the addPage methods.

Wizard was designed to extend JPanel to provide greater flexibilty for containment. Utility method showWizardDialog is provided to place the wizard in a JDialog.

See Also:: Serialized Form

Field Summary

protected BackAction backAction


protected ButtonNavigationPanel buttonPanel
          A ButtonNavigationPanel object that contains and manages the buttons used to navigate through the wizard.

protected CancelAction cancelAction


protected boolean closeWindowOnCancel
          A boolean value indicating if the window containing the wizard should be disposed of when either the cancel button, the ESC key, or the close button in the window's title bar are activated, before the cancel method is called.

static int CREATE_IN_ADVANCE
          An int value informing the wizard to create all of the pages in advance, before the time they are shown for the first time.

static int CREATE_WHEN_SHOWN
          An int value informing the wizard to delay instantiation of pages until the time they are shown for the first time.

protected java.lang.String currentImageSource
          The source path or URL for obtaining the current image being displayed in the wizard.

protected WizardPageDeck deck
          A WizardPageDeck object that contains and manages all of the wizard pages.

protected javax.swing.JPanel deckAndImagePanel
          Container used in the wizard layout that holds the deck and the statusImagePanel

protected java.lang.String defaultImage
          The source path or URL for obtaining the default image.

protected FinishAction finishAction


protected HelpAction helpAction


protected ImageView imageView
          An ImageView object that is used to display images in the statusImagePanel

protected Next_FinishAction next_finishAction


protected boolean promptOnClose
          A boolean value indicating if a message should be displayed when the close button in the title bar of the window containing the wizard, or the ESC key is activated.

static java.lang.String RB_KEY


protected javax.swing.JPanel statusImagePanel
          Container used in the wizard layout that may hold an ImageView object, or any other type of component depending upon the requirements of individual wizard pages.

protected java.lang.String titleFormatString
          Specifies the format of the wizard title

protected boolean wasCancelled
          A boolean value indicating if the Wizard has been cancelled (i.e. its cancel method has been invoked)

protected int whenToCreatePage
          Flag specifying when the wizard will create the pages.

protected java.lang.String wizardName
          The name of this wizard.

Constructor Summary

Wizard()
          Constructs a Wizard with wizardName set to null, and whenToCreatePage flag set to CREATE_IN_ADVANCE.

Wizard(java.lang.String wizardName)
          Constructs a Wizard with the specified wizardName, and whenToCreatePage flag set to CREATE_IN_ADVANCE.

Wizard(java.lang.String wizardName, int whenToCreate)
          Constructs a Wizard with the specified wizardName and whenToCreatePage flag.

Method Summary

void addPage(java.lang.String pageName)
          Adds the name of a page to the wizard, and adds the page name to the end of the path.

void addPage(java.lang.String pageName, WizardPageInterface page)
          Adds a page instance and its corresponding name to the wizard, and adds the page name to the end of the path.

void addPages(java.lang.String[] pageNames)
          Adds the page names to the wizard, and to the end of the path.

void appendPath(java.lang.String[] pageNames)
          The path defines the traversal order of the pages in the wizard.

void cancel()
          This method should be overidden by subclasses to provide the desired functionality when the Cancel button is activated in the ButtonNavigationPanel.

protected void cleanup()
          Calls WizardPageInterface method cleanup on individual wizard pages.

void closeWindow()
          Disposes of the Window that contains the Wizard

ButtonNavigationPanel createButtonPanel()
          Constucts and returns a ButtonNavigationPanel containing buttons used to navigate through the wizard.

void createLayout()
          Creates and sets the layout manager for the wizard.

WizardPageInterface createNamedPage(java.lang.String pageName)
          This method should be overridden by Wizard subclasses if delayed page instantiation is selected.

javax.swing.JComponent createSeparator()
          Returns a separator component used in the wizard layout.

javax.swing.JPanel createStatusImagePanel()
          Constructs and returns a JPanel object.

void createVisuals()
          Calls method createLayout to create and set the layout manager for the wizard.

protected ImageView createWizardImageView()
          Factory method used to create the imageView object.

WizardPageDeck createWizardPageDeck()
          Factory method used to construct the deckobject.

int displayCancelPrompt()
          Displays a confirmation message dialog with Yes and No options.

void doWindowClosingAction()
          If the promptOnClose property is true, this method calls the displayCancelPrompt method to display a prompting message dialog asking the user to verify the closing action.

void enableButtons()


void finish()
          This method should be overidden by subclasses to provide the desired functionality when the Finish button is activated in the ButtonNavigationPanel.

BackAction getBackAction()


ButtonNavigationPanel getButtonPanel()
          Returns the buttonPanel.

CancelAction getCancelAction()


boolean getCloseWindowOnCancel()
          Returns a boolean value indicating if the window containing the wizard should be disposed of when either the cancel button or the close button in the window's title bar are selected, before the cancel method is called.

java.lang.String getCurrentImageSource()
          Returns a string specifying the source (location) for obtaining the current image being shown in the statusImagePanel of the wizard, or null if an image is not currently being displayed.

java.lang.String getCurrentPageName()
          Returns the name of the current page being shown in the wizard, or null if the path has not been set.

java.lang.String getDefaultImage()
          Returns the source (location) for obtaining the default image for the wizard.

javax.swing.Action getEscAction()
          Returns the Action whose actionPerformed method is invoked when the ESC key is activated.

FinishAction getFinishAction()


HelpAction getHelpAction()


Next_FinishAction getNext_FinishAction()


WizardPageInterface getPage(java.lang.String pageName)
          Returns a WizardPageInterface object corresponding to its name pageName.

java.lang.String getPageName(WizardPageInterface page)
          Returns name of a WizardPageInterface object page.

java.lang.String[] getPath()


boolean getPromptOnClose()
          Returns a boolean value indicating if a message should be displayed when the close button in the title bar of the window containing the wizard is selected.

javax.swing.JPanel getStatusImagePanel()
          Returns the statusImagePanel.

java.lang.String getTitle()
          Returns the title of the current page being shown in the wizard, or null if the path has not been set.

java.lang.String getTitleFormatString()
          Returns the titleFormatString.

static com.sas.swing.visuals.wizard2.WizardDialog getWizardDialog(javax.swing.JFrame frame, Wizard wizard)
          Creates and returns a dialog containing wizard.

java.lang.String getWizardName()
          Returns the name of the wizard.

void handleButtonCommand(java.lang.String actionCommand)
          This method is called when a button in the ButtonNavigationPanel is activated.

void help()
          This method should be overidden by subclasses to provide the desired functionality when the Help button is activated in the ButtonNavigationPanel.

void propertyChange(java.beans.PropertyChangeEvent pce)
          Processes a void removePage(java.lang.String pageName)


void setCloseWindowOnCancel(boolean closeAction)
          Set whether the window containing the wizard should be disposed of when either the cancel button or the close button in the window's title bar are selected, before the cancel method is called.

void setDefaultImage(java.lang.String imageSource)
          Sets the source (location) for obtaining the default image for the wizard.

void setImage(java.lang.String imageSource)
          Sets the source on the imageView to imageSource, and adds imageView to the statusImagePanel.

void setPath(java.lang.String[] pageNames)
          The path defines the traversal order of the pages in the wizard.

void setPromptOnClose(boolean promptAction)
          Sets whether a message should be displayed when the close button in the title bar of the window containing the wizard is selected.

void setTitleFormatString(java.lang.String titleFormat)
          Sets the titleFormatString to the specified titleFormat.

void setWizardName(java.lang.String name)
          Sets the wizardName to the specified name.

void showPage(java.lang.String pageName)
          Shows the page corresponding to the name pageName in the wizard.

static void showWizardDialog(javax.swing.JFrame frame, Wizard wizard)
          Displays a Wizard object in a dialog.

boolean wasCancelled()
          Returns a boolean value indicating if the Wizard has been cancelled from.

Field Summary
`protected BackAction`	`backAction`
`protected ButtonNavigationPanel`	`buttonPanel` A ButtonNavigationPanel object that contains and manages the buttons used to navigate through the wizard.
`protected CancelAction`	`cancelAction`
`protected boolean`	`closeWindowOnCancel` A boolean value indicating if the window containing the wizard should be disposed of when either the cancel button, the ESC key, or the close button in the window's title bar are activated, before the cancel method is called.
`static int`	`CREATE_IN_ADVANCE` An int value informing the wizard to create all of the pages in advance, before the time they are shown for the first time.
`static int`	`CREATE_WHEN_SHOWN` An int value informing the wizard to delay instantiation of pages until the time they are shown for the first time.
`protected java.lang.String`	`currentImageSource` The source path or URL for obtaining the current image being displayed in the wizard.
`protected WizardPageDeck`	`deck` A WizardPageDeck object that contains and manages all of the wizard pages.
`protected javax.swing.JPanel`	`deckAndImagePanel` Container used in the wizard layout that holds the `deck` and the `statusImagePanel`
`protected java.lang.String`	`defaultImage` The source path or URL for obtaining the default image.
`protected FinishAction`	`finishAction`
`protected HelpAction`	`helpAction`
`protected ImageView`	`imageView` An ImageView object that is used to display images in the `statusImagePanel`
`protected Next_FinishAction`	`next_finishAction`
`protected boolean`	`promptOnClose` A boolean value indicating if a message should be displayed when the close button in the title bar of the window containing the wizard, or the ESC key is activated.
`static java.lang.String`	`RB_KEY`
`protected javax.swing.JPanel`	`statusImagePanel` Container used in the wizard layout that may hold an ImageView object, or any other type of component depending upon the requirements of individual wizard pages.
`protected java.lang.String`	`titleFormatString` Specifies the format of the wizard title
`protected boolean`	`wasCancelled` A boolean value indicating if the Wizard has been cancelled (i.e. its cancel method has been invoked)
`protected int`	`whenToCreatePage` Flag specifying when the wizard will create the pages.
`protected java.lang.String`	`wizardName` The name of this wizard.

Constructor Summary
`Wizard()` Constructs a Wizard with wizardName set to null, and whenToCreatePage flag set to CREATE_IN_ADVANCE.
`Wizard(java.lang.String wizardName)` Constructs a Wizard with the specified wizardName, and whenToCreatePage flag set to CREATE_IN_ADVANCE.
`Wizard(java.lang.String wizardName, int whenToCreate)` Constructs a Wizard with the specified wizardName and whenToCreatePage flag.

Method Summary
`void`	`addPage(java.lang.String pageName)` Adds the name of a page to the wizard, and adds the page name to the end of the `path`.
`void`	`addPage(java.lang.String pageName, WizardPageInterface page)` Adds a page instance and its corresponding name to the wizard, and adds the page name to the end of the `path`.
`void`	`addPages(java.lang.String[] pageNames)` Adds the page names to the wizard, and to the end of the `path`.
`void`	`appendPath(java.lang.String[] pageNames)` The path defines the traversal order of the pages in the wizard.
`void`	`cancel()` This method should be overidden by subclasses to provide the desired functionality when the Cancel button is activated in the ButtonNavigationPanel.
`protected void`	`cleanup()` Calls `WizardPageInterface` method `cleanup` on individual wizard pages.
`void`	`closeWindow()` Disposes of the Window that contains the Wizard
`ButtonNavigationPanel`	`createButtonPanel()` Constucts and returns a ButtonNavigationPanel containing buttons used to navigate through the wizard.
`void`	`createLayout()` Creates and sets the layout manager for the wizard.
`WizardPageInterface`	`createNamedPage(java.lang.String pageName)` This method should be overridden by Wizard subclasses if delayed page instantiation is selected.
`javax.swing.JComponent`	`createSeparator()` Returns a separator component used in the wizard layout.
`javax.swing.JPanel`	`createStatusImagePanel()` Constructs and returns a JPanel object.
`void`	`createVisuals()` Calls method `createLayout` to create and set the layout manager for the wizard.
`protected ImageView`	`createWizardImageView()` Factory method used to create the `imageView` object.
`WizardPageDeck`	`createWizardPageDeck()` Factory method used to construct the `deck`object.
`int`	`displayCancelPrompt()` Displays a confirmation message dialog with Yes and No options.
`void`	`doWindowClosingAction()` If the `promptOnClose` property is true, this method calls the displayCancelPrompt method to display a prompting message dialog asking the user to verify the closing action.
`void`	`enableButtons()`
`void`	`finish()` This method should be overidden by subclasses to provide the desired functionality when the Finish button is activated in the `ButtonNavigationPanel`.
`BackAction`	`getBackAction()`
`ButtonNavigationPanel`	`getButtonPanel()` Returns the `buttonPanel`.
`CancelAction`	`getCancelAction()`
`boolean`	`getCloseWindowOnCancel()` Returns a boolean value indicating if the window containing the wizard should be disposed of when either the cancel button or the close button in the window's title bar are selected, before the cancel method is called.
`java.lang.String`	`getCurrentImageSource()` Returns a string specifying the source (location) for obtaining the current image being shown in the `statusImagePanel` of the wizard, or null if an image is not currently being displayed.
`java.lang.String`	`getCurrentPageName()` Returns the name of the current page being shown in the wizard, or null if the path has not been set.
`java.lang.String`	`getDefaultImage()` Returns the source (location) for obtaining the default image for the wizard.
`javax.swing.Action`	`getEscAction()` Returns the Action whose actionPerformed method is invoked when the ESC key is activated.
`FinishAction`	`getFinishAction()`
`HelpAction`	`getHelpAction()`
`Next_FinishAction`	`getNext_FinishAction()`
`WizardPageInterface`	`getPage(java.lang.String pageName)` Returns a WizardPageInterface object corresponding to its name `pageName`.
`java.lang.String`	`getPageName(WizardPageInterface page)` Returns name of a WizardPageInterface object `page`.
`java.lang.String[]`	`getPath()`
`boolean`	`getPromptOnClose()` Returns a boolean value indicating if a message should be displayed when the close button in the title bar of the window containing the wizard is selected.
`javax.swing.JPanel`	`getStatusImagePanel()` Returns the `statusImagePanel`.
`java.lang.String`	`getTitle()` Returns the title of the current page being shown in the wizard, or null if the path has not been set.
`java.lang.String`	`getTitleFormatString()` Returns the `titleFormatString`.
`static com.sas.swing.visuals.wizard2.WizardDialog`	`getWizardDialog(javax.swing.JFrame frame, Wizard wizard)` Creates and returns a dialog containing `wizard`.
`java.lang.String`	`getWizardName()` Returns the name of the wizard.
`void`	`handleButtonCommand(java.lang.String actionCommand)` This method is called when a button in the ButtonNavigationPanel is activated.
`void`	`help()` This method should be overidden by subclasses to provide the desired functionality when the Help button is activated in the ButtonNavigationPanel.
`void`	`propertyChange(java.beans.PropertyChangeEvent pce)` Processes a	`void`	`removePage(java.lang.String pageName)`
`void`	`setCloseWindowOnCancel(boolean closeAction)` Set whether the window containing the wizard should be disposed of when either the cancel button or the close button in the window's title bar are selected, before the cancel method is called.
`void`	`setDefaultImage(java.lang.String imageSource)` Sets the source (location) for obtaining the default image for the wizard.
`void`	`setImage(java.lang.String imageSource)` Sets the source on the `imageView` to `imageSource`, and adds `imageView` to the `statusImagePanel`.
`void`	`setPath(java.lang.String[] pageNames)` The path defines the traversal order of the pages in the wizard.
`void`	`setPromptOnClose(boolean promptAction)` Sets whether a message should be displayed when the close button in the title bar of the window containing the wizard is selected.
`void`	`setTitleFormatString(java.lang.String titleFormat)` Sets the titleFormatString to the specified `titleFormat`.
`void`	`setWizardName(java.lang.String name)` Sets the wizardName to the specified name.
`void`	`showPage(java.lang.String pageName)` Shows the page corresponding to the name `pageName` in the wizard.
`static void`	`showWizardDialog(javax.swing.JFrame frame, Wizard wizard)` Displays a `Wizard` object in a dialog.
`boolean`	`wasCancelled()` Returns a boolean value indicating if the Wizard has been cancelled from.

Field Detail

RB_KEY

public static final java.lang.String RB_KEY

See Also:: Constant Field Values

backAction

protected BackAction backAction

finishAction

protected FinishAction finishAction

next_finishAction

protected Next_FinishAction next_finishAction

cancelAction

protected CancelAction cancelAction

helpAction

protected HelpAction helpAction

closeWindowOnCancel

protected boolean closeWindowOnCancel

A boolean value indicating if the window containing the wizard should be disposed of when either the cancel button, the ESC key, or the close button in the window's title bar are activated, before the cancel method is called. The default setting is true.

promptOnClose

protected boolean promptOnClose

A boolean value indicating if a message should be displayed when the close button in the title bar of the window containing the wizard, or the ESC key is activated. If set to true, the displayCancelPrompt method is called to display a message when the close button is selected. The default setting is true.

CREATE_WHEN_SHOWN

public static final int CREATE_WHEN_SHOWN

An int value informing the wizard to delay instantiation of pages until the time they are shown for the first time.

See Also:: CREATE_IN_ADVANCE, whenToCreatePage, Constant Field Values

CREATE_IN_ADVANCE

public static final int CREATE_IN_ADVANCE

An int value informing the wizard to create all of the pages in advance, before the time they are shown for the first time.

See Also:: CREATE_WHEN_SHOWN, whenToCreatePage, Constant Field Values

whenToCreatePage

protected int whenToCreatePage

Flag specifying when the wizard will create the pages. This flag can be set at time of Wizard construction.

See Also:: CREATE_WHEN_SHOWN, CREATE_IN_ADVANCE

imageView

protected ImageView imageView

An ImageView object that is used to display images in the statusImagePanel

See Also:: statusImagePanel, currentImageSource, defaultImage

currentImageSource

protected java.lang.String currentImageSource

The source path or URL for obtaining the current image being displayed in the wizard.

See Also:: getCurrentImageSource(), setImage(java.lang.String), statusImagePanel

defaultImage

protected java.lang.String defaultImage

The source path or URL for obtaining the default image.

See Also:: setDefaultImage(java.lang.String), getDefaultImage()

wizardName

protected java.lang.String wizardName

The name of this wizard. The wizard name can optionally be included in the page titles, by setting the title format.

deck

protected WizardPageDeck deck

A WizardPageDeck object that contains and manages all of the wizard pages. The deck maintains the traversal order of the pages. The deck is also responsible for showing the pages, where only one page is visible at a time.

buttonPanel

protected ButtonNavigationPanel buttonPanel

A ButtonNavigationPanel object that contains and manages the buttons used to navigate through the wizard.

titleFormatString

protected java.lang.String titleFormatString

Specifies the format of the wizard title

See Also:: setTitleFormatString(java.lang.String), getTitleFormatString()

statusImagePanel

protected javax.swing.JPanel statusImagePanel

Container used in the wizard layout that may hold an ImageView object, or any other type of component depending upon the requirements of individual wizard pages. Wizard pages implement the getStatusImage method from the WizardPageInterface interface to return the source for obtaining the image to be shown, or return null if the statusImagePanel should be empty.

If the desired behaviour is to have something other than an image shown in this panel, then the method getStatusImagePanel can be called to obtain the statusImagePanel object, and then used to add other types of components to it.

See Also:: WizardPageInterface.getStatusImage(), getStatusImagePanel()

deckAndImagePanel

protected javax.swing.JPanel deckAndImagePanel

Container used in the wizard layout that holds the deck and the statusImagePanel

wasCancelled

protected boolean wasCancelled

A boolean value indicating if the Wizard has been cancelled (i.e. its cancel method has been invoked)

Constructor Detail

Wizard

public Wizard()

Constructs a Wizard with wizardName set to null, and whenToCreatePage flag set to CREATE_IN_ADVANCE. Calls Wizard(null, CREATE_IN_ADVANCE).

See Also:: wizardName, CREATE_IN_ADVANCE

Wizard

public Wizard(java.lang.String wizardName)

Constructs a Wizard with the specified wizardName, and whenToCreatePage flag set to CREATE_IN_ADVANCE. Calls Wizard(wizardName, CREATE_IN_ADVANCE).

Parameters:: wizardName - the name of the wizard.
See Also:: wizardName, CREATE_IN_ADVANCE

Wizard

public Wizard(java.lang.String wizardName,
              int whenToCreate)

Constructs a Wizard with the specified wizardName and whenToCreatePage flag.

Parameters:: wizardName - the name of the wizard.; whenToCreatePage - int value telling wizard when to create the wizard pages.
See Also:: wizardName, CREATE_WHEN_SHOWN, CREATE_IN_ADVANCE

Method Detail

getNext_FinishAction

public Next_FinishAction getNext_FinishAction()

getCancelAction

public CancelAction getCancelAction()

getHelpAction

public HelpAction getHelpAction()

getFinishAction

public FinishAction getFinishAction()

getBackAction

public BackAction getBackAction()

createLayout

public void createLayout()

Creates and sets the layout manager for the wizard. Default implementation uses an AutoSizingGridLayout with three rows and one column. This method is called from method createVisuals. Subclasses can override this method to create and use a different layout manager.

See Also:: createVisuals()

createVisuals

public void createVisuals()

Calls method createLayout to create and set the layout manager for the wizard. Constructs the Wizard visual components, and adds them to the Wizard.

The deckAndImagePanel, a separator, and the buttonPanel are constructed and added to the Wizard in that order. The separator and buttonPanel are created through the factory methods createSeparator and createButtonPanel.

The deck and statusImagePanel objects are constructed and added to the deckAndImagePanel. These objects are created through factory methods createWizardPageDeck and createStatusImagePanel.

See Also:: createLayout(), createStatusImagePanel(), createWizardImageView(), createSeparator(), createButtonPanel()

setTitleFormatString

public void setTitleFormatString(java.lang.String titleFormat)

Sets the titleFormatString to the specified titleFormat. The titleFormatString is used by the getTitle method to display the title on the Wizard pages.

The default titleFormatString is "{0} -- Step {1} of {2} {3}", where the parameters represent:

{0} - the name of the wizard
{1} - current page number
{2} - final page number
{3} - the current page information

The titleFormatString can be modified to control what information is displayed in the title bar of the Wizard pages. For example, if the page number information should not be displayed, then the titleFormatString can be set to "{0} -- {3}". This will result in only the Wizard name and current page information being displayed.

See Also:: titleFormatString, getTitleFormatString(), getTitle()

getTitleFormatString

public java.lang.String getTitleFormatString()

Returns the titleFormatString.

Returns:: the title format string
See Also:: titleFormatString, setTitleFormatString(java.lang.String), getTitle()

setWizardName

public void setWizardName(java.lang.String name)

Sets the wizardName to the specified name.

Parameters:: name - the name of the wizard
See Also:: getWizardName()

getWizardName

public java.lang.String getWizardName()

Returns the name of the wizard.

Returns:: the name of the wizard
See Also:: setWizardName(java.lang.String)

addPage

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

Adds a page instance and its corresponding name to the wizard, and adds the page name to the end of the path. The page variable has a null value if not yet instantiated. Calls WizardPageDeck method addPage(String pageName, WizardPageInterface page) through the deck object.

Every page must have a unique identifying name, pageName. WizardPageInterface objects may only be added one time, with one name. If a page with the same pageNamewas previously added, or the * page object was already added under another name, then an IllegalArgumentException is thrown.

Parameters:: pageName - the name of the page; page - the instance of the page corresponding to the name pageName
See Also:: addPage(String pageName), addPages(String[] pageNames), deck

addPage

public void addPage(java.lang.String pageName)

Adds the name of a page to the wizard, and adds the page name to the end of the path. If delayed creation of pages has been opted for, then the page corresponding the the name pageName will be instantiated by calling the createNamedPage method at the time the page is initially shown. The createNamedPage method must be overridden to add pages in this manner.

If the option to create pages in advance is chosen, then this method first creates the page by calling the createNamedPage method and adds it by calling addPage(String pageName, WizardPageInterface page).

If a page with the same pageNamewas previously added, an IllegalArgumentException is thrown.

Parameters:: pageName - the name of the page to be added to the wizard.
See Also:: createNamedPage(String pageName), addPage(String pageName, WizardPageInterface page), addPages(String[] pageNames)

addPages

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

Adds the page names to the wizard, and to the end of the path. If delayed creation of pages has been selected, then the instantiation of the pages will be delayed until the time they are shown for the first time. The createNamedPage method must be overridden to add pages in this manner. The order of names in the pageNames array is not important, and doesn't affect the order or traversal of pages in the wizard.

If any of the names in the pageNames array were previously added, an IllegalArgumentException is thrown.

Parameters:: pageNames - array of wizard page names to be added to the wizard.
See Also:: createNamedPage(java.lang.String)

removePage

public void removePage(java.lang.String pageName)

See Also:: WizardPageDeck.removePage(java.lang.String)

createNamedPage

public WizardPageInterface createNamedPage(java.lang.String pageName)

This method should be overridden by Wizard subclasses if delayed page instantiation is selected. The code should create and return a WizardPageInterface instance corresponding to pageName. This method is called when delayed instantiation was selected, and the page is being shown for the first time. It is not necessary call this method directly.

Parameters:: pageName - the name of the page to create an instance of
Returns:: instance of WizardPageInterface corresponding to pageName

setPath

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

The path defines the traversal order of the pages in the wizard. This method clears the current path, and sets it to the order of the pages in the pageNames array. The first page in the path is shown in the wizard.

Parameters:: pageNames - an array of page names defining the desired order of the path through the wizard
See Also:: appendPath(java.lang.String[])

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.

Parameters:: pageNames - an array of page names to be added to the path following the current page name, replacing any names currently there.
See Also:: setPath(java.lang.String[])

getPath

public java.lang.String[] getPath()

See Also:: WizardPageDeck.getPath()

handleButtonCommand

public void handleButtonCommand(java.lang.String actionCommand)

This method is called when a button in the ButtonNavigationPanel is activated. Wizard subclasses that add custom buttons should override this method to provide the desired functionality.

If actionCommand is equal to ButtonNavigationPanel.HELP_COMMAND, the help method is called.

If actionCommand is equal to ButtonNavigationPanel.CANCEL_COMMAND, the cancel method is called. If closeWindowOnCancel is set to true, then the window containing the Wizard is disposed of by calling method closeWindow, and then the cancel method is called.

If actionCommand is equal to ButtonNavigationPanel.NEXT_FINISH_COMMAND, the finish method is called.

Parameters:: actionCommand - the action command associated with the button that fired an actionEvent.

enableButtons

public void enableButtons()

See Also:: ButtonNavigationPanel.enableButtons()

help

public void help()

This method should be overidden by subclasses to provide the desired functionality when the Help button is activated in the ButtonNavigationPanel.

cancel

public void cancel()

This method should be overidden by subclasses to provide the desired functionality when the Cancel button is activated in the ButtonNavigationPanel. Wizard subclasses should call super.cleanup() method at the end of this method, to invoke the WizardPageInterface cleanup method on the individual wizard pages.

See Also:: cleanup()

wasCancelled

public boolean wasCancelled()

Returns a boolean value indicating if the Wizard has been cancelled from.

Returns:: true if the Wizard was cancelled from otherwise false

displayCancelPrompt

public int displayCancelPrompt()

Displays a confirmation message dialog with Yes and No options. The title of the dialog is "Cancel?", and the message is "Are you sure?".

Returns an int value representing the response to the message dialog. Valid values are JOptionPane.YES_OPTION, and JOptionPane.NO_OPTION.

This method is called from the WizardDialog windowClosing method if promptOnClose is set to true. If the Yes option in the message dialog is selected, and closeWindowOnCancel is set to true, the closeWindow method is called. Then the cancel method is called. If the closeWindowOnCancel is set to false, then only the cancel method is called.

Returns:: an int value representing the response to the message dialog, where valid values are JOptionPane.YES_OPTION, and JOptionPane.NO_OPTION

closeWindow

public void closeWindow()

Disposes of the Window that contains the Wizard

getEscAction

public javax.swing.Action getEscAction()

Returns the Action whose actionPerformed method is invoked when the ESC key is activated. When activated and the promptOnClose property is true, this Action calls the displayCancelPrompt method to display a prompting message dialog asking the user to verify the closing action.

If the Yes option in the message dialog is selected, and the closeWindowOnCancel property is true, the closeWindow method is called, disposing of the Window containing this Wizard, and then the cancel method is called. If the closeWindowOnCancel property is false, the cancel method is called, but the Window containing this Wizard is not disposed of.

If the promptOnClose property is false, no prompting message dialog is shown. The Window containing this Wizard is disposed of by calling the closeWindow method if the closeWindowOnCancel property is true, and the cancel method is called. Otherwise the cancel method is called without disposing of the Window containing this Wizard.

doWindowClosingAction

public void doWindowClosingAction()

If the promptOnClose property is true, this method calls the displayCancelPrompt method to display a prompting message dialog asking the user to verify the closing action.

finish

public void finish()

This method should be overidden by subclasses to provide the desired functionality when the Finish button is activated in the ButtonNavigationPanel. Wizard subclasses should call super.cleanup() method at the end of this method, to invoke the WizardPageInterface cleanup method on the individual wizard pages.

See Also:: cleanup()

cleanup

protected void cleanup()

Calls WizardPageInterface method cleanup on individual wizard pages.

See Also:: finish(), cancel()

showPage

public void showPage(java.lang.String pageName)

Shows the page corresponding to the name pageName in the wizard. If pageName is not in the current path, an IllegalArgumentException is thrown.

Parameters:: pageName - the name of the page to be shown in the wizard

getPageName

public java.lang.String getPageName(WizardPageInterface page)

Returns name of a WizardPageInterface object page.

Parameters:: page - a WizardPageInterface object

getPage

public WizardPageInterface getPage(java.lang.String pageName)

Returns a WizardPageInterface object corresponding to its name pageName.

Parameters:: pageName - the name of the WizardPageInterface object to return

getCurrentPageName

public java.lang.String getCurrentPageName()

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

getTitle

public java.lang.String getTitle()

Returns the title of the current page being shown in the wizard, or null if the path has not been set. Uses com.sas.text.Message format method to set the current page's title, formatting it according to the pattern specified in the titleFormatString.

The default titleFormatString is "{0} -- Step {1} of {2} {3}", where the parameters represent:

{0} - the name of the wizard
{1} - current page number
{2} - final page number
{3} - the current page information

Subclasses that change the default titleFormatString should override this method to provide correct formatting.

Returns:: the title of the current page being shown in the wizard, or null if the path has not been set
See Also:: titleFormatString, setTitleFormatString(java.lang.String), getTitleFormatString(), Message.format(java.util.ResourceBundle, java.lang.String, java.lang.Object[])

getDefaultImage

public java.lang.String getDefaultImage()

Returns the source (location) for obtaining the default image for the wizard. This method may be called in a page's getStatusImage() method to return an image source that is common to multiple pages.

Returns:: a string specifying the source path or URL for obtaining the default image
See Also:: setDefaultImage(java.lang.String), WizardPageInterface.getStatusImage()

setDefaultImage

public void setDefaultImage(java.lang.String imageSource)

Sets the source (location) for obtaining the default image for the wizard.

Parameters:: imageSource - the source path or URL for obtaining the default image
See Also:: getDefaultImage()

getCurrentImageSource

public java.lang.String getCurrentImageSource()

Returns a string specifying the source (location) for obtaining the current image being shown in the statusImagePanel of the wizard, or null if an image is not currently being displayed.

Returns:: a string specifying the source (location) for obtaining the current image, or null if an image is not currently being displayed
See Also:: currentImageSource

setImage

public void setImage(java.lang.String imageSource)

Sets the source on the imageView to imageSource, and adds imageView to the statusImagePanel. If imageSource is null, the imageView is removed from the statusImagePanel.

Parameters:: imageSource - the location for obtaining the image to be shown
See Also:: statusImagePanel, imageView

createButtonPanel

public ButtonNavigationPanel createButtonPanel()

Constucts and returns a ButtonNavigationPanel containing buttons used to navigate through the wizard. The ButtonNavigationPanel returned has Back, Next, Cancel, and Help buttons. The respective action commands associated with these buttons are BACK_COMMAND, NEXT_FINISH_COMMAND, CANCEL_COMMAND, and HELP_COMMAND. The buttons are right aligned within the panel.

Wizard subclasses which require different buttons may override this method to create a ButtonNavigationPanel with the appropriate buttons, or may add or remove buttons through the ButtonNavigationPanel addButton and removeButton methods.

Returns:: a ButtonNavigationPanel object containing buttons used to navigate through the wizard
See Also:: buttonPanel, ButtonNavigationPanel, createVisuals()

getButtonPanel

public ButtonNavigationPanel getButtonPanel()

Returns the buttonPanel.

Returns:: the buttonPanel
See Also:: buttonPanel

createSeparator

public javax.swing.JComponent createSeparator()

Returns a separator component used in the wizard layout.

Returns:: a separator component used in the wizard layout
See Also:: createVisuals()

createWizardPageDeck

public WizardPageDeck createWizardPageDeck()

Factory method used to construct the deckobject. Constructs and returns a WizardPageDeck object.

Returns:: a WizardPageDeck object to which the wizard pages may be added
See Also:: deck, WizardPageDeck, createVisuals()

createStatusImagePanel

public javax.swing.JPanel createStatusImagePanel()

Constructs and returns a JPanel object.

Returns:: an empty JPanel object
See Also:: statusImagePanel, createVisuals()

getStatusImagePanel

public javax.swing.JPanel getStatusImagePanel()

Returns the statusImagePanel.

Returns:: the statusImagePanel
See Also:: statusImagePanel

propertyChange

public void propertyChange(java.beans.PropertyChangeEvent pce)

Processes a PropertyChangeEvent.

Specified by:: propertyChange in interface java.beans.PropertyChangeListener

Parameters:: event - the event indicating what property changed

createWizardImageView

protected ImageView createWizardImageView()

Factory method used to create the imageView object. Returns an WizardImageView object with a black background color, and transparency set to false.

See Also:: imageView, createVisuals()

setCloseWindowOnCancel

public void setCloseWindowOnCancel(boolean closeAction)

Set whether the window containing the wizard should be disposed of when either the cancel button or the close button in the window's title bar are selected, before the cancel method is called.

See Also:: closeWindowOnCancel

getCloseWindowOnCancel

public boolean getCloseWindowOnCancel()

Returns a boolean value indicating if the window containing the wizard should be disposed of when either the cancel button or the close button in the window's title bar are selected, before the cancel method is called.

Returns:: a boolean value indicating if the window containing the wizard should be disposed of when either the cancel button or the close button in the window's title bar are selected, before the cancel method is called.
See Also:: closeWindowOnCancel

setPromptOnClose

public void setPromptOnClose(boolean promptAction)

Sets whether a message should be displayed when the close button in the title bar of the window containing the wizard is selected. If set to true, the method is called to display a message asking the user to verify the close action. when the close button is sdisplayCancelPromptelected.

See Also:: promptOnClose, displayCancelPrompt()

getPromptOnClose

public boolean getPromptOnClose()

Returns a boolean value indicating if a message should be displayed when the close button in the title bar of the window containing the wizard is selected. If true, then a message dialog is displayed by calling method displayCancelPrompt, asking the user to verify the close action.

Returns:: a boolean value indicating if a message should be displayed when the close button in the title bar of the window containing the wizard is selected
See Also:: promptOnClose, displayCancelPrompt()

getWizardDialog

public static com.sas.swing.visuals.wizard2.WizardDialog getWizardDialog(javax.swing.JFrame frame,
                                                                         Wizard wizard)

Creates and returns a dialog containing wizard.

Parameters:: frame - the frame that owns this dialog; wizard - the wizard object to place in this dialog

showWizardDialog

public static void showWizardDialog(javax.swing.JFrame frame,
                                    Wizard wizard)

Displays a Wizard object in a dialog. The Wizard object will be centered over the specified frame.

Parameters:: frame - the frame that owns this dialog; wizard - the wizard object to show in this dialog

All Libraries

This Library

Package

Class

Use

Tree

Deprecated

Index

Grand Index

Help

Components

PREV CLASS NEXT CLASS

FRAMES NO FRAMES

SUMMARY: NESTED | FIELD | CONSTR | METHOD

DETAIL: FIELD | CONSTR | METHOD

com.sas.swing.visuals.wizard2 Class Wizard

RB_KEY

backAction

finishAction

next_finishAction

cancelAction

helpAction

closeWindowOnCancel

promptOnClose

CREATE_WHEN_SHOWN

CREATE_IN_ADVANCE

whenToCreatePage

imageView

currentImageSource

defaultImage

wizardName

deck

buttonPanel

titleFormatString

statusImagePanel

deckAndImagePanel

wasCancelled

Wizard

Wizard

Wizard

getNext_FinishAction

getCancelAction

getHelpAction

getFinishAction

getBackAction

createLayout

createVisuals

setTitleFormatString

getTitleFormatString

setWizardName

getWizardName

addPage

addPage

addPages

removePage

createNamedPage

setPath

appendPath

getPath

handleButtonCommand

enableButtons

help

cancel

wasCancelled

displayCancelPrompt

closeWindow

getEscAction

doWindowClosingAction

finish

cleanup

showPage

getPageName

getPage

getCurrentPageName

getTitle

getDefaultImage

setDefaultImage

getCurrentImageSource

setImage

createButtonPanel

getButtonPanel

createSeparator

createWizardPageDeck

createStatusImagePanel

getStatusImagePanel

propertyChange

createWizardImageView

setCloseWindowOnCancel

getCloseWindowOnCancel

setPromptOnClose

getPromptOnClose

getWizardDialog

showWizardDialog

com.sas.swing.visuals.wizard2
Class Wizard