Contributing Actions to the Eclipse Workbench

Summary

The Eclipse Platform is an open and extensible platform. This article
explains in detail how the Workbench can be extended to add new actions
and provides guidance to the plug-in developers on how they can design
for extensibility.

Introduction

The Eclipse Platform allows a plug-in to extend other plug-ins, allowing
for a tight integration and therefore a better experience for the end
user. This article illustrates how to contribute actions to views and
editors of other plug-ins, and allowing for others to contribute to your
own custom views and editors. Each example explores in detail the
different features available when contributing actions. Once understood,
these features can be combined to control the contribution of actions
within views and editors.

The image above shows the many areas where a plug-in can contribute
actions:

to the context menu of a view or editor

to the local toolbar and pull down menu of a view

to the main toolbar and menu bar of the Workbench window

Each different contribution area is examined in this article, with
examples showing how to contribute actions to each.

In order for an Independent Software Vendor (ISV) to contribute
actions to other views and editors, plug-ins need to make their views
and editors extensible. This article shows how a plug-in can allow
action contributions from other plug-ins.

This article assumes a basic understanding of writing a plug-in.
For more information on how to write a plug-in for the Eclipse Platform,
please read the article from Jim Amsden, "Your
First Plug-in".

Contributing actions to context menus

The ability to add actions to the context menu of a view or editor
allows tight integration between plug-ins. For example, the Version and
Configuration Management plug-in (VCM) adds a number of new actions to
existing views such as the Navigator and Packages views, allowing the
user to version manage resources from existing views. To contribute an
action to a context menu, the Workbench plug-in (org.eclipse.ui)
provides the extension point org.eclipse.ui.popupMenus.
There are two types of action contributions. Actions can either be
contributed to the context menu of a specific editor or view, or they
can be registered against a specific object type. The following three
examples will look at each in detail.

Example 1: Adding an action to the default text
editor

Let's look at how to add a single action to the
context menu of the default text editor provided by the Workbench
plug-in.

The XML above declares a contribution to the context menu of a specific
editor. These extensions are called viewer extensions (). The term viewer is
used to represent both views and editors.

The targetID attribute () specifies the context menu identifier for
the target view or editor. The documentation of the plug-in providing
the view or editor will list the identifier to use. If none is specified
in the documentation, then the context menu is not registered by the
plug-in for external action contribution. A view or editor may have more
than one context menu.

Unfortunately, the default text editor does not follow the guidelines
for plug-in developers. The context menu identifier is not part of the
default text editor documentation as it should be. Also, the identifier
is not fully qualified as recommended by the plug-in developer
guidelines.

The action to be contributed to the context menu is described
next in XML ().
The first step is to assign an identifier to the action using the id
attribute. The label and icon that will appear in the context menu are
given next using the label and icon attributes. The
optional icon attribute is specified as a path relative to the
plug-in directory.

The menubarPath attribute () specifies the path, starting at the root of
the context menu, where this action will be added. In this example,
“additions” is the value of the constant org.eclipse.ui.IWorkbenchActionConstants.MB_ADDITIONS.
Plug-ins are expected to provide this group once in their context menus
indicating the default location where action contributions can be
placed. Plug-ins may provide other groups in their context menus where
action contributions can be added. In this case, it is recommended that
plug-ins document each group. If the menubarPath attribute is not
specified, the Workbench will first attempt to add the action in the
group “additions”. If the group “additions” does
not exist, then the action is added to the end of the context menu.

The class attribute () specifies the Java™ class that will
perform the action when the menu item is selected by the user. This
class must implement the org.eclipse.ui.IEditorActionDelegate
interface if contributing to an editor's context menu or the org.eclipse.ui.IViewActionDelegate
interface if contributing to a view's context menu. One very important point to understand about the
delegate class is that this class is loaded by the Workbench only when
the user selects the menu item for the first time because plug-ins are
loaded lazily. This means that the initial enablement logic must be
described in XML. Once the delegate class has been loaded by the
Workbench, the delegate can control the enabled/disabled state of the
action.

