Mastering Eclipse Plug-in Development

Create a new class called com.packtpub.e4.advanced.feeds.ui.NewFeedWizard that extends org.eclipse.jface.wizard.Wizard. This creates a skeleton file with a performFinish method.

To add content, one or more pages must be created. A page is a subclass of WizardPage or another class that implements the IWizardPage interface. Pages are typically added within the constructor or addPages methods of the owning wizard.

Create a new class called com.packtpub.e4.advanced.feeds.ui.NewFeedPage that extends org.eclipse.jface.wizard.WizardPage. The default implementation will be missing a constructor; create a default constructor that passes the string "NewFeedPage" to the superclass' constructor.

The code should now look like the following code snippet:

package com.packtpub.e4.advanced.feeds.ui;
import org.eclipse.jface.wizard.Wizard;
public class NewFeedWizard extends Wizard {
  public boolean performFinish() {
    return false;
  }
}
package com.packtpub.e4.advanced.feeds.ui;
import org.eclipse.jface.wizard.WizardPage;
import org.eclipse.swt.widgets.Composite;
public class NewFeedPage extends WizardPage {
  protected NewFeedPage() {
    super("NewFeedPage");
  }
  public void createControl(Composite parent) {
  }
}

The wizard has an addPages method that is called when it is about to be shown. This allows one or more pages to be added to allow the wizard to do work. For simple wizards, a single page is often enough; but for complex wizards, it may make sense to break it down into two or more individual pages. A multipage wizard typically steps through its pages in order, but more complex transitions can be achieved if necessary.

Create a new instance of NewFeedPage and assign it to an instance variable called newFeedPage. Create an addPages method that calls addPage with newFeedPage as an argument, as shown in the following code:

private NewFeedPage newFeedPage = new NewFeedPage();
public void addPages() {
  addPage(newFeedPage);
}

Each page has an associated content area, which is populated through the createControl method on the page class. This is given a Composite object to add widgets; a typical wizard page starts off with exactly the same stanza as other container methods by creating a new Composite, setting it as the control on the page and making it incomplete. The code is as follows:

public void createControl(Composite parent) {
  Composite page = new Composite(parent,SWT.NONE);
  setControl(page);
  setPageComplete(false);
}

Pages are typically set up as data gathering devices, and the logic is delegated to the wizard to decide what action to take. In this case, a feed has a simple URL and a title, so the page will store these as two instance variables and set up UI widgets to save the content.

One of the easiest ways to get data out of the page is to persist references to the SWT Text boxes that are used to input content and then provide accessors to access the data. To guard against failure, accessor methods need to test for null and check that the widget hasn't been disposed. The code is as follows:

private Text descriptionText;
private Text urlText;
public String getDescription() {
  return getTextFrom(descriptionText);
}
private String getTextFrom(Text text) {
  return text==null || text.isDisposed() ? null : text.getText();
}
public String getURL() {
  return getTextFrom(urlText);
}

This allows the parent wizard to access the data entered by the user once the page is complete. The process of getting the data is typically performed within the performFinish method, where the resulting operation can be displayed.

The page's user interface is built in the createControl method. This is typically organized with a GridLayout, although this isn't a requirement. The user interface for wizards tend to offer a grid of Label and Text widgets, so it could look like the following code snippet:

  page.setLayout(new GridLayout(2, false));
  page.setLayoutData(new GridData(GridData.FILL_BOTH));
  Label urlLabel = new Label(page, SWT.NONE);
  urlLabel.setText("Feed URL:");
  urlText = new Text(page, SWT.BORDER);
  urlText.setLayoutData(new GridData(GridData.FILL_HORIZONTAL));
  Label descriptionLabel = new Label(page, SWT.NONE);
  descriptionLabel.setText("Feed description:");
  descriptionText = new Text(page, SWT.BORDER);
  descriptionText.setLayoutData(
    new GridData(GridData.FILL_HORIZONTAL));

The Finish button on the wizard is enabled when the page is marked as complete. Each wizard knows what information is required to finish; when it is finished, it should call setPageComplete(true). This can be arranged in the NewFeedPage class by listening to text entry changes on the feed description and URL and setting the page to be complete when both have non-empty values:

private class CompleteListener implements KeyListener {
  public void keyPressed(KeyEvent e) {
  }
  public void keyReleased(KeyEvent e) {
    boolean hasDescription =
     !"".equals(getTextFrom(descriptionText));
    boolean hasUrl = !"".equals(getTextFrom(urlText));
    setPageComplete(hasDescription && hasUrl);
  }
}
public void createControl(Composite parent) {
  …
  CompleteListener listener = new CompleteListener();
  urlText.addKeyListener(listener);
  descriptionText.addKeyListener(listener);
}

Now, whenever a key is pressed and there is text present in both the description and URL fields, the Finish button will be enabled; if text is removed from either field, it will be disabled.

