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
Pages: 1, 2

Adding a Menu Item

As you may have guessed adding a menu item is almost the same as adding a toolbar button. You also have to declare an extension (the same kind), augment the declaration with specific tags (the same tags), and write an action class (the same class). The main difference is with the declaration of the extension. Here's how extension XML code looks like for a menu item without a corresponding toolbar button:




<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"
          label="New Invokatron"
          menubarPath="file/new.ext"
          icon="icons/InvokatronIcon16.gif"
          tooltip="Starts the New Invokatron Document Wizard."
          class="invokatron.wizard.RunWizardAction">
    </action>
  </actionSet>
</extension>

The label attribute contains the text that will be displayed in the menu item. Keyboard shortcuts are represented by "&" which is written &amp; in XML. And now for an example of a combined menu item and toolbar button:


<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"
          label="New Invokatron"
          menubarPath="file/new.ext"
          toolbarPath="org.eclipse.ui.workbench.file/new.ext"
          icon="icons/invokatronPicture.gif"
          tooltip="Starts the New Invokatron Document Wizard."
          class="invokatron.wizard.RunWizardAction">
    </action>
  </actionSet>
</extension>

Menus are a little bit different than toolbars. There's only one "level" of toolbars but there's a whole hierarchy of menus. This is why it is possible to declare menus along with actions. Menus are listed inside of the <actionSet> tag, above <action> tags. They have the following syntax:


    <menu id="unique.ID"
          <!-- New menu at the top-level. The menubarPath
              for actions inside this menu is: Special -->
          path="Special" 
          label="This is a parent menu item.">
      <!-- Optional, the menubarPath for actions after
         this separator is: Special/BelowBar -->
      <separator name="BelowBar"> 
    </menu>
About Menubar Paths

A menubar path indicates where to add a menu item. We refer to this location with a hierarchical list of identifiers. Here's a list of often-used menubars, with their paths, and public group markers (when available):

  • File: file
    • "Start" zone: fileStart
    • Inside the New menu, the "additions" group marker: new/additions
    • "New" zone, below the New menu: new.ext
    • "Close" zone: close.ext
    • "Save" zone: save.ext
    • "Print" zone: print.ext
    • "Open" zone: open.ext
    • "Import" zone: import.ext
    • "Additions" zone: additions
    • "Recent documents" zone: mru
    • "End" zone: fileEnd
  • Edit: edit
    • "Start" zone: editStart
    • "Undo" zone: undo.ext
    • "Cut" zone: cut.ext
    • "Find" zone: find.ext
    • "Add" zone: add.ext
    • "End" zone (which is not at the end, for some reason): fileEnd
    • "Additions" zone: additions
  • Source: org.eclipse.jdt.ui.source.menu
  • Refactor: org.eclipse.jdt.ui.refactoring.menu
  • Navigate: navigate
    • "Start" zone: navStart
    • Inside of the Go To menu, "additions" group marker: goTo/additions
    • "Open" zones (four of them): open.ext, open.ext2, open.ext3, and open.ext4
    • "Show" zones (four of them): show.ext, show.ext2, show.ext3, and show.ext4
    • "Additions" zone: additions
    • "End" zone: navEnd
  • Search: org.eclipse.search.menu
  • Project: project
    • "Start" zone: projStart
    • "Open" zone: open.ext
    • "Build" zone: build.ext
    • "Additions" zone: additions
    • "End" zone: projEnd
  • Launch: launch
  • Run: org.eclipse.ui.run
  • "Additions" group marker: additions
  • Window: window
    • "Additions" zone: additions
    • "End" zone: additionsend
  • Help: help
    • "Start" zone: helpStart
    • "Main group" zone: group.main.ext
    • "Tutorials group" zone: group.tutorials
    • "Tools group" zone: group.tools
    • "Updates group" zone: group.updates
    • "End" zone (which is not at the end, for some reason): helpEnd
    • "Additions" zone: additions
    • "About group" zone: group.about.ext

If you provide the menubar ID without a marker ID, your menu item will appear right next to this menubar. If you create a new menubar ID, your menubar is added between the Project and Run menus.

Message to Eclipse developers: Please use more consistency for toolbar and menubar IDs, and marker locations.

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

file/new.ext

The Result