The interface IEditorActionDelegate allows the
action delegate to retarget itself to the active editor. This is
important because only one delegate is created for the action and is
shared by all instances of the same editor type. The action delegate
must implement the method setActiveEditor(IAction action,
IEditorPart targetEditor). When the action is invoked via its run()
method, it must act upon the active editor given to the delegate via the
last setActiveEditor() method call.

The interface IViewActionDelegate allows the action
delegate, during initialization, to target itself with the view instance
it should work with. The action delegate must implement the method init(IViewPart
view). When the action is invoked via its run() method, it
must act upon the view passed to init() method.

The image above shows the result of running this example. Notice the
"Editor Action 1" is added to the editor's context menu. This is where
the “additions” group is located in the default text editor
context menu.

Example 2: Adding a sub-menu to the Navigator
view

Let's look at how to add one action and a
sub-menu with two actions to the Navigator view.

The XML above declares that a contribution to the context menu of the
Navigator view is requested (). The first action contribution () is then defined just
like the previous example. The attributes described in the previous
example are skipped to focus on the new attributes and features of this
example.

Notice the attribute enablesFor in the action definition (). This attribute
controls the enabled/disabled state of the action based on the current
selection. The current selection is obtained from the selection provider
given when the context
menu was registered by the plug-in developer. The enablesFor
attribute value is the selection count condition which must be met to
enable the action. If the condition is not met the action is disabled.
If the attribute is left out, the action is enabled for any number of
items selected. The following attribute formats are supported:

Formats

Description

!

0 items selected

?

0 or 1 items selected

+

1 or more items selected

multiple, 2+

2 or more items selected

n

a precise number of items selected (e.g. 4)

*

any number of items selected

Action enablement is declared in XML because plug-ins are loaded
lazily. Until an action is actually invoked by the user, the plug-in is
not loaded and the Workbench uses the enablement logic declared in XML.
Once a plug-in is loaded, the delegate class is notified of selection
changes and can update the enabled/disabled state of the action. Refer
to the org.eclipse.ui.IActionDelegate.selectionChanged(IAction
action, ISelection selection) method documentation for more details.

The menu element (), in this example, specifies the sub menu. The label
attribute value is the text displayed in the menu. The path
attribute specifies the path, starting at the root of the context menu.
This attribute works like the menubarPath attribute of the action
element which was discussed in the first example.

Within the menu element (), notice that a separator was defined (). A separator serves
as a group name into which actions can be added. In this example, the
last two actions defined use this separator name in their menubarPath
attribute (). This
is how the two actions are placed in the sub menu. A menu separator item
is added by the Workbench menu manager above and below the group as
needed.

The image above shows the result of running this example. Notice the
sub menu added to the Navigator's context menu.

The order in which the actions are added to the menu and sub menu
is in the same order of how they are listed in the plugin.xml file.

Example 3: Adding an action to an object

Let's look at how to add a single action to a
.java file in a Java project.

The XML above declares a contribution to every context menu () but only when the
selected objects all match the type specified in the objectClass
attribute (). The
attribute can be either a fully qualified class or interface name. When
the selection is heterogeneous, the contribution will be applied if it
is registered against a common type of the selection. If a direct match
is not possible, matching against super classes and super interfaces
will be attempted. The action contribution is dependent on the selection
only containing objects of the specified type, and is not limited to one
view or editor's context menu.

For example, if the file "f1.java" and the project "Java Project"
are selected in the Navigator when the context menu is shown for that
view, then the action contribution defined by the XML above would be
excluded because the object "Java Project" is of type IProject
not IFile, and IFile is not a super interface
of IProject. However, if the objectClass attribute
value in the XML above was org.eclipse.core.resources.IResource,
then the action contribution would be included because IResource is a
super interface of both IFile ("f1.java") and IProject ("Java Project"),
neglecting for the moment the nameFilter attribute.

