Support free tutorials



vogella training Training Books

Creating Eclipse Wizards - Tutorial

Lars Vogel

Version 2.4

17.07.2013

Eclipse Wizards

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.


Table of Contents

1. Eclipse Wizards
1.1. What is a wizards
1.2. Wizards and WizardPages
1.3. Starting the Wizard
1.4. Changing the page order
1.5. Working with data in the wizard
1.6. Updating the Wizard buttons from a WizardPage
2. Adding your wizard to the New, Import and Export commands
3. Prerequisites for this tutorial
4. Tutorial: Wizards Example
5. Learn more about Eclipse 4 RCP development
6. About this website
6.1. Donate to support free tutorials
6.2. Questions and discussion
6.3. License for this tutorial and its code
7. Links and Literature
7.1. Source Code
7.2. Eclipse Wizard Resources
7.3. vogella GmbH training and consulting support

Get the book Eclipse RCP book

1. Eclipse Wizards

1.1. What is a wizards

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

Tip

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, you 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.

// todo is an object available in the wizard

private TodoWizardPage1 page1 = new TodoWizardPage1(todo);
private TodoWizardPage2 page2 = new TodoWizardPage2();
private TodoWizardPage3 specialPage = new TodoWizardPage3(todo);

@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.

2. 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.

3. Prerequisites for this tutorial

This tutorial assumes that you have basic understanding of development for the Eclipse platform. Please see Eclipse RCP Tutorial or Eclipse Plug-in Tutorial if you need any basic information.

4. Tutorial: 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");
      }
  }
}); 

5. Learn more about Eclipse 4 RCP development

I hope you enjoyed this tutorial. You find this tutorial and much more information also in the Eclipse 4 RCP book from this author.

6. About this website

6.1. Donate to support free tutorials

Please consider a contribution Support free tutorials if this article helped you. It will help to maintain our content and our Open Source activities.

6.2. Questions and discussion

Writing and updating these tutorials is a lot of work. If this free community service was helpful, you can support the cause by giving a tip as well as reporting typos and factual errors.

If you find errors in this tutorial, please notify me (see the top of the page). Please note that due to the high volume of feedback I receive, I cannot answer questions to your implementation. Ensure you have read the vogella FAQ as I don't respond to questions already answered there.

6.3. License for this tutorial and its code

This tutorial is Open Content under the CC BY-NC-SA 3.0 DE license. Source code in this tutorial is distributed under the Eclipse Public License. See the vogella License page for details on the terms of reuse.

7. Links and Literature

7.1. Source Code

Source Code of Examples

7.2. Eclipse Wizard Resources

Creating JFace Wizards

7.3. vogella GmbH training and consulting support

TRAINING SERVICE & SUPPORT
The vogella company provides comprehensive training and education services from experts in the areas of Eclipse RCP, Android, Git, Java, Gradle and Spring. We offer both public and inhouse training. Whichever course you decide to take, you are guaranteed to experience what many before you refer to as “The best IT class I have ever attended”. The vogella company offers expert consulting services, development support and coaching. Our customers range from Fortune 100 corporations to individual developers.