Many other features are available in Action Sets, including shortcut keys, state buttons, hovering icons, help context, window toolbars, etc. And Action Sets is just a single kind of extension point among the dozens that are documented. So what we saw is just the tip of the iceberg. But at least it gives you a good idea of how extension points works. The 1. 2. 3. procedure we saw is always good.

Before we move on to wizard customizations, Figure 3 shows what the new toolbar button and menu item look like:

Figure 3
Figure 3. New menu item and toolbar button

Standard Dialogs

Eclipse comes with a full range of standard dialogs and an easy way to create custom dialogs. Many standard dialogs are provided by the class org.eclipse.jface.dialogs.MessageDialog. This has many static methods to create standard dialogs. The following lists some of the standard dialogs available.

Type of dialog Creation method Equivalent in Swing
Confirmation (Message, question mark icon, OK, and Cancel buttons) MessageDialog.openConfirm( Shell parent, String title, String message) Returns true if the user has clicked OK, false otherwise. JOptionPane.showConfirmDialog(...) passing the optionType JOptionPane.OK_CANCEL_OPTION
Error (Message, error icon, OK button) MessageDialog.openError( Shell parent, String title, String message) JOptionPane.showMessageDialog(...) passing the messageType JOptionPane.ERROR_MESSAGE
Informational (Message, information icon, OK button) MessageDialog.openInformation( Shell parent, String title, String message) JOptionPane.showMessageDialog(...) passing the messageType JOptionPane.INFORMATION_MESSAGE
Yes/No question (Message, question mark icon, Yes and No buttons) MessageDialog.openQuestion( Shell parent, String title, String question) Returns true if the user has clicked Yes, false otherwise. JOptionPane.showConfirmDialog(...) passing the optionType JOptionPane.YES_NO_OPTION
Warning (Message, warning icon, OK buttons) MessageDialog.openWarning( Shell parent, String title, String message) JOptionPane.showMessageDialog(...) passing the messageType JOptionPane.WARNING_MESSAGE

One may think that the JOptionPane class offers more flexibility than MessageDialog when it comes to standard dialogs. But ultimately, with MessageDialog's constructor and custom dialogs you can do almost anything. The only feature missing in MessageDialog, which JOptionPane has, is direct message formatting in HTML. This can be worked around with customized dialogs.

Dialog Helper Class

Now that we know our options, let's create the dialogs that we need for Invokatron. There are two areas that necessitate dialogs:

  • The confirmation of generation of code, overwriting previous code.
  • A dialog asking for the entry of a value (similar to JOptionPane.showInputDialog()).

Let's create a new utility class that will host these dialogs. Create the folder Invokatron/src/invokatron/helper and make a new class named DialogHelper.

The first method in this class is for the confirmation of code overwriting. Here it is:


public static boolean openOverwriteDialog(Shell parent) {
    return MessageDialog.openConfirm(parent,
        "Confirmation",
        "You are about to overwrite your class. " +
        "Are you sure you want to continue?");
}

This is very simple, we just create a regular confirmation dialog. The input dialog is another matter: MessageDialog doesn't have an input field. We could just create a new dialog class, maybe a subclass of Dialog. We could also subclass MessageDialog and override its createCustomArea() method to add the input field. But there's a simpler way.

We'll use the InputDialog class!


public static String openInputDialog(
      Shell parent,
      String title,
      String question,
      String initialValue) {

    InputDialog dlg = new InputDialog(
            parent,
            title,
            question,
            initialValue,
            null); //This is an optional validation class
    dlg.open();

    if(dlg.getReturnCode()!=Window.OK) //Didn't click on OK!
        return null;

    return dlg.getValue();
}

Our dialog helper class is done. You can look at the dialogs in Figure 4. We will make use of it in the next issues of the series.

Figure 4
Figure 4. Dialogs

The Eclipse Symphony

Eclipse is like music; once you learn how to use some of the available instruments, you can write yourself a symphony. Today we've briefly seen two categories of instruments: extension points and dialogs. In the next article, we'll talk about how to enter and save the state of our editor.

Resources

Emmanuel Proulx is an expert in J2EE and Enterprise JavaBeans, and is a certified WebLogic Server 7.0 engineer. He works in the fields of telecommunications and web development.


Return to ONJava.com.