The nameFilter attribute () is used to further constrain the selection
to which this action will apply. In this example, only IFiles
that end with the .java extension are considered. The value of this
attribute is compared to the org.eclipse.ui.model.IWorkbenchAdapter.getLabel()
method result for each object in the selection. If the object does not
have an IWorkbenchAdapter, then the object's toString()
method is used. If this attribute is not specified, then no filtering is
done on the object's name.

The filter element () provides another way of controlling the
enablement criteria of an action. These are name/value pairs of
attributes for the objects in the selection. The attributes which apply
to the selection are type-specific, so the Workbench delegates filtering
at this level to the actual selection (see IActionFilter
javadoc). In this example, the object attribute name, "projectNature",
is defined on IResourceActionFilter and is applicable to
all IResources. Therefore, the action contribution will
only happen if the IProject of each object in the selection
has a Java nature. Refer to the documentation on IActionFilter and its
sub-interfaces for a list and description of other named attributes. For
more information about project natures, refer to the documentation on org.eclipse.core.resources.IProjectNature
interface.

For object contributions, the class attribute () of the action
element is the name of a Java class that implements the org.eclipse.ui.IObjectActionDelegate
interface. The interface IObjectActionDelegate allows the
action delegate to retarget itself to the active part. This is important
because only one delegate is created for the action and is shared by all
instances of IWorkbenchPart. The action delegate must
implement the method setActivePart(IAction action,
IWorkbenchPart targetPart). When the action is invoked via its run()
method, it must act upon the active part given to the delegate via the
last setActivePart() method call.

The image above shows the result of running this example. Notice the
object action contribution is added to the Navigator's context menu
because a .java file within a Java project is selected.

Within the Workbench, action contributions to a context menu is only
possible when the menu is made known to the Workbench. This is a
voluntary process, but plug-ins are encouraged to expose their menus so
that ISVs may extend them. This increases the overall extensability and
integration of the platform.

Each context menu should be registered with the Workbench. This
is accomplished by calling either org.eclipse.ui.IWorkbenchPartSite.registerContextMenu(MenuManager
menuManager, ISelectionProvider selectionProvider) or org.eclipse.ui.IWorkbenchPartSite.registerContextMenu(String
menuId, MenuManager menuManager, ISelectionProvider selectionProvider).
If a view or editor has more than one context menu to expose, then each
one needs to be registered. Once the context menu is registered, the
Workbench will automatically insert any action contributions which exist
into the menu.

As part of the context menu registration, a unique identifier for
each context menu is required to avoid conflicts in the Workbench global
registry of context menus. For consistency across all parts, the
following strategy should be adopted by all plug-ins registering a
context menu:

If the view or editor has only one context menu, it should be
given the same identifier as the view or editor's identifier. For
convenience, publishers can call registerContextMenu(MenuManager,
ISelectionProvider) on IWorkbenchPartSite.

If the view or editor has more than one context menu, each
should be given a unique identifier whose prefix is the identifier of
the view or editor. For example, an editor, with identifier com.xyz.bestEditor,
has two context menus. The first context menu identifier would be org.xyz.bestEditor.menu1
and the second context menu identifier would be com.xyz.bestEditor.menu2.
Register each context menu by calling registerContextMenu(String,
MenuManager, ISelectionProvider) on IWorkbenchPartSite.

All context menu identifiers should be published within the javadoc of
the view or editor. This makes it easier for ISVs to determine the menu
identifier for a particular part and define action contributions. These
identifiers are used as the targetID attribute value in action
contributions.

Publishers of context menus should include the standard insertion
point identifier IWorkbenchActionConstants.MB_ADDITIONS.
This default reference point is used for insertion of actions
contributed by ISVs. The insertion point is defined by adding a
GroupMarker to the menu at an appropriate location for insertion. Other
insertion points can be defined and published within the javadoc of the
view or editor. This is strongly recommended to allow ISVs better
control of where the action will be inserted within the context menu.

