This article describes how to create and use Eclipse Wizards. It is based on the Eclipse 4.4 release but covers also the Eclipse 3.x releases.

1. Eclipse Wizards

1.1. What is a wizard

In Eclipse, a wizard is commonly used for the creation of new elements, imports or exports. It can also be used for the execution of any task involving a sequential series of steps. A wizard should be used if there are many steps in the task, and they must be completed in a specific order.

Wizards are meant to take the hassle out of standard, repetitive, or tedious user tasks. If a wizard is started, typically a new modal window is opened. This window blocks the remaining user interface until the user finishes the task in the wizard or cancels the wizard.

The following screenshot shows the second page of a wizard.

Example wizard
JFace orders the buttons differently depending on the platform.

1.2. Wizards and WizardPages

The Wizard class from the org.eclipse.jface.wizard package provides the functionality to build custom wizards. This class controls the navigation between the different pages and provides the base user interface, for example, an area for error and information messages.

A wizard contains one or several pages of the type WizardPage. Such a page is added to a Wizard object via the addPage() method.

A WizardPage must create a new Composite in its createControl() method. This new Composite must use the Composite of the method parameter as parent. It also must call the setControl() method with this new Composite as parameter. If this is omitted, Eclipse will throw an error.

1.3. Starting the Wizard

To open a wizard, use the WizardDialog class from the org.eclipse.jface.wizard package.

WizardDialog dialog = new WizardDialog(shell, new YourWizardClass());
dialog.open();

Typically, a wizard is opened via a menu or toolbar entry or via a SelectionListener on a button.

1.4. Changing the page order

To control the order of the WizardPage object, you can override the getNextPage() method in the Wizard. This allows you to change the order of the pages depending on the data in the wizard and pages.

The following code snippet demonstrates this approach.

// task is an object available in the wizard

private CreateTaskPage1 page1 = new CreateTaskPage1(task);
private CreateTaskPage2 page2 = new CreateTaskPage2();
private CreateTaskPage3 specialPage = new CreateTaskPage3(task);

@Override
public void addPages() {
  addPage(page1);
  addPage(page2);
  addPage(specialPage);
}

@Override
public IWizardPage getNextPage(IWizardPage currentPage) {
    if (todo.isDone()) {
       return specialPage;
    }
    if (currentPage == page1) {
        return page2;
    }
    return null;
}

1.5. Working with data in the wizard

To use the same data in different pages of your wizard, pass them to the wizard pages via their constructor parameters.

The isVisible() method is called whenever the WizardPage either gets visible or invisible. Call the super.isVisible() method and check the current status of the page. If the page is visible, assign the data of your object to the user interface components.

1.6. Updating the Wizard buttons from a WizardPage

The WizardPage class defines the canFlipToNextPage() and setPageComplete() methods to control if the Next or the Finish button in the wizard becomes active.

The Wizard class defines the canFinish method in which you can define if the wizard can be completed.

If the status changes, you can update the buttons in the Wizard (e.g., the Next and the Finish button) from a WizardPage via the getWizard().getContainer().updateButtons() method call.

1.7. Adding your wizard to the New, Import and Export commands

In Eclipse 3.x you can register a wizard via the org.eclipse.ui.newWizards extension point.

This includes your wizard in the standard dialog for new projects which can be used via the command org.eclipse.ui.newWizard.

This is also possible for the export and import wizard commands.

2. Exercise: Wizards Example

The following gives an example of a wizard with two pages.

Create the following MyPageOne and MyPageTwo classes.

package de.vogella.rcp.intro.wizards.wizard;

import org.eclipse.jface.wizard.WizardPage;
import org.eclipse.swt.SWT;
import org.eclipse.swt.events.KeyEvent;
import org.eclipse.swt.events.KeyListener;
import org.eclipse.swt.layout.GridData;
import org.eclipse.swt.layout.GridLayout;
import org.eclipse.swt.widgets.Composite;
import org.eclipse.swt.widgets.Label;
import org.eclipse.swt.widgets.Text;

public class MyPageOne extends WizardPage {
    private Text text1;
    private Composite container;

    public MyPageOne() {
        super("First Page");
        setTitle("First Page");
        setDescription("Fake Wizard: First page");
    }

    @Override
    public void createControl(Composite parent) {
        container = new Composite(parent, SWT.NONE);
        GridLayout layout = new GridLayout();
        container.setLayout(layout);
        layout.numColumns = 2;
        Label label1 = new Label(container, SWT.NONE);
        label1.setText("Put a value here.");

        text1 = new Text(container, SWT.BORDER | SWT.SINGLE);
        text1.setText("");
        text1.addKeyListener(new KeyListener() {

            @Override
            public void keyPressed(KeyEvent e) {
            }

            @Override
            public void keyReleased(KeyEvent e) {
                if (!text1.getText().isEmpty()) {
                    setPageComplete(true);

                }
            }

        });
        GridData gd = new GridData(GridData.FILL_HORIZONTAL);
        text1.setLayoutData(gd);
        // required to avoid an error in the system
        setControl(container);
        setPageComplete(false);

    }

    public String getText1() {
        return text1.getText();
    }
}
package de.vogella.rcp.intro.wizards.wizard;

