com.borland.primetime.wizard
Interface Wizard

All Known Implementing Classes:
BasicWizard

public interface Wizard

A Wizard is a multi-step UI interface used to walk a user through an otherwise complicated or tedious task. Implementations of Wizard manage a series of WizardPage objects, and control the interactions between them.

Wizards are presented in the Gallery or the wizards menu as options using the WizardAction class. A WizardAction is registered via the static WizardManager method public static void registerWizardAction(WizardAction wizardAction) When invoked, the Wizard instance (implementation of this interface) is retrieved from the WizardAction, and a WizardDialog is created to host the Wizard.

Once created, a Wizard acts as the 'brains' of the wizard session by providing a series of WizardPages for the user to navigate and fill out. The Wizard also houses the logic that binds the series of steps together. Once the steps have been completed and all the necessary information has been collected from the user, the Wizard is responsible for doing the actual work, whatever that may be.

During the wizard session, the Wizard can interact with the WizardHost to change settings on the wizard dialog: This includes changing the total number of steps on the fly when the user selects a different path in the wizard, enabling and disabling the next and finish buttons (as the user fills in necessary data to advance to the next step), and providing a dialog parent if the Wizard wishes to display a modal dialog for more input from the user.

See Also:
WizardManager, WizardAction, WizardPage, WizardHost

Method Summary
 WizardPage finish(WizardPage currentPage, WizardHost host)
           The user has clicked Finish, and the Wizard should go do its action.
 java.lang.String getWizardTitle()
          Returns the title for this Wizard.
 void help(WizardPage currentPage, WizardHost host)
          The user has clicked the Help button while viewing the specified page.
 int initTotalSteps()
          Returns the initial total number of steps for this Wizard.
 WizardPage invokeWizard(WizardHost host)
          Returns the first page in this Wizard.
 WizardPage next(WizardPage currentPage, WizardHost host)
           Returns the next WizardPage - after the specified WizardPage.
 void wizardCompleted()
           The user has clicked Finish or Cancel, and the Wizard has completed its action.
 

Method Detail

getWizardTitle

public java.lang.String getWizardTitle()
Returns the title for this Wizard. This is displayed as the title of the Wizard followed by the step number and total number of steps. If there is only 1 step in the Wizard, this title is displayed as-is.
Returns:
The dialog title for this Wizard

initTotalSteps

public int initTotalSteps()
Returns the initial total number of steps for this Wizard. This can change on the fly if an option is picked on a particular page that expands the Wizard into more or less steps. The Wizard or WizardPage simply calls the WizardHost method: public void setTotalSteps(int count) , and the Wizard title updates to reflect the new range.
Returns:
the initial total number of steps.

invokeWizard

public WizardPage invokeWizard(WizardHost host)
Returns the first page in this Wizard. This is the page that is displayed initially when the Wizard appears. This method is called each time the wizard is invoked.
Parameters:
host - The WizardHost that will be hosting the Wizard. The host is supplied so that the Wizard can optionally start on a different page based on the context of the Browser.
Returns:
The first WizardPage for this Wizard. If null is returned, the Wizard session is halted.

next

public WizardPage next(WizardPage currentPage,
                       WizardHost host)
                throws VetoException

Returns the next WizardPage - after the specified WizardPage.

This method is called each time the user moves forward in the Wizard. The order of pages (and their corresponding step number) is maintained by the WizardHost. When the user clicks the 'Back', the Wizard is not asked for the previous page, it is already cached by the WizardHost - but when the user clicks next, the Wizard is again asked for the next page, to allow for steps to be changed based on settings in prior steps, or for new steps to be injected or removed. The Wizard or WizardPage can call the WizardHost method: public void setTotalSteps(int count) to change the total number of steps at any time.

Parameters:
currentPage - The current WizardPage displaying in the Wizard
host - The host of the Wizard
Returns:
The next WizardPage for the Wizard to display
Throws:
VetoException - Can be thrown to stop forward navigation

finish

public WizardPage finish(WizardPage currentPage,
                         WizardHost host)
                  throws VetoException

The user has clicked Finish, and the Wizard should go do its action.

Normally, this method returns null, and the Wizard disappears. If there is a problem on a specific page, a WizardPage is returned, the Wizard jumps to that page.

Parameters:
currentPage - The current WizardPage displaying in the Wizard
host - The host of the Wizard
Returns:
null if all is well (the Wizard will dispose), or if there is a problem, the WizardPage for the Wizard to jump to and display
Throws:
VetoException - May be thrown to stop the finish operation, and leave the Wizard on the current WizardPage.

help

public void help(WizardPage currentPage,
                 WizardHost host)
The user has clicked the Help button while viewing the specified page.
Parameters:
currentPage - The current WizardPage displaying in the Wizard
host - The host of the Wizard

wizardCompleted

public void wizardCompleted()

The user has clicked Finish or Cancel, and the Wizard has completed its action. This is a notification to the Wizard that the process is complete, and any aide to the garbage collector at this point is much appreciated.