ONJava.com -- The Independent Source for Enterprise Java
oreilly.comSafari Books Online.Conferences.

advertisement

AddThis Social Bookmark Button

Eclipse Plugins Exposed, Part 2: Simple GUI Elements

by Emmanuel Proulx
03/30/2005

The way to write American music is simple. All you have to do is be an American and then write any kind of music you wish. -- Virgil Thompson

In the same vein, the way to write Eclipse plugins is simple too. You have to write an application and "attach" it to Eclipse. But like music, you first have to learn a lot of things before you can write a masterpiece. So let's get started.

In this article we'll discuss a few simple GUI elements:

  • Toolbar button
  • Menu item
  • Dialog

As examples of these, we'll modify slightly our existing plugin, and write a utility class that we'll need down the road.

Extension Points

One can't just add widgets to Eclipse's user interface anywhere. It has to be done at specific, named, documented places. These are called extension points. In a basic Eclipse installation, there are hundreds of extension points available. Plugins themselves can publish new extension points. Let's have a look at the list. Open Invokatron's plugin.xml file and go to the Extensions tab. The items shown in the All Extensions tree list are the different widgets of your plugins, categorized by the extension points in which they appear. For example, the Invokatron Editor is inside an Editor (org.eclipse.ui.editor) extension point. Figure 1 shows the tab in question.

Figure 1
Figure 1. Extensions tab

Now press the Add button. A list (shown in Figure 2) appears.

Figure 2
Figure 2. New extension wizard, list of extensions

Scroll up and down this list to see the many extension points available. You'll notice that there are two kinds of extension points: those with extension templates (identified by the plus-sign icon), and those without. Most of the often-used extension points come with templates to help us developing extensions. The one selected in Figure 2, Action Set, has a template named "Hello World" action set. When you select a template, a short description appears. The next page asks for the parameters to the template.

Related Reading

Eclipse
By Steve Holzner

Now close the wizard and go back to the Extensions tab. Select the Invokatron Editor. You'll remark in this tab the information that we entered in the wizard for the Invokatron Editor, in the last article. Normal extensions need a unique identifier (Id field), a name for display (Name field), and the extension point where it belongs (Point field). Extensions created from templates (like the Invokatron Editor) need more parameters. Extension points without a template need more information, as well, but it must be entered in the text editor.

Adding a Toolbar Button

Now that we know what extension points are, let's add an extension. The first one we're going to add is a toolbar button. This button will invoke the New Invokatron wizard we've created.

There are three steps in adding a toolbar button:

  1. Declare a new extension.
  2. Augment the declaration with specific tags.
  3. Write the action delegate class.

1. Declare a new extension

We already know how to do this. Simply go back to the plugin.xml editor, under the Extensions tab. Click Add. Toolbar buttons fall under the org.eclipse.ui.actionSets extension point. Don't use the template. Click Finish directly. Enter the following for this new action:

  • Id: NewInvokatronAction
  • Name: New Invokatron Document Action
  • Point: (leave as default: org.eclipse.ui.actionSets)

Go to the tab plugin.xml. Eclipse added a new section to this file.

2. Augment the declaration with specific tags

This new extension is a bit naked. Let's add tags under here. How do you know which tags are allowed? You can right-click on elements in the All Extensions tree, and go to the menu New; this will give you a list. Or you can look in the Eclipse documentation under Action Sets.

Here we see that inside of the <extension> tag we can put a single <actionSet> tag. This can contain zero or more <menu> tags, followed by zero or more <action> tags, and an optional <description> tag. But the most important tag is <action>. This can describe both toolbar buttons and menu items. (We'll discuss the <menu> tag later on.)

Below is a snippet of XML code for the toolbar button we're going to add. The new code is in bold type. We will dissect this code right after.


<extension id="NewInvokatronAction"
         name="New Invokatron Document Action"
         point="org.eclipse.ui.actionSets">
  <actionSet id="invokatron.actionSet"
        label="Invokatron Actions"
        visible="true">
    <action id="invokatron.wizard.RunWizardAction"
          toolbarPath="org.eclipse.ui.workbench.file/new.ext"
          icon="icons/InvokatronIcon16.gif"
          tooltip="Starts the New Invokatron Document Wizard."
          class="invokatron.wizard.RunWizardAction">
    </action>
  </actionSet>
</extension>

All of this is also available graphically in the plugin.xml editor, but we're looking at the XML to be able to see the full text of the fields. The <actionSet> tag shown here has only one action. An action is an object that represents an item in a menu or a button in a toolbar. Action attributes are too many to list here, but they are all documented in the online help. The most interesting attributes are:

  • id: Unique identifier for this action. Can be used to refer to an action at runtime.
  • toolbarPath: This is the place to put the toolbar button. See below.
  • icon: Path to a graphic that will appear in the toolbar button or to the left of the menu item. It is a 16-by-16 pixel GIF file that relative to the folder deployment folder. Save this icon Icon to the folder Invokatron\icons. This folder is already included in the binary build, so the icon will end up in the plugin's archive.
  • tooltip: Text that will appear when a mouse hovers the toolbar button.
  • class: The fully qualified name of the class that will implement this action.
About Toolbar Paths

A toolbar path indicates where to add a toolbar button. Since anyone can create toolbars, and sometimes a button can contain sub-items, we refer to this location with a hierarchical list of identifiers. Here's a list of often-used toolbars, with their paths:

  • File: org.eclipse.ui.workbench.file with some public group markers (more places where you can add buttons):
    • "New" zone: new.ext
    • "Save" zone: save.ext
    • "Print" zone: print.ext
    • "Build" zone: build.ext
  • Navigate: org.eclipse.ui.workbench.navigate
  • Launch: org.eclipse.debug.ui.launchActionSet
  • Editor presentation: org.eclipse.ui.edit.text.actionSet.presentation
  • Search: org.eclipse.search.searchActionSet
  • Java element creation: org.eclipse.jdt.ui.JavaElementCreationActionSet
  • Team: Team
  • CVS: CVS

If you provide the toolbar ID without a marker ID, your button will be added in a new toolbar right next to this one. Creating toolbars is as simple as using a new toolbar name. This new toolbar will then be available to add on the Eclipse GUI. You will sometimes see plugins using the toolbar path "Normal." This is the old naming convention. Using this in Eclipse 3 will create a new toolbar named "Normal." If you create a new toolbar ID, your toolbar is added after the File toolbar.

Notice the New group marker of the File toolbar. This is where we'll add our button. Since the marker ID is new.ext, the complete path is:

org.eclipse.ui.workbench.file/new.ext

3. Write the action delegate class

The last step is to write a bit of Java to implement the action. This class is called an action delegate.

package invokatron.wizard;

public class RunWizardAction extends Action 
    implements IWorkbenchWindowActionDelegate {
    /** Called when the action is created. */
    public void init(IWorkbenchWindow window) {
    }

    /** Called when the action is discarded. */
    public void dispose() {
    }

    /** Called when the action is executed. */
    public void run(IAction action) {
        InvokatronWizard wizard= new InvokatronWizard();
        Shell shell =
          PlatformUI.getWorkbench().getActiveWorkbenchWindow().getShell();
        WizardDialog dialog= new WizardDialog(shell, wizard);
        dialog.create();
        dialog.open();
    }

    /** Called when objects in the editor are selected or deselected. */
    public void selectionChanged(IAction action, ISelection selection) {
    }
}

Pages: 1, 2

Next Pagearrow