Dialogs and Wizards

Chapter 16, Dialogs and Wizards, covered the options for definition and implementation of dialogs that extend the basic function of the Eclipse Platform. This project, com.ibm.jdg2e.wizards.newwizards, provides a detailed look at how multiple page wizards can be defined and managed. This includes an example of a wizard with pages defined statically and a wizard that dynamically adds pages.

There are other projects you can review for additional dialog examples. The Simple Model View plug-in, located in the com.ibm.jdg2e.view.simplemodel project, includes examples of wizard programming and property page creation. This includes the ability to open the common Properties dialog for a specific object in a viewer. Additional wizard examples are defined by the Resource Extensions (com.ibm.jdg2e.resources.extensions) and Mini-Spreadsheet plug-in (com.ibm.jdg2e.msseditor.ide). The User Settings API Demonstration plug-in (com.ibm.jdg2e.usersettings) includes examples of preference and property page creation. This includes the initialization of preference values.

Running the Example

The goal of this demonstration is an understanding of the options you have for page management in a multi-page wizard. This demonstration is best run as a project in your workspace that you can test. This is because you will be asked to modify the source as a last step. You can use it as an installed plug-in for this demonstration, but you will have to skip the last step.

First, some basics on the code so you understand what is going on. There are two wizards: a Defined Page Wizard and a Dynamic Page Wizard, and one wizard page called PageChain. This page can be added to a wizard multiple times, each time with a different name and some control settings that define its behavior. The page can either act as a simple page without any control over page progression or be more dynamic and use the user input to determine if another page is required and which page that might be.

The wizard page can be added with a pageComplete status of true or false. When added as false the page must trigger a state change before the wizard framework will allow it to proceed to the next, or if all pages are then complete, finish the wizard processing. In addition the wizard page has user interface controls that determine behavior. One user interface label attempts to populated itself with content from a text input field on the previous page. This only works in certain situations as you will soon see.

Defined Page Wizard

In the defined page example three wizard pages (PageChain instances) are added to the wizard. The first is defined as incomplete, the rest are complete. These pages do not participate in the process of determining the next page, they leave it to the wizard. That is why portions of the page user interface are disabled. This testing cycle will help you understand the capabilities of this basic wizard structure.

From the Java or Plug-in Development perspective, launch and run a runtime workbench (Run > Run As > Eclipse Application).
Open the File > New wizard selection dialog and select the JDG2E > Defined Pages Structure Demo wizard, then select Next to start the wizard. This is a wizard whose addPages method defines three pages.
The same code is used for each page in the wizard, this PageChain class extracts information about the pages known to the wizard and progression through the pages for display in the user interface. The page attempts to read content from the page before it in sequence, and customize the user interface for that page instance.
The page is opened with an initial state of incomplete, so you will need to select the toggle option to complete the page first. Also enter some text in the entry field for use by the next page.

Select Next to enter the next page of the wizard.
The page content will keep you informed on position in the pages known to the wizard and reflect any customization of the user interface that was possible based on the previously entered text. This second page in the wizard will not show any customization of the user interface. When pages are defined in the addPages method their user interface is created immediately upon entry to the wizard, so no customization was possible. This is why the user input is not displayed on the subsequent page.

Dynamic Page Wizard

In the dynamic page example only one PageChain wizard page instance is added to the wizard. This page is defined as incomplete; it is also responsible for identifying if another page is available, and which page will be next. Previously disabled portions of the user interface are enabled. This testing cycle will help you understand the capabilities of this open-ended wizard structure.

Open the File > New wizard selection dialog and find and select the JDG2E > Dynamic Pages Structure Demo wizard, then select Next to start the wizard. This is a wizard whose addPages method defines only one page.
The first page is incomplete, so select the option to mark it complete.
The PageChain implementation also includes a customized getNextPage method which can support the addition of new pages dynamically.
Select the option to identify another page is required and then select the option to use an alternative page instead. The wizard page should now show you as being on the first of three pages known to the wizard.

Select Next, the AltPage2 page known to the wizard will be shown.
This progression is controlled by the getNextPage method. The input on the previous page will be included in the user interface as well. This is because the widgets for a given page are not created until that page is entered for the first time when dynamically identified pages are used in a wizard.
Select Back to return to the first page, deselect the alternate page option, and then select Next.
You will now be on a different second page. If you request another page and go forward again, you will jump over the alternative page previously visited.

The page progression is completely dynamic and allows you to back up and change your mind. As shown in the list of traversed pages the wizard is always able to tell which pages were visited as compared to the larger set actually known to the wizard.

Modifying Defined Page Wizard to Support a Dynamic Page User Interface

The first visit to the defined page wizard structure showed that the user interface for a page was created up front. This early user interface creation can actually be delayed; this allows you to react to user input while using a simpler wizard structure.

You may need to stop the testing cycle if you are unable to dynamically load code changes into your testing environment.
Edit the DefinedPageWizard class and find the createPageControls method.
The implementation we shipped simply called the inherited implementation to allow the wizard framework to perform the default processing. To delay the creation of the user interface for a defined page wizard all you need to do is disable this framework method.
Comment out this line of code in the createPageControls method.
super.createPageControls(pageContainer);
This will disable early page creation, but the wizard will still work fine.
Repeat the first test cycle, be sure to enter some text on the first page and see if the second page shows this text in the customized user interface.

Roadmap of the Example

The JDG2E: Wizard Page/Flow Control Demonstration plug-in is designed to help you understand how progression through a set of wizard pages can be controlled. Below are the key classes from the com.ibm.jdg2e.wizards.newwizards package that are used to implement the defined and dynamic wizards.

Class (All)	Description
`DefinedPageWizard`	Wizard that adds all pages up front in the `addPages` method.
`DynamicPageWizard`	Wizard that adds only one initial page in the `addPages` method and allows all other pages to be added dynamically.
`PageChain`	Wizard page that interrogates the wizard to display a list of all pages known to the wizard and all pages that have been traversed. The page also control the dynamic progression process by overriding the `getNextPage` method. The customized method determines if another page is required and which page that will be at the point of page progression.