Open source Java projects: The Wizard API

Swing-based application wizardry with the Wizard API

By Jeff Friesen, JavaWorld.com, 04/07/08

If you're faced with creating a Swing-based wizard from scratch, you'll want to know about Tim Boudreau's Wizard project. This installment of Jeff Friesen's Open source Java projects series gets you started with the Wizard API and concludes with a hands-on installation wizard that is sure to please users and impress the boss. 

Editor's note: This article has been updated with a new sidebar: WizardException fixed!

Wizards (also known as assistants to Mac developers) guide users through complicated tasks such as installing software and setting up network connections. Although wizards are designed to be easy to use, creating them can be difficult. Fortunately for Java developers, NetBeans guru Tim Boudreau has created an open source project that takes the pain out of creating Swing-based wizards, by offering features such as

• An architecture that handles much of the work of implementing a wizard
• Automatic capture of standard Swing component values to a map during data entry -- your wizard code can interrogate the map when it's time for the wizard to do its thing
• Input validation
• Handling of lengthy wizard tasks on a background thread (with progress notification) so as not to disrupt the event-dispatching thread
• End-of-wizard summary panels
• Meta wizards

In this installment of the Open source Java projects series, I'll introduce you to Tim's Wizard project. I'll start by showing you how to obtain Wizard's library and documentation, as well as introducing you to its examples. Next, I'll take you on a tour of Wizard's API, pointing out interesting features and things you should avoid. Finally, you'll have the opportunity to create a MakeInstaller application, and see for yourself a realistic example of Wizard's usefulness.

Get started with Wizard

The Wizard project, which is hosted on Java.net, facilitates the task of creating Swing-based wizards via an API and implementation library. Visit the Wizard Project main page to download the library's (ver. 0.992) wizard.jar distribution file. The library's source code is available in the CVS.

To begin familiarizing yourself with Wizard, follow the Quick Start Guide and Frequently Asked Questions links on the Wizard project page. You can also explore the online API documentation by following the Javadoc (online) link, or download the documentation's WizardAPI.zip file by following the Download the Javadoc (zip file) link.

Wizard examples

Clicking Java WebStart Demo on the Wizard project page will lead you to a demonstration of a NetBeans tool, which uses Wizard to implement its own wizard. Figure 1 reveals this wizard's dialog box, which presents the first step in the sequence of steps to complete.

Figure 1. NetBeans Module Generator for Swing Components wizard. (Click to enlarge.)

The dialog box's left "sidebar" panel presents the wizard's steps over a decorative image -- the current step is bolded. The right panel presents the step's page of GUI components. Navigation, Finish, and Cancel buttons appear along the bottom.

In addition to the online demo, you can explore basic and advanced example wizards. You first need to build these examples, however. Complete the following steps to build the basic example:

1. Create a wizardpagedemo directory below the current directory.
2. Follow the Basic example source link to download the basic example's AnimalTypePage.java, FinalPage.java, LocomotionPage.java, OtherAttributesPage.java, and WizardPageDemoMain.java source files into wizardpagedemo.
3. Download wizard.jar into the current directory.
4. Invoke the command below (which assumes a Windows XP platform) to compile the basic example's source files:

   javac -cp wizard.jar;. wizardpagedemo\WizardPageDemoMain.java
   

After successfully compiling these source files, invoke the following command (which also assumes Windows XP) to run the basic example:

java -cp wizard.jar;. wizardpagedemo.WizardPageDemoMain

Figure 2 reveals the basic example's wizard dialog box with its introductory page.

Figure 2. The Next button is disabled until you make a selection. (Click to enlarge.)

Both the basic and advanced examples present wizards that request animal information. Unlike the basic example, the advanced example demonstrates multiple wizards.

Archived Discussions (Read only)

Subject

Forum migration complete By Athen

Forum migration update By Athen