Provides a simple API and UI for Wizards, a commonly used UI pattern in GUI
interfaces. Traditionally, everybody has needed to write their own
Wizards from scratch, and such code is painful and hard to get right.
This
library aims to provide a simple, relatively bulletproof API
for writing Wizards. The UI for Wizards is pluggable; the default
implementation conforms to the JLF usability guidelines for
Wizards.
This library was originally designed as a
replacement for NetBeans' Wizards API,
and takes into account the long history
of that API and problems encountered with it over the years. It provides a
simple, easy-to-use solution that enables any Swing application to provide
Wizards with a minimum of code and effort.
Features At A Glance
Assemble a Wizard from a series of panels
Panels put key/value pairs into a java.util.Map
When Finish is pressed, your code evaluates the contents of the Map
and does whatever your wizard does (optionally on a background thread
with progress notification)
Automatic listening to components - for simple cases, just set names
on standard swing components and they will automatically be listened to
and their changes handled
Simple support for multiple branches (dynamically changing sets of steps)
Panels can be validated as the user interacts, or when the user presses
next (including on a background thread)
Support for long running operations with progress indication
Support for end-of-wizard summary panels
Goals
Provide an easy-to-use API for creating wizards
Leverage existing research into how to make wizards easy to use
for end users
Leverage knowledge of known problems in existing wizard APIs to
avoid them in this one
Make it easy to create wizards that end users find easy to use
Minimalism - the API should be low-surface-area, exposing
no more concepts or classes than necessary
Robustness - keep the code simple and heavily covered by tests
A NetBeans Module that adds the Wizard Library,
its source and Javadoc to the set of registered libraries in the NetBeans IDE
News
2/8/06 - Summary pages now use proportional fonts, instructions panel
is accessible
12/30/06 - WizardDisplayer.installInContainer() - use a wizard ui in any
ad-hoc swing container
12/29/06 - Improvements contributed by Stanley Knutson:
WizardPanel allows veto of "next" or "prev" button actions (possibly
using a background thread with busy indication); Busy icon alternative for
long-running deferred result computations; The map of values can be pre-initialized when
the wizard is started; the size of the wizard can be specified when starting.
Validation can now be deferred until Next is pressed, optionally on a background
thread
9/24/06 - Examples of new features in CVS - see DeferredResultDemo,
SummaryPageDemo and WizardPageDemo
9/24/06—Support for asynchronously computed results w/ progress
bar, and support for JLF-style summary panels added. Just return an instance of
Summary or an instance of DeferredWizardResult from
the appropriate finish() methods, or return pass a Summary
object to DeferredWizardResult.ResultProgressHandle.finished();
new Quick Start Guide
9/23/06—WizardPage now listens to nested
containers so any named component can participate in the wizard settings map with
no code needed.
8/20/05—A convenience class, WizardPage, has been added,
which makes it even easier to create new wizards, often doing almost nothing
but using your favorite GUI designer. See the first item in the
FAQ.
Status
This library has not yet reached 1.0 status (we reserve the right to make
API changes), but is stable in terms
of functionality and used in many projects. If you
encounter a problem, please file bugs; bugs with unit tests attached are
much appreciated.
To Do:
JDK 5 and up enhancements: Allow WizardPage ids/descriptions via
annotations, generify where it makes sense