Allow contributions to Forms

Introduction

Each Form has a toolbar associated with it, as you probably already know. You can get it by calling form.getToolBarManager(). Once you got the manager you can add your own contribution items or (legacy) actions to it. But what if you could allow other bundles/developers to add contributions to your forms toolbar too? There exists already an extension point that allows adding of contributions to menus and toolbars. You most likely used it already to customize your popup menus or your RCP applications main menu.

How to implement

The menuConstribution extension point works in conjunction with the IMenuService. This service allows you to put matching contributions into any ContributionManager. It respects the current workbench evaluation state so contributions with expressions are carefully evaluated before they are added to the ContributionManager. The menu service also takes care of enabling the contributions and manages their visibility dynamically. Basically all that you already know from addin contributions to the various Eclipse menus and toolbars. To get the contributions you are interested in, you first have to decide on a menu URI schema that identifies contributions for your form. We should follow the Eclipse Schema and define "form:" as our new schema and the following parameter is the ID of the form. The ID can be anything and you as a programmer decide for each form that you create what its ID should be. A common way I use is, if the form is embedded into a ViewPart, to use the ViewPart.getSite().getId() method. So I would call

menuService.populateContributionManager(toolbarManager, "form:"+getSite().getId());

Cleanup

You have to remember to release the contributions when your form is disposed or otherwise the IMenuService will continue to track your contributions and waste time as well as resources. So be a good contribution citizen and call menuService.releaseContributions(toolbarManager) and also toolbarManager.dispose()to allow it to clean up its resources. I recommend using a DisposeListener on the form to perform the cleanup.

Extension: Allow contributions to any form

Much like you can add contributions to the global popup menu using the "popup:org.eclipse.ui.popup.any" we can define our new "form:org.eclipse.ui.form.any" URI that allows contributions to be added to each forms toolbar.

ContributionHelper.contributeTo(toolbarManager, "form:" + getSite().getId(), "form:org.eclipse.ui.form.any");

/**
* Adds menu contributions to a {@link ContributionManager} using the
* {@link IMenuService}.
*
* @param contributionManager
* @param locations
*            The format is the Menu API URI format.
*/
public static void contributeTo(final ContributionManager contributionManager, final String... locations) {
final IMenuService menuService = (IMenuService)PlatformUI.getWorkbench().getService(IMenuService.class);

for (final String location : locations) {
 menuService.populateContributionManager(contributionManager, location);
}
contributionManager.update(false);
}