import org.eclipse.jface.wizard.WizardPage;
import org.eclipse.swt.SWT;
import org.eclipse.swt.events.KeyEvent;
import org.eclipse.swt.events.KeyListener;
import org.eclipse.swt.layout.GridData;
import org.eclipse.swt.layout.GridLayout;
import org.eclipse.swt.widgets.Button;
import org.eclipse.swt.widgets.Composite;
import org.eclipse.swt.widgets.Label;
import org.eclipse.swt.widgets.Text;

public class MyPageTwo extends WizardPage {
    private Text text1;
    private Composite container;

    public MyPageTwo() {
        super("Second Page");
        setTitle("Second Page");
        setDescription("Now this is the second page");
        setControl(text1);
    }

    @Override
    public void createControl(Composite parent) {
        container = new Composite(parent, SWT.NONE);
        GridLayout layout = new GridLayout();
        container.setLayout(layout);
        layout.numColumns = 2;
        Label label1 = new Label(container, SWT.NONE);
        label1.setText("Say hello to Fred");

        text1 = new Text(container, SWT.BORDER | SWT.SINGLE);
        text1.setText("");
        text1.addKeyListener(new KeyListener() {

            @Override
            public void keyPressed(KeyEvent e) {
                // TODO Auto-generated method stub
            }

            @Override
            public void keyReleased(KeyEvent e) {
                if (!text1.getText().isEmpty()) {
                    setPageComplete(true);
                }
            }

        });
        GridData gd = new GridData(GridData.FILL_HORIZONTAL);
        text1.setLayoutData(gd);
        Label labelCheck = new Label(container, SWT.NONE);
        labelCheck.setText("This is a check");
        Button check = new Button(container, SWT.CHECK);
        check.setSelection(true);
        // required to avoid an error in the system
        setControl(container);
        setPageComplete(false);
    }

    public String getText1() {
        return text1.getText();
    }
}

Create the following class called MyWizard.

package de.vogella.rcp.intro.wizards.wizard;

import org.eclipse.jface.wizard.Wizard;


public class MyWizard extends Wizard {

    protected MyPageOne one;
    protected MyPageTwo two;

    public MyWizard() {
        super();
        setNeedsProgressMonitor(true);
    }

    @Override
    public String getWindowTitle() {
        return "Export My Data";
    }

    @Override
    public void addPages() {
        one = new MyPageOne();
        two = new MyPageTwo();
        addPage(one);
        addPage(two);
    }

    @Override
    public boolean performFinish() {
        // Print the result to the console
        System.out.println(one.getText1());
        System.out.println(two.getText1());

        return true;
    }
}

To show the wizard you could, for example, add a Button to your part and call the Wizard via a SelectionListener on the Button.

Button button = new Button(parent, SWT.PUSH);
button.setText("Open Wizard");
button.addSelectionListener(new SelectionAdapter() {
    @Override
    public void widgetSelected(SelectionEvent e) {
        WizardDialog wizardDialog = new WizardDialog(parent.getShell(),
            new MyWizard());
        if (wizardDialog.open() == Window.OK) {
            System.out.println("Ok pressed");
        } else {
            System.out.println("Cancel pressed");
        }
    }
});

3. Exercise: Adding a wizard to the IDE

Provide a wizard in the New dialog of the Eclipse IDE.

3.1. Using the org.eclipse.ui.newWizards extension point

When a wizard should be provided as new wizard in the New dialog, the org.eclipse.ui.newWizards extension point has to be used.

Add org.eclipse.ui.newWizards extension point

Add a category to this extension point.

Add a wizard entry

This category should be called Vogella.

Add a wizard entry

Add a wizard to this extension point.

Add a wizard entry

When clicking on the class*: hyperlink of the wizard entry, the following dialog will appear. Use the data depicted on the image.

Create a new wizard

The result will look like this:

Extension Point Result

3.2. Implement the INewWizard interface

The MyNewWizard implementation will look similar to this:

package de.vogella.rcp.intro.wizards.wizard;

import org.eclipse.jface.viewers.IStructuredSelection;
import org.eclipse.jface.wizard.Wizard;
import org.eclipse.ui.INewWizard;
import org.eclipse.ui.IWorkbench;

public class MyNewWizard extends Wizard implements INewWizard {

    public MyNewWizard() {
    }

    // ...
    // other MyWizard code
    // ...

    @Override
    public void init(IWorkbench workbench, IStructuredSelection selection) {
        // initialize wizard with workbench and the current selection

    }

    @Override
    public boolean performFinish() {
        return false;
    }

}

3.3. Validate

Optionally the two wizard pages from previous exercises can be added to this new wizard.

Start an Eclipse IDE and open the New dialog by using the File  New  Other…​ menu or simply press CTRL+N and choose the MyNewWizard wizard.

New dialog containing the MyNewWizard

4. Exercise: Eclipse IDE Import Wizard

In this exercise you provide a wizard in the Import dialog of the Eclipse IDE.

4.1. Implement an import wizard

Implementing an import wizard is pretty similar to implementing a new wizard.

The main difference is that the org.eclipse.ui.importWizards extension point and the IImportWizard interface has to be used.

4.2. Validate

Optionally the two wizard pages from previous exercises can be added to this new wizard.

Start an Eclipse IDE and open the Import dialog by using the File  Import…​ menu and choose the MyImportWizard wizard.

Import dialog containing the MyNewWizard

5. Eclipse Wizard Resources

If you need more assistance we offer Online Training and Onsite training as well as consulting