Support free tutorials:











vogella training Training Books



Creating Eclipse Wizards - Tutorial

Lars Vogel

Version 2.4

17.07.2013

Revision History
Revision 0.1 07.08.2009 Lars
Vogel
created
Revision 0.2 - 2.4 25.09.2009 - 17.07.2013 Lars
Vogel
bug fixes and updates

Eclipse Wizards

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


Table of Contents

1. Eclipse Wizards
1.1. Usage of 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. Support this website
6.1. Thank you
6.2. Questions and Discussion
7. Links and Literature
7.1. Source Code
7.2. Eclipse Wizard Resources
7.3. vogella Resources

Get the book Eclipse RCP book

1. Eclipse Wizards

1.1. Usage of wizards

Wizards allow you to capture user input in a structured way. A wizard guides a user step-by-step through different pages to fulfill a specific task.

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 the 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 TodoWizardPage2(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 in your wizard, add the required objects to the constructor of your wizard page and pass it to the wizard pages.

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 what 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. Support this website

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.

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.

6.1. Thank you

Please consider a contribution if this article helped you.

Flattr this

6.2. Questions and Discussion

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.

7. Links and Literature

7.1. Source Code

Source Code of Examples

7.2. Eclipse Wizard Resources

Creating JFace Wizards

7.3. vogella Resources

vogella Training Android and Eclipse Training from the vogella team

Android Tutorial Introduction to Android Programming

GWT Tutorial Program in Java, compile to JavaScript and HTML

Eclipse RCP Tutorial Create native applications in Java

JUnit Tutorial Test your application

Git Tutorial Put all your files in a distributed version control system