Back to top

vogella training Training Books

Creating Eclipse Wizards - Tutorial

Lars Vogel

Version 2.3

07.10.2012

Revision History
Revision 0.1 07.08.2009 Lars
Vogel
created
Revision 0.2 - 2.3 25.09.2009 - 07.10.2012 Lars
Vogel
bug fixes and updates

Eclipse Wizards

This article describes how to create and use Eclipse Wizards. It is based on Eclipse 4.2 (Eclipse Juno) but covers also the Eclipse 3.x releases.


Table of Contents

1. Eclipse Wizards
1.1. Overview
1.2. Wizards and WizardPages
1.3. Starting the Wizard
1.4. Changing the page order
1.5. Working with the same data on different pages
1.6. Updating the Wizard buttons from the Page
2. Adding your wizard to the New, Import and Export commands
3. Prerequisites for this tutorial
4. Tutorial: Wizards Example
5. Thank you
6. Questions and Discussion
7. Links and Literature
7.1. Source Code
7.2. Eclipse Wizard Resources
7.3. vogella Resources

1. Eclipse Wizards

1.1. Overview

Wizards allow to capture user feedback in a structured way. A wizard guides a user step by step through different pages.

The following screenshot shows the second page of a Wizard.

Example wizard

1.2. Wizards and WizardPages

The Wizard class from the org.eclipse.jface.wizard package provides the functionality to build own wizards. This class controls the navigation between the different pages and provides the base user interface, i.e. a progress bar and 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 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 SWT Button.

1.4. Changing the page order

Frequently you want to jump to a specific page depending on the user input.

A WizardPage can override the getNextPage() method for this purpose.

If you do this, you would typically access the correct page via the Wizard. You get the Wizard via the getWizard() method. Afterwards you can access via the Wizard the page which should be the next one.

1.5. Working with the same data on different pages

To use the same data in different pages in your wizard, add the required objects to the constructor of your wizard page. 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 the Page

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 would include 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 4 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.NULL);
    GridLayout layout = new GridLayout();
    container.setLayout(layout);
    layout.numColumns = 2;
    Label label1 = new Label(container, SWT.NULL);
    label1.setText("Put here a value");

    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.NULL);
    GridLayout layout = new GridLayout();
    container.setLayout(layout);
    layout.numColumns = 2;
    Label label1 = new Label(container, SWT.NULL);
    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 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. Thank you

Please help me to support this article:

Flattr this

6. Questions and Discussion

Before posting questions, please see the vogella FAQ. If you have questions or find an error in this article please use the www.vogella.com Google Group. I have created a short list how to create good questions which might also help you.

7. Links and Literature

7.1. Source Code

Source Code of Examples

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 and compile to JavaScript and HTML

Eclipse RCP Tutorial Create native applications in Java

JUnit Tutorial Test your application

Git Tutorial Put everything you have under distributed version control system