To test whether the wizard works as expected before it is integrated into an Eclipse application, a small standalone test script can be created. Although bad practice, it is possible to add a main method to NewFeedWizard to allow it to display the wizard in a standalone fashion.

Wizards are displayed with the JFace WizardDialog. This takes a Shell and the Wizard instance; so a simple test can be run using the following snippet of code:

public static void main(String[] args) {
  Display display = new Display();
  Shell shell = new Shell(display);
  new WizardDialog(shell, new NewFeedWizard()).open();
  display.dispose();
}

Now, if the wizard is run, a standalone shell will be displayed and the fields and checks can be tested for correct behavior. A more complex set of tests can be set up with a UI test framework such as SWTBot.

If the wizard is shown as is, the title area will be empty. Typically, a user will need to know what information to put in and what is required in order to complete the dialog. Each page can contribute information specific to that step. In the case of a multipage wizard where there are several distinct stages, each page can contribute its own information.

In the case of the new feed page, the title and message can be informational. The constructor is a good place to set the initial title and message. The code to perform this operation is as follows:

protected NewFeedPage() {
  super("NewFeedPage");
  setTitle("Add New Feed");
  setMessage("Please enter a URL and description for a news feed");
}

When feed information is entered, the message can be replaced to indicate that a description or URL is required. To clear the message, invoke setMessage(null). To add an error message, invoke setMessage and pass in one of the constants from IMessageProvider, as shown:

public void keyReleased(KeyEvent e) {
  boolean hasDescription
   = !"".equals(getTextFrom(descriptionText));
  boolean hasUrl = !"".equals(getTextFrom(urlText))
  if (!hasDescription) {
    setMessage("Please enter a description"
      IMessageProvider.ERROR);
  }
  if (!hasUrl) {
    setMessage("Please enter a URL", IMessageProvider.ERROR);
  }
  if (hasDescription && hasUrl) {
    setMessage(null);
  }
  setPageComplete(hasDescription && hasUrl);
}

To display an image on the wizard as a whole, the page can have an image of size 75 x 58 pixels. This can be set from an image descriptor in the constructor:

setImageDescriptor(
 ImageDescriptor.createFromFile(
  NewFeedPage.class, "/icons/full/wizban/newfeed_wiz.png"));