A plug-in developer of an object that can be part of a selection
in a context menu can implement the org.eclipse.ui.IActionFilter
interface. This is a filtering strategy which can perform type-specific
filtering based on name/value pairs. This permits an ISV to use these
name/value pairs within the filter element in XML to further
restrict which objects the action contribution applies to. The Workbench
will retrieve the filter for the selection by testing to see if it
implements IActionFilter. If that fails, the Workbench will ask for a
filter through the IAdaptable mechanism.

Contributing actions to a view's menu or toolbar

A view has a local pull down menu and a toolbar which is initially
populated by the view itself. Other plug-ins can contribute actions to
this menu and toolbar by using the org.eclipse.ui.viewActions
extension point.

Example 4: Adding actions to the Navigator view's
menu and toolbar

Let's look at how to contribute a different
action to both the pull down menu and toolbar of the Navigator view.

The above XML informs the Workbench that a plug-in wants to contribute
to the Navigator's pull down menu and toolbar (). In this example,
the targetID attribute () refers to the Navigator view identifier.

The first action element () should look familiar by now, with the same
attributes covered in previous examples. The value of the menubarPath
attribute () is
the same as IWorkbenchActionConstants.MB_ADDITIONS constant, which is
the default group that contributors add actions to. Though not shown in
this example, it is possible to add a sub-menu to the view's pull down
menu simply by defining a menu element. Refer to the previous
example on adding
sub-menu to a context menu for more details.

The second action element () is only slightly different than the first
one. Instead of adding the action to the pull down menu (using the menubarPath
attribute), the action is added to the view's toolbar (). The value of the toolbarPath
attribute specifies the group into which the action should be added. If
the group specified does not exist, then it is created at the end of the
toolbar and a separator is added if required. Views may publish groups
to which a plug-in can add actions inside the toolbar. In the case of
the Navigator view's toolbar, it does not publish any groups. Unlike a
menu which has the default IWorkbenchActionConstants.MB_ADDITIONS group,
a toolbar is not required to provide one.

The selection element () can further constrain the selection to
which this action applies. The class attribute specifies the
selection object type that must be met for the action to be enabled. In
this example, the action is only enabled if all the objects within the
selection implement the IFile interface. The name attribute
specifies a wildcard match against each object in the selection. The
value of this attribute is compared to the org.eclipse.ui.model.IWorkbenchAdapter.getLabel()
method result for each object in the selection. In this example, the
action is only enabled if all the objects in the selection end with the
.java extension. The selection element is ignored by the
Workbench if the enablesFor attribute is not specified.

The image above shows the result of running this example. Notice the
action added to the Navigator's pull down menu. The action added in the
toolbar is enabled because the current selection contains .java files.

Developers of a view should include the standard insertion point
identifier IWorkbenchActionConstants.MB_ADDITIONS in the
view's pull down menu. This reference point will be used for insertion
of actions contributed by ISVs. The insertion point is defined by adding
a GroupMarker to the menu at an appropriate location for insertion.
Other insertion points can be defined and published within the javadoc
of the view. This is strongly recommended to allow ISVs better control
of where the action will be inserted within the pull down menu.

Contributing actions to an editor's menu or toolbar

An editor will contribute its actions to the main menu bar and toolbar
of the Workbench window. Another plug-in can contribute actions for a
particular editor by using the org.eclipse.ui.editorActions
extension point. Each action extension is created and shared by all
instances of the same editor type.

Example 5: Adding actions to the default text
editor's toolbar

Let's look at how to contribute two actions to
the toolbar of the default text editor.

As with previous examples, the first few lines instruct the Workbench
that actions are being contributed to the default text editor ( and ). In this example,
two actions are added to the toolbar of the editor.

The toolbarPath attribute value ( and ) is different than previous examples in that
the first segment of the path represents the toolbar identifier, while
the second segment represents the group within the toolbar. The toolbar
identifier allows the plug-in to determine which toolbar the action is
added to. Currently in the Workbench, only one toolbar is supported and
its identifier is "Normal". If the group does not exist, then it is not created within the specified toolbar, and
the action is not added to the specified
toolbar. Valid toolbar groups are listed in the documentation of the IWorkbenchActionConstants
interface and the plugin providing the target editor.

