New menu contribution extension

Background

I started this post to help me and hopefully you understand what is involved in using org.eclipse.ui.menus. I'm assuming you have a good understanding of Eclipse RCP and you would use this as a reference guide. It stems from my fustration in using the Eclipse wiki and finding help with the new features of Eclipse Europa.

The Eclipse Europa (3.3) release has changed the org.eclipse.ui.menus extension to improve menu, toolbar, and popup placement and visibility. The idea is to move away from the old extensions.

• org.eclipse.ui.actionSets
• org.eclipse.ui.editorActions
• org.eclipse.ui.popupMenus
• org.eclipse.ui.viewActions

Where to start

I've listed the extensions with links to appropriate Eclipse help page and wiki page.

Scared yet? It is well worth the effort to learn and thus avoid, as much as possible, the legacy action extensions listed above.

What do you get? A very flexible and powerful way of creating menus, toolbars, and popup menus. I found the legacy action extensions to be difficult to implement complex menu and toolbar interactions and I ended up writing less java code.

org.eclipse.ui.commands

A logical representation of a task. A handler does the work. See wiki and help guide.

org.eclipse.ui.handlers

A handler does what the command represents. See wiki and help guide.

org.eclipse.ui.bindings

Bind a command to a key. See wiki and help guide.

org.eclipse.ui.contexts

Bindings can be organized into a context. See wiki.

org.eclipse.ui.commandImages

Give a command an image.

org.eclipse.ui.editor

See RCP Text Editor Example.

org.eclipse.ui.view

See Creating an Eclipse View.

org.eclipse.ui.menus

Add custom additions to the main menu, main toolbars, and view/editor context menus, toolbars, popup menu, and trim. See wiki and help guide.

Important to understand

Command Core Expressions needs to be understood to make your commands visible and handlers enabled.

Read up on Basic workbench extension points using commands.

How the old maps to the new.

Examples

Example code can be found in org.eclipse.ui.examples.contributions.

Development strategies

Keep notes of the commands you are creating and how they can be reused.

1. Create or reuse a org.eclipse.ui.contexts.
2. Create a command category.
3. Create a command.
4. Create a command image (optional).
5. Create a binding schema.
6. Create a binding for a command.
7. Create a handler.
8. Create a menu contribution.

Debugging and tracing

Check out this wiki page for details on a few debugging strategies.

Common mistakes

• Commands added to a view toolbar must have either a label or icon defined in the menuContribution or icons defined in the org.eclipse.ui.commandImages.
• Forget to look at org.eclipse.ui.menus.MenuUtil for correct spelling of menu constants.