|
Previously I discussed how to build preference
pages in Eclipse. Preference pages are used to gather and save user
preferences regarding the user's workspace.
Wizards are another beast entirely. Wizards are
generally thought of as a series of dialogs that guide the user through
a process. But unlike most modern user interface methods, "the user is
forced to perform the task in a specific sequence," according to the Wikipedia
definition.
Wizards are most useful for helping users get
through complex or infrequent tasks "where the user is unfamiliar with
the steps involved," says Wikipedia.
In terms of Eclipse, a wizard is a JFace element
that leads a user through a sequence of wizard pages. The user is
forced to perform a task in a specific sequence, but can go backward
and forward through the sequence, making it easier to perform the task.
In some instances, the user can short-circuit the
entire sequence and just finish the task when enough information has
been provided. In this article, and a few more to come, I'll describe
how to launch and build your own Eclipse wizards, and what and what not
to do with them in the process.
Let's begin by looking how to use a wizard that
we'll ultimately create. Below is a code snippet of how you can ideally
open a wizard and get the information back from it after the user has
completed it.
import org.eclipse.jface.wizard.WizardDialog;
public class SampleView extends ViewPart {
...
private String openWizard(String model) {
WizardExample wizard = new WizardExample(model);
WizardDialog dialog = new
WizardDialog(getSite().getShell(), wizard);
dialog.create();
dialog.getShell().setSize( Math.max(300,
dialog.getShell().getSize().x), 200);
dialog.setTitleImage(Activator.getImageDescriptor("icons/sample.gif").createImage());
dialog.open();
if (dialog.getReturnCode() == WizardDialog.OK)
return model;
else
return null;
}
...
}
The first thing the method does is create the
specific wizard. It then wraps it in an
org.eclipse.jface.wizard.WizardDialog. In the example, the specific
wizard—which we'll build in the next article—is the class WizardExample.
Note how I pass a model object into the wizard and
get it back after the wizard has closed. In general, this is a good
idea. A wizard and the corresponding wizards pages will operate on an
object that you should initialize and get back after the modifications
have been done.
When I open the wizard, I pass the model object
in, and if the wizard closes correctly (by the user hitting the Finish
button), I return the model object.
Another approach is to pass an object in, which is
cloned by the wizard. Then send a message to the wizard after it closes
successfully to get the cloned model object back.
Each approaches has its advantages and
disadvantages. I prefer the former, because if I want the wizard to
work with a clone, then I pass it a clone when I create the wizard. The
wizard shouldn't care if it's working with a clone of a model object or
the real one. It should just care about taking the information from the
model, presenting it to the user, and updating the model when the user
makes modifications to it as a result of interacting with the wizard
pages.
So when working with a wizard, pass a model object
to it—in this example, it's just a String—and have the wizard and
corresponding wizard pages operate on the model. When the wizard closes
successfully, return the model, which will contain the information the
user has provided.
Next time, we'll look at how to create a wizard
with wizard pages to retrieve user information.
|
