org.eclipse.ui.newWizards

You can add a wizard to the File->New menu option in the workbench using the org.eclipse.ui.newWizards extension point. The readme tool example uses this extension point definition to add the Readme File wizard:

<extension
      point = "org.eclipse.ui.newWizards">
	<category
	   id = "org.eclipse.ui.examples.readmetool.new"
	   parentCategory="org.eclipse.ui.Examples"
	   name="%NewWizard.category">
	</category>
 	<wizard
	   id = "org.eclipse.ui.examples.readmetool.wizards.new.file"
      	   name = "%NewWizard.name"
	   class="org.eclipse.ui.examples.readmetool.ReadmeCreationWizard"
	   category="org.eclipse.ui.Examples/org.eclipse.ui.examples.readmetool.new"
	   icon="icons/obj16/newreadme_wiz.gif">
    	   <description>%NewWizard.desc</description>
	   <selection class="org.eclipse.core.resources.IResource"/>
	</wizard>
</extension>

The category describes where the wizard will be grouped when the wizard selection dialog is used to find and launch a wizard. The category name defines the label that is used in the wizard.  The wizard itself is assigned to the category.   Its name, icon, and description all show up in the new wizard selection dialog shown below.

New wizard selection dialog with readme entries

All of this appears based on the markup in the plugin.xml file.  None of the plug-in code runs until the user chooses the Next button.  Once this happens, the workbench will instantiate the wizard class specified in the markup and pass it an expected selection class.

The class identified in this extension (ReadmeCreationWizard) must implement the INewWizard interface.  Most wizards do so by extending the platform Wizard class although this is an implementation mechanism and not required by the extension point.

The wizard itself does little but create the pages inside of it. Let's look at the implementation of the page first, and then come back to the wizard.

Pages

The workbench provides base wizard page classes that support the type of processing performed for each wizard extension point. You can use these pages, or extend them to add additional processing.

The goal of the ReadmeCreationWizard is to create a new file, add the required content to the file, and as an option, open an editor on the file. Our page needs to define the controls that let the user specify what content goes in the file and whether an editor should be launched.

We create the wizard page, ReadmeCreationPage, by extending WizardNewFileCreationPage. The controls for a wizard page are defined in a fashion similar to the definition of the controls for a view or an editor. The page implements a createControl method, creating the necessary SWT widgets as children of the supplied Composite. Since the superclass already adds widgets that support new file processing, we need only extend the createControl method in our wizard page to add the additional checkboxes that control generation of sections and opening of the editor.

   public void createControl(Composite parent) {
      // inherit default container and name specification widgets
      super.createControl(parent);
      Composite composite = (Composite)getControl();
      ...
      // sample section generation group
      Group group = new Group(composite,SWT.NONE);
      group.setLayout(new GridLayout());
      group.setText(MessageUtil.getString("Automatic_sample_section_generation"));
      group.setLayoutData(new GridData(GridData.GRAB_HORIZONTAL |
         GridData.HORIZONTAL_ALIGN_FILL));
      ...
      // sample section generation checkboxes
      sectionCheckbox = new Button(group,SWT.CHECK);
      sectionCheckbox.setText(MessageUtil.getString("Generate_sample_section_titles"));
      sectionCheckbox.setSelection(true);
      sectionCheckbox.addListener(SWT.Selection,this);

      subsectionCheckbox = new Button(group,SWT.CHECK);
      subsectionCheckbox.setText(MessageUtil.getString("Generate_sample_subsection_titles"));
      subsectionCheckbox.setSelection(true);
      subsectionCheckbox.addListener(SWT.Selection,this);
      ...
      // open file for editing checkbox
      openFileCheckbox = new Button(composite,SWT.CHECK);
      openFileCheckbox.setText(MessageUtil.getString("Open_file_for_editing_when_done"));
      openFileCheckbox.setSelection(true);
      ...
   }

You should be able to follow this code if you understand the concepts in Standard Widget Toolkit.

The basic patterns for implementing a page include:

The ReadmeCreationPage class inherits a lot of this behavior from the WizardNewFileCreationPage.  Browse the implementation of these classes for further information.

Now that we understand what a page does, let's look again at the wizard.

Wizard

The wizard is responsible for creating the pages and providing the "finish" logic.

The basic patterns for implementing a wizard include:

The completed wizard looks like this:

Readme file creation wizard page

    

Copyright IBM Corp. and others 2000,2002.