Contributing to toolbars with org.eclipse.ui.menus

I just spent most of the day trying to get a toolbar button to show up using the (relatively) new org.eclipse.ui.menus extension point. As the documentation is misleading, I thought I would take a moment to jot down what I discovered here.

Commands and handlers are a potentially useful abstraction of “behavior the user can invoke”. If we were talking about an object oriented language, the commands would be the message selectors and the handlers would be the methods. The same command (like “save”) can mean different things in different contexts just as the same message can mean different things depending on the receiver.

The purpose of this particular piece of abstraction wasn’t clearly laid out in the Eclipse documentation, but never mind. I got past that. What took all the time was the misleading documentation and examples regarding adding items to toolbars.

The org.eclipse.ui.menus extension point takes a target location, a pointer into either a menu bar or a toolbar where its commands will be inserted. No comprehensive list of possible targets is available that I could find, but again, never mind. I figured out what I needed. Menus work as described:

    <extension point="org.eclipse.ui.menus">
       <menuContribution locationURI="popup:org.eclipse.jdt.ui.PackageExplorer?after=additions">
         <command
           commandId="org.junit.max.ui.command.revertToLastGreen"
           label="Revert to last green">
         </command>
       </menuContribution>
    </extension>

This adds my “Revert to last green” menu item to the package explorer pop up menu. Toolbars are supposed to work the same way, according to the documentation. However, if you change the locationURI to “toolbar:org.eclipse.ui.main.toolbar?after=additions”, Eclipse terminates during startup. By removing the menu contribution from the plugin.xml, starting up the runtime workspace again, and checking the error log, you can see that a class cast exception has been thrown. The CommandContributionItem can’t be cast to a ToolbarContributionItem (this is all with 3.5M5). The examples in the documentation show exactly this configuration, though. The one use of a toolbar in the location (in org.eclipse.pde.ui) is commented out, so Monkey See/Monkey Do doesn’t even work.

The magic incantation solution? Embed the command in a toolbar:

    <extension point="org.eclipse.ui.menus">
       <menuContribution locationURI=""toolbar:org.eclipse.ui.main.toolbar?after=additions">
         <toolbar id="org.junit.max.ui.toolbar">
           <command
             commandId="org.junit.max.ui.command.revertToLastGreen
             label="Revert to last green">
           </command>
         </toolbar>
       </menuContribution>
    </extension>

Now a button appears in the toolbar as expected. Sigh… Another six hours down the drain, hours I could have spent adding functionality to JUnit Max. I’ll take some responsibility for this, but the documentation was lacking as well. At least you don’t have to go through the same search, not if you’ve read this far. Good luck!