Now, running the wizard will display an icon at the top-right corner (if it doesn't, check that build.properties includes the icons/ directory in the bin.includes property):

Use this to add a feed file of http://www.packtpub.com/rss.xml with a description of Packt Publishing special offers.

To add help, the wizard needs to declare that help is available. During the construction of the wizard or in the addPages method, a call to the parent's setHelpAvailable method with a true parameter has to be invoked.

Help is delegated to each page by calling a performHelp method. This allows context-sensitive help to be delivered for the specific page displayed, and it also helps to get the state of the page or its previous page states. The code is as follows:

// Add to the NewFeedWizard class
public void addPages() {
  addPage(new NewFeedPage());
  setHelpAvailable(true);
}
// Add to the NewFeedPage class
public void performHelp() {
  MessageDialog.openInformation(getShell(),
    "Help for Add New Feed",
    "You can add your feeds into this as an RSS or Atom feed, "
  + "and optionally specify an additional description "
  + "which will be used as the feed title.");
}

Executing the preceding code will show a Help button on the bottom of the dialog; when clicked, it will show a help dialog with some text as shown in the following screenshot:

When the user clicks on the Finish button on the wizard, the corresponding performFinish method is called. This allows the wizard to acquire data from the underlying pages and perform whatever action is required.

In this case, a Properties file called news.feeds can be created underneath a project called bookmarks in the workspace. This will require that org.eclipse.core.resources is added to the plug-in's dependencies.

First, acquire or create a project called bookmarks and then acquire or create a file called news.feeds. The underlying content will be stored in the Properties file as a list of key=value pairs, where key is the URL and value is the description.

To simplify access to ResourcesPlugin, create a helper method in NewFeedWizard that will obtain an IFile from a project as follows:

private IFile getFile(String project, String name,
 IProgressMonitor monitor) throws CoreException {
  IWorkspace workspace = ResourcesPlugin.getWorkspace();
  IProject bookmarks = workspace.getRoot().getProject(project);
  if (!bookmarks.exists()) {
    bookmarks.create(monitor);
  }
  if (!bookmarks.isOpen()) {
    bookmarks.open(monitor);
  }
  return bookmarks.getFile(name);
}

To access the feeds from the resources, create two public static final variables that define the name of the project and the name of the bookmarks file:

public static final String FEEDS_FILE = "news.feeds";
public static final String FEEDS_PROJECT = "bookmarks";

These can be used to create a helper method to add a single feed on the resource by reading the contents of the file (creating it if it doesn't exist), adding the feed, and then saving the new contents of the file:

private synchronized void addFeed(String url, String description)
 throws CoreException, IOException {
  Properties feeds = new Properties();
  IFile file = getFile(FEEDS_PROJECT, FEEDS_FILE, null);
  if (file.exists()) {
    feeds.load(file.getContents());
  }
  feeds.setProperty(url, description);
  ByteArrayOutputStream baos = new ByteArrayOutputStream();
  feeds.store(baos, null);
  ByteArrayInputStream bais =
   new ByteArrayInputStream(baos.toByteArray());
  if (file.exists()) {
    file.setContents(bais, true, false, null);
  } else {
    file.create(bais, true, null);
  }
}

Finally, to hook this method in with the performFinish method being called, pull the description and url fields from NewFeedPage and then pass them to the addFeed method. Since an exception may be raised, surround them with a try/catch block that returns true or false (as appropriate):

public boolean performFinish() {
  String url = newFeedPage.getURL();
  String description = newFeedPage.getDescription();
  try {
    if (url != null && description != null) {
      addFeed(url, description);
    }
    return true;
  } catch (Exception e) {
    newFeedPage.setMessage(e.toString(), IMessageProvider.ERROR);
    return false;
  }
}

Running the wizard from the test harness won't have an effect, since the workspace won't be open. It is thus necessary to contribute this to the new wizard's mechanism in Eclipse, which is done in the next section.

To integrate the wizard into Eclipse, it should be added to the newWizards extension point provided by the org.eclipse.ui plug-in.

There is a minor modification required in the wizard to make it fit in with the new wizard extension point: implementing the INewWizard interface. This adds an additional method, init, that provides the current selection at the time of calling. This allows the wizard to detect whether (for example) a string URL is selected and, if so, fills the dialog with that information. The modification is shown in the following code snippet:

public class NewFeedWizard extends Wizard implements INewWizard {
  public void init(IWorkbench workbench,
   IStructuredSelection selection) {
  }
  …
}

Add the following extension, along with a 16 x 16 icon, to the plugin.xml file:

<plugin>
  <extension point="org.eclipse.ui.newWizards">
    <category name="Feeds"
      id="com.packtpub.e4.advanced.feeds.ui.category"/>
    <wizard name="New Feed"
      class="com.packtpub.e4.advanced.feeds.ui.NewFeedWizard"
      category="com.packtpub.e4.advanced.feeds.ui.category"
      icon="icons/full/etool16/newfeed_wiz.gif"
      id="com.packtpub.e4.advanced.feeds.ui.newFeedWizard"/>
  </extension>
</plugin>

Now, the Eclipse application can be run and a Feeds category will be added to the New dialog situated under File.

The wizard container can have a progress bar for long-running operations and can be used to display the progress, including optional cancellation, if the job requires it.

To acquire a progress monitor, the wizard's container can be used to invoke RunnableWithProgress, which is an interface that has a run method with an IProgressMonitor argument. The addFeed method can be moved into an anonymous inner class, which allows the wizard to display the progress of the operation without blocking the UI. The code is as follows:

public boolean performFinish() {
  final String url = newFeedPage.getURL();
  final String description = newFeedPage.getDescription();
  try {
    boolean fork = false;
    boolean cancel = true;
    getContainer().run(fork, cancel, new IRunnableWithProgress() {
      public void run(IProgressMonitor monitor) 
       throws InvocationTargetException, InterruptedException {
        try {
          if (url != null && description != null) {
            addFeed(url, description, monitor);
          }
        } catch (Exception e) {
          throw new InvocationTargetException(e);
        }
      }
    });
    return true;
  } catch (InvocationTargetException e) {
    newFeedPage.setMessage(e.getTargetException().toString(),
     IMessageProvider.ERROR);
    return false;
  } catch (InterruptedException e) {
    return true;
  }
}

The fork argument passed to the run method indicates whether the job should run in the path of the performFinish method or if it should run in a new thread. If a new thread is chosen, the run method will return hiding any errors that may be generated from the result of the addFeed call. The cancel argument provides an option to cancel the job if run in the same thread.

The addFeed method can be modified (as shown in the following code snippet) to interact with the progress monitor after converting it to a SubMonitor and passing it to the child tasks as appropriate. Regularly checking whether the monitor is cancelled will give the user the best experience if they decide to cancel the job.

private synchronized void addFeed(String url, String description,
 IProgressMonitor monitor) throws CoreException, IOException {
  SubMonitor subMonitor = SubMonitor.convert(monitor, 2);
  if(subMonitor.isCanceled())
    return;
  Properties feeds = new Properties();
  IFile file = getFile(FEEDS_PROJECT, FEEDS_FILE, subMonitor);
  subMonitor.worked(1);
  if (file.exists()) {
    feeds.load(file.getContents());
  }
  if(subMonitor.isCanceled())
    return;
  feeds.setProperty(url, description);
  ByteArrayOutputStream baos = new ByteArrayOutputStream();
  feeds.save(baos, null);
  ByteArrayInputStream bais = 
   new ByteArrayInputStream(baos.toByteArray());
  if(subMonitor.isCanceled())
    return;
  if (file.exists()) {
    file.setContents(bais, true, false, subMonitor);
  } else {
    file.create(bais, true, subMonitor);
  }
  subMonitor.worked(1);
  if (monitor != null) {
    monitor.done();
  }
}

If the wizard is shown now, the cancellation button and progress bars are not shown. In order to ensure that the wizard shows them, the addPages method must also declare that the progress monitor is required, as shown in the following code snippet:

public void addPages() {
  addPage(newFeedPage);
  setHelpAvailable(true);
  setNeedsProgressMonitor(true);
}

To open an editor and set the selection correctly, it will be necessary to include two more bundles to the project: org.eclipse.jface.text (for the TextSelection class) and org.eclipse.ui.ide (for the IDE class). This will tie the bundle into explicit availability of the IDE, but it can be marked as optional (because if there is no IDE, then there are no editors). It may also require org.eclipse.ui.navigator to be added to include referenced class files.

To implement the activateEditor method, it is necessary to find where the entry is inside the properties file and then set the selection appropriately. Since there is no easy way to do this, the contents of the file will be read instead (with a BufferedInputStream instance) while searching for the bytes that make up the selected item. Because there is a hardcoded name of bookmarks and a feed of news.feeds, this can be used to acquire the file content; though for real applications, the Feed object should know its parent and be able to provide that dynamically. The following code snippet shows how to set the selection appropriately:

public class FeedLinkHelper implements ILinkHelper {
  public void activateEditor(IWorkbenchPage page,
   IStructuredSelection selection) {
    Object object = selection.getFirstElement();
    if (object instanceof Feed) {
      Feed feed = ((Feed) object);
      byte[] line = (feed.getUrl().replace(":", "\\:") + "="
       + feed.getName()).getBytes();
      IProject bookmarks = ResourcesPlugin.getWorkspace()
       .getRoot().getProject(NewFeedWizard.FEEDS_PROJECT);
      if (bookmarks.exists() && bookmarks.isOpen()) {
        IFile feeds = bookmarks.getFile(NewFeedWizard.FEEDS_FILE); 
        if (feeds.exists()) {
          try {
            TextSelection textSelection = findContent(line,feeds);
            if (textSelection != null) {
              setSelection(page, feeds, textSelection);
            }
          } catch (Exception e) {
            // Ignore
          }
        }
      }
    }
  }
  … 
}

To find the content of the line, it is necessary to get the contents of the file and then perform a pass-through looking for the sequence of bytes. If the bytes are found, the start point is recorded and is used to return a TextSelection. If they are not found, then return a null, which indicates that the value shouldn't be set. This is illustrated in the following code snippet:

private TextSelection findContent(byte[] content, IFile file)
 throws CoreException, IOException {
  int len = content.length;
  int start = -1;
  InputStream in = new BufferedInputStream(file.getContents());
  int pos = 0;
  while (start == -1) {
    int b = in.read();
    if (b == -1)
      break;
    if (b == content[0]) {
      in.mark(len);
      boolean found = true;
      for (int i = 1; i < content.length && found; i++) {
        found &= in.read() == content[i];
      }
      if (found) {
        start = pos;
      }
      in.reset();
    }
    pos++;
  }
  if (start != -1) {
    return new TextSelection(start, len);
  } else {
    return null;
  }
}

This takes advantage of the fact that BufferedInputStream will perform the mark operation on the underlying content stream and allow backtracking to occur. Because this is only triggered when the first character of the input is seen, it is not too inefficient. To further optimize it, the content could be checked for the start of a new line.

Once the appropriate selection has been identified, it can be opened in an editor through the IDE class. This provides an openEditor method that can be used to open an editor at a particular point, from which the selection service can be used to set the text selection on the file. The code is as follows:

private void setSelection(IWorkbenchPage page, IFile feeds,
 TextSelection textSelection) throws PartInitException {
  IEditorPart editor = IDE.openEditor(page, feeds, false);
  editor.getEditorSite()
   .getSelectionProvider().setSelection(textSelection);
}

Now when the element is selected in the project navigator, the corresponding news.feeds resource will be opened as long as Link editor with selection is enabled.

The corresponding direction, linking the editor with the selection in the viewer, is much less practical. The problem is that the generic text editor won't fire the method until the document is opened, and then there are limited ways in which the cursor position can be detected from the document. More complex editors, such as the Java editor, provide a means to model the document and understand where the cursor is in relation to the methods and fields. This information is used to update the outline and other views.