The first action () is added to the default group called IWorkbenchActionConstants.MB_ADDITIONS
using the toolbarPath attribute (). The second action () is being added to
the group called IWorkbenchActionConstants.SAVE_EXT using
the toolbarPath attribute (). Refer to the interface IWorkbenchActionConstants
for a list of other groups provided by the Workbench window main
toolbar.

The image above shows the result of running this example. Notice the
action next to the save tool items and the action added at the end of
the toolbar.

Example 6: Adding actions to the default text
editor's menu bar

Let's look at how to contribute to the default
text editor's menu bar the following:

As in previous examples, the targetID attribute value () lets the Workbench
know that the actions are being added to the default text editor. The
first action declaration specifies a menubarPath attribute (). The value comes
from IWorkbenchActionConstants.M_FILE and IWorkbenchActionConstants.SAVE_EXT
constants. This tells the Workbench to add the action to the save group
of the File menu.

Next a sub-menu is defined in the Edit menu (). The path
attribute of the menu element is made up from the IWorkbenchActionConstants.M_EDIT
and IWorkbenchActionConstants.MB_ADDITIONS constants. The
following two action declarations have a menubarPath attribute ( and ) which specifies the
path to the group created for the sub menu ().

In the Workbench's main menu bar, there is a problem with
contributing actions to a contributed sub-menu. These sub-menu items are
lost by the Workbench, so the sub-menu is empty and therefore is visible
but disabled. This sub-menu problem is only for editor menu
contributions and action set contributions. This is why the sub-menu
contribution to the Edit menu is disabled.

The last part of the XML is used to define a new top level menu
to the left of the Window menu (). The path attribute of the menu element
comes from the IWorkbenchActionConstants.MB_ADDITIONS
constant. This is the default group plug-ins use to add top level menus
to the menu bar. These new menus are always added to the left of the
Window menu.

The last action element has a menubarPath attribute
() which specifies
the path to the group created for the top level menu (). That is the
location where the action is added by the Workbench.

The image above shows the result of running this example. Notice the
action below the save menu items in the File menu and the new top level
menu.

When contributing to the Perspective or Project menu, the path
name is not the same as the menu name. The constant IWorkbenchActionConstants.M_VIEW
is used to represent the path to the Perspective menu and the constant IWorkbenchActionConstants.M_WORKBENCH
is used to represent the path to the Project menu. This is for
historical reasons; these menus were renamed after the constants were
defined as API.

Publishers of an editor should include the standard insertion point
identifier IWorkbenchActionConstants.MB_ADDITIONS in all
top level menus added by the editor. This reference point is used for
insertion of actions contributed by ISVs. The insertion point is defined
by adding a GroupMarker to the menu at an appropriate location for
insertion. Other insertion points can be defined and published within
the javadoc of the editor. This is strongly recommended to allow ISVs
better control of where the action is inserted within the menu bar.

Contributing actions via action sets

An action set is a mechanism that allows a plug-in to contribute menus,
menu items, and toolbar items to the main menu bar and toolbar of the
Workbench window. It is important to understand what action sets are
meant to be used for. An action set should contribute common actions
which are not specific to any particular view or editor. Typically, an
action set would include creation actions, global actions, etc. It is
not a mechanism for a view to "promote" its actions to the main menu bar
and toolbar.

The user can choose which action sets are visible. The goal is to
let users customize the Workbench environment to suit their needs and
override the assumptions made by the plug-in about which actions are
appropriate. Plug-in developers of views and editors are encouraged to
define important actions locally within their own menu and toolbar so
that they are available even when the action set is not visible.

A plug-in uses the org.eclipse.ui.actionSets
extension point to define an action set. These actions appear in the
Workbench window by user preference. See the customize perspective
dialog by selecting the menu item Perspective->Customize... and then
expanding the Other category.

Example 7: Adding an action set

Let's look at how to add an action set which
contains two toolbar items.

The attribute label () specifies the name of the group of actions. This text
appears in the customize perspective dialog box
(Perspective->Customize...) by expanding the "Other" tree item.

