15

Wizard Creator

Features of JCWizard and JCSplitWizard  Classes

Constructors and Methods  Events  Examples

---

15.1 Features of JCWizard and JCSplitWizard

JCWizard lets you create and manage a Wizard-style group of dialogs by supplying informative events and special page components with standard buttons. You add a JCWizardListener to your JCWizardPages to invoke the actions that each page needs to perform.

Figure 47 :  A sample Wizard page.

JCWizard supplies these features:

• Standard Next, Back, Finish, Cancel and Help buttons that are characteristic of Wizard dialogs.
• You provide instructions for the end-user on each page, and define the actions corresponding to the choices made by the end-user.
• The Wizard's pages are instances of JCWizardPage. As is usual with Swing components, you do not add children to JCWizardPage. Instead, you call its getContentPane() method and add items to it.

The JCWizard component is a container that manages JCWizardPages. The pages are added to it in a way that only one of them shows at a time, but navigation buttons let the end user move back and forth through the deck. The component posts a JCWizardEvent as changes occur.

The JCWizardPage provides a getContentPane() method to return the panel to which you add content. It automatically builds content to manage the Next, Previous, Finish, Cancel, Help buttons at the bottom right of the page.

JCSplitWizard, on the other hand, creates a split-Wizard layout, which allows for one page to be created with multiple panels, rather than multiple pages with one panel.

Figure 48 :  A sample split-Wizard page.

The button features provided for a standard Wizard are also available for the split-Wizard, though there is only one set that will apply to the entire Wizard. (The Back button is automatically unavailable on the first page, and the Next button is automatically unavailable on the last page.) Pages that are added are displayed in the right pane, while the left pane is used for the progress list, if one has been created.

---

15.2 Classes

The classes in the JCWizard group are:

JCWizard	Creates and manages a Wizard-style set of dialogs. To create your own Wizard, design JCWizardPages and add Wizard listeners.
JCWizardPage	A JCBox that knows about Wizard-style actions.
JCWizardEvent	The event object that carries information about changes to JCWizard pages.
JCWizardListener	The listener for JCWizard events.

The classes in the JCSplitWizard group are:

JCSplitWizard

Creates a wizard with two panes, and a bottom button panel. The panes can contain any component, or left pane can optionally contain an automatically generated list of Steps.

---

15.3 Constructors and Methods

JCWizard Constructors

JCWizardPage's constructor lets you specify the buttons you want on a page by combining JCWizardPage constants, as follows:

page = new JCWizardPage(JCWizardPage.NEXT |
             JCWizardPage.PREVIOUS |
             JCWizardPage.FINISH |
             JCWizardPage.CANCEL |
             JCWizardPage.HELP);

JCSplitWizard Constructors

JCSplitWizard has two constructors. There is a constructor that can be used to create a standard two-pane Wizard, along with buttons and an empty string as a title. The second constructor is equipped with two arguments:

• The int argument that specifies which buttons should be included;
• The String title that specifies the title of the progress list.

JCWizard Methods

JCWizard inherits both properties and methods from JPanel. Listed here are the methods that JCWizard itself defines to provide the needed functionality for managing Wizard pages.

Method	Description
add()	Adds a page to the Wizard.
addWizardListener()	Adds a new JCWizardListener to the list.
cancel()	Invokes the registered "cancel" action.
finish()	Invokes the registered "finish" action.
first()	Moves to the first page in the Wizard.
help()	Invokes the registered "help" action.
last()	Moves to the last page in the Wizard.
next()	Advances to the next page in the Wizard.
previous()	Moves to the previous page in the Wizard.
show()	The method takes a parameter (String name), and moves to the Wizard page with the specified name.

JCSplitWizard Methods

Listed here are the methods that JCSplitWizard itself defines to provide the needed functionality for managing split-Wizard pages.

Method	Description
addPage()	Adds a page to the right panel of the Wizard.
getLeftPanel()	Accesses the left panel, which can contain an automatically generated list of steps based on titles, an image, help text, or any other desired components.
cancel()	Invokes the registered "cancel" action.
finish()	Invokes the registered "finish" action.
first()	Moves to the first page in the Wizard.
help()	Invokes the registered "help" action.
last()	Moves to the last page in the Wizard.
next()	Advances to the next page in the Wizard.
previous()	Moves to the previous page in the Wizard.

---

15.4 Events

A JCWizard or JCSplitWizard listens for JCWizardEvents. A JCWizardEvent contains information on the Object that triggered the event, the Component's current page and new page, two Booleans, whether the event occurred on the last page, and whether the event should be allowed to finish processing.

Interface JCWizardListener methods are:

nextBegin	Invoked before advancing to the next page. Calling e.setAllowChange(false) will prevent the advance to the next page. Check e.isLastPage() to see if you are on the last page.
nextComplete	Invoked after advancing to the next page.
previousBegin	Invoked before returning to the previous page. Calling e.setAllowChange(false) will prevent the return to the previous page.
previousComplete	Invoked after advancing to the previous page.
finished	Invoked if a "finish" action is triggered.
canceled	Invoked if the "cancel" action is triggered.
help	Invoked if the "help" action is triggered

---

15.5 Examples

Please refer to examples.elements.Wizard.java to see how to construct regular Wizard pages. Briefly, these are the steps:

1. Add an instance of a JCWizard to a JPanel or similar component.
2. Create a JCWizard page.
3. Specify the buttons that should appear on each page.
4. Name the page.
5. The content for each page will likely be a JPanel. Add it to the Wizard page's content pane.
6. Add the page to the JCWizard.
7. Continue adding pages as necessary.

Please refer to examples.elements.SplitWizard.java to see how to construct split-Wizard pages. Briefly, these are the steps:

1. Create an instance of a JCSplitWizard, adding the desired buttons and determining whether or not a progress list should be generated.
   To create a progress list, pass the title of the list as the second argument in the constructor.
   If no progress list is desired, simply leave the title null, or use the no-argument constructor.
2. Create content for the right-hand wizard pages. These can be any instance of JComponent.
3. Add the pages to the wizard using wizard.addPage(JComponent, page title), where page title is the title of the page.
4. Add the wizard to a container; add listeners, if desired.
5. If a progress list has not been specified, call getLeftPage() to add content to the left pane.