The attribute visible () is optional and specifies whether this
action set should be initially made visible when any perspective is
open. This option will only be honoured when the user opens a new
perspective which has not been customized. The user can override this
setting by customizing the perspective. By default, the value of this
attribute is false. Caution should be taken when enabling this attribute
so as not to abuse it. If every plug-in enables this attribute, then all
perspectives will be cluttered with these action sets. A better approach
is for the plug-in to specify which perspective(s) should show its
action sets by using the extension point org.eclipse.ui.perspectiveExtensions.
Please refer to "Extending an Existing Perspective" in Dave Springgay's
article "Using
Perspectives in the Eclipse UI" for more details.

The definition of each action looks the same as in previous
examples. However, the toolbarPath attribute ( and ) value is different
in that the first segment of the path represents the toolbar identifier,
while the second segment represents the group within the toolbar. The
toolbar identifier allows the plug-in to determine which toolbar the
action is added to. Currently in the Workbench, only one toolbar is
supported and its identifier is "Normal". If the group does not exist,
then it is created within the specified toolbar.

The second action definition introduces the optional style
attribute (). When
set to "pulldown", the tool item has an optional pull down menu. The
tool item has the same look as the tool item "Open The New Wizard"
provided by the Workbench window. This attribute is ignored for menu
item contributions.

The class attribute () specifies the Java class that is loaded to
perform the action invoked by the user. This class must implement org.eclipse.ui.IWorkbenchWindowActionDelegate
interface if the style attribute is "push", "radio", or "toggle";
or org.eclipse.ui.IWorkbenchWindowPulldownDelegate
interface if the style attribute is "pulldown". This delegate
class can control the enabled/disabled state of the action when the
selection changes, but only once the plug-in is loaded. Until then, the
enabled/disabled state of the action is controlled by other XML
attributes like enablesFor and selection.

The image above shows the result of running this example. Notice the
two actions added at the end of the toolbar, with one having a drop down
menu option. To show this action set in the current perspective, select
the menu item Perspective->Customize..., expand the Other category,
and check the option "Action Set 1".

Example 8: Supporting actions on custom editors
and views

Let's look at how to add a single action to the
context menu of your own editor or view

This is very similar to Example 1 covered above;
and only differences from Example 1 are
highlighted here. This example uses the XML editor created using the
standard eclipse wizard:

File > New > Project > Plug-in Project

Project Name: org.eclipse.articles.xmlEditor, click "Next"

On the "Templates page", select "Plug-in with an editor" (this
creates a sample XML editor)

Accept all defaults and click to the finish.

The targetID attribute () specifies the context menu identifier for
the target view or editor (XMLEditor.EDITOR_CONTEXT). The
documentation of the plug-in providing the view or editor will list the
identifier to use. If none is specified in the documentation, then the
context menu is not registered by the plug-in for external action
contribution. A view or editor may have more than one context menu.

The code below shows the additions that you have to make to the
XMLEditor created using the standard template.

The image above shows the result of running this example. Notice the
"XML Text Editor Action" is added to the XML editor's context menu. This
is where the “additions” group is located in the default
text editor context menu.

Conclusion

This article has covered the extension points that a plug-in may use to
contribute actions to the Workbench. The best way to learn more about
action contributions is to take the examples and experiment with them.
Plug-in developers should pay special attention to the recommendations
made here so that ISVs can contribute actions and achieve a high level
of integration. More information is available in the Platform Plug-in
Developer Guide from the Help perspective, and in the org.eclipse.ui
extension points documentation from the Platform Plug-in Developer
Guide, expand Reference->Extension Points Reference->Workbench.

Running the examples

The file "action_contribution_examples.zip"
contains the complete source code for all the examples in this article.
Extract the content of the ZIP file into the Eclipse "plugins" directory
to install the action contribution example plug-in. Then edit the
plugin.xml file to uncomment the example to be run.

Notices

Java and all Java-based trademarks and logos are trademarks or
registered trademarks of Sun Microsystems, Inc. in the United States,
other countries, or both.