Contributing Actions to the
Eclipse Workbench
1
Summary



The Eclipse Platform is an open and extensible
platform.
This article explains in detail
» how to extend the Workbench by adding new
actions and
» provides guidance to the plug-in developers on
how they can design for extensibility.
Reference
» Workbench Menu Contribution
2
The Workbench
3
Where you can contribute actions
4
The places you can put actions




the context menu (s) of a view / editor
the local toolbar and pull down menu of a view
to the main toolbar and menu bar of the
Workbench window (for the whole workbench/ an
editor)
Can contribute actions to viewers/editors from
other plug-ins
» which need these views and editors extensible
» The editors/context menus should have their
target IDs.
5
Contributing actions to context
menus


Extension point: org.eclipse.ui.popupMenus
» Provider: the Workbench plug-in
(org.eclipse.ui)
Types of action contributions to context menus.
» Viewer Contribution :
– to the context menu of a specific editor/view,
» Object Contribution :
– Contributed to a specific object type via registration.
6
Example 1: Adding an action to the
default text editor
<extension point="org.eclipse.ui.popupMenus">  id of the extension-point
<viewerContributionA ↓ id of this contribution
id="org.eclipse.ui.articles.action.contribution.popup.editor“
targetIDB="#TextEditorContext">  id of the context menu
<actionC
↓ id the the action
id="org.eclipse.ui.articles.action.contribution.editor.action1“
label="Editor Action 1"
 user viewable text
icon="icons/red_dot.gif"  path to icon relative to plug-in dir
menubarPathD="additions“  where to put the action in cxt menu
classE="org.eclipse.ui.articles.action.contribution.EditorAction1Delegate">
</action>
↑ implementation class of the action
</viewerContribution>
</extension>
7
Notes




The XML element above declares a contribution to the
context menu of a specific editor.
These extensions are called viewer extensions
A: The term viewer is used to represent both views and
editors.
B: id -- the id of the editor/view
» targetID is the id of the context menu for the
editor/view.
» should be documented in javadoc of the plug-in.
– id not specified => the context menu is not registered by the
plug-in for external action contribution.
– A view or editor may have more than one context menus.
8
Notes

C:The actual action to be contributed to the
context menu
» 1. assign an identifier to the action using the id
attribute.
» The label and icon appearing in the context
menu are given using the label and icon
attributes.
» The optional icon attribute is specified as a
path relative to the plug-in directory.
9
menubarPath


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 expected to provide this group indicating the
default location where action contributions can be
placed.
» may provide other groups where action contributions
can be added.  should be documented.
» If the menubarPath attribute is not specified
– add the action in the group "additions".
– If "additions" group does not exist  append to the end of the
context menu.
10
Note about context menus


Unlike editor/view/actions, the context menus for
view/editor are not declared in plugin.xml.
» After version 3.2, there is an extension point
org.eclipse.ui.menu intended to serve this purpose, but
it is not fully functional now.
To make context menu known to other plugins, the
plugins should register their menus by the methods:
» IWorkbenchPart.registerContextMenu([String menuId
,] MenuManager, ISelectionProvider)
» default menuId = part id.
» ≥ 2 menus  register each with id = partId.menu_part.
» Each menu should define an ‘’additions” group for
others to contribute actions/submenu.
11
classE attribute




is the Java class that will perform the action when the
menu item is selected by the user.
Editor  must implement the
org.eclipse.ui.IEditorActionDelegate interface
» View  org.eclipse.ui.IViewActionDelegate
» Object  org.eclipse.ui.IObjectActionDelegate
lazy loading
» loaded by the Workbench only when the user selects
the menu item for the first time.
This means that the initial enablement logic must be
described in XML.
» Once the delegate class loaded, the delegate can
control the enabled/disabled & visible/hide state of the
action.
12
IEditorActionDelegate,



Interface IActionDelegate
» selectionChanged(IAction, ISelection)
» run(IAction)
IEditorActionDelegate extends IActionDelegate
» setActiveEditor(IAction,IEditorPart)
» allows the action delegate to retarget itself to the active
editor.
only one delegate is created for the action and is shared by
all instances of the same editor type.
» 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.
13
IViewActionDelegate


interface IViewActionDelegate extends
IActionDelegate
» init( IViewPart part);
» allows the action delegate, during initialization,
to target itself with the view instance it should
work with.
» typical implementaiton: {
»
this.part = part; }
When the action is invoked via its run() method, it
must act upon the view passed to init method.
14
Example 1
15
Example 2:
Adding a sub-menu to the Navigator view
<extension point="org.eclipse.ui.popupMenus">
<viewerContribution
id="org.eclipse.ui.articles.action.contribution.popup.navigator"
targetID="org.eclipse.ui.views.ResourceNavigator">
<action
id="org.eclipse.ui.articles.action.contribution.navigator.action1"
label="View Action 1"
icon="icons/red_dot.gif"
menubarPath="additions"
class=
"org.eclipse.ui.articles.action.contribution.ViewAction1Delegate"
enablesFor="!“/>
<menu
id="org.eclipse.ui.articles.action.contribution.navigator.subMenu“
label="View Sub Menu"
path="additions">
<separator name="group1"/></menu>
16
<action id="org.eclipse.ui.articles.action.contribution.navigator.action2"
label="View Action 2“ icon="icons/red_dot.gif“
menubarPath=
"org.eclipse.ui.articles.action.contribution.navigator.subMenu/group1“
class="org.eclipse.ui.articles.action.contribution.ViewAction2Delegate"
enablesFor="1“ />
<action
id="org.eclipse.ui.articles.action.contribution.navigator.action3"
label="View Action 3" icon="icons/red_dot.gif"
menubarPath=
"org.eclipse.ui.articles.action.contribution.navigator.subMenu/group1“
class="org.eclipse.ui.articles.action.contribution.ViewAction3Delegate“
enablesFor="2+“/>
</viewerContribution> </extension>
17
Result
18
enabledFor attribute




Used to control 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.
is the selection count condition which must be met to
enable the action.
» If not met ==> the action is disabled.
» If not given ==> the action is enabled for any number
of items selected.
Meaning of enablesFor Formats
»!
0 items selected
» ?, +, * 0 or 1, 1 or more, 0 or more items selected
» multiple, 2+ 2 or more items selected
»n
n items selected (e.g. 4)
19
menu Element


specify a sub menu.
» label attr is the text displayed in the menu.
» path attr specifies the path, starting at the root of the
context menu.
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 ( ).
» A menu separator item is added by the Workbench
menu manager above and below the group as needed.
20
Example 3: Adding an action to an object
<extension point="org.eclipse.ui.popupMenus">
<objectContribution
id="org.eclipse.ui.articles.action.contribution.popup.object"
objectClass="org.eclipse.core.resources.IFile"
nameFilter="*.java">
<filter
name="projectNature"
value="org.eclipse.jdt.core.javanature“/>
<action
id="org.eclipse.ui.articles.action.contribution.object.action1“
label="Object Action 1"
icon="icons/red_dot.gif"
menubarPath="additions“
class=
"org.eclipse.ui.articles.action.contribution.ObjectAction1Delegate“/>
</objectContribution>
</extension>
21
ObjectContribution


declares a contribution to every context menu
» but only when the selected objects all match
the type specified in the objectClass attribute.
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.
22
nameFilter


used to further constraint the selection
» In this example, only IFiles that end with the
.java extension are considered.
Value compared to the
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.
» not specified ==>no filtering is done on name
23
The filter element


additional way of controlling the enablement of an
action.
are name/value pairs of attributes for the objects
in the selection.
» allowable name/values are type-specific.
» Workbench delegates filtering to the actual
selection (which must implement IActionFilter).
24
The result
25
Contributing actions via action
sets


An action set is a set of actions that may appear
together on menus, menu items,or toolbar items
to the main menu bar and toolbar of the
Workbench window.
intended use of action sets:
» common actions not specific to any particular
view or editor.
» Typically, an action set would include creation
actions, global actions, etc.
» not a mechanism for a view to "promote" its
actions to the main menu bar and toolbar.
26
Example: Adding an action set with
two tool bar items
<extension point="org.eclipse.ui.actionSets">
<actionSet
id="org.eclipse.ui.articles.action.contribution.set"
label="Action Set 1" visible="false">
<action
id="org.eclipse.ui.articles.action.contribution.set.action1"
label="Set Action 1"
icon="icons/red_dot.gif"
tooltip="Tooltip for Set Action 1"
toolbarPath="Normal/additions" class=
“org.eclipse.ui.articles.action.contribution.SetAction1Delegate
“/>
27
<action
id="org.eclipse.ui.articles.action.contribution.set.action2"
label="Set Action 2"
icon="icons/red_dot.gif"
tooltip="Tooltip for Set Action 2"
toolbarPath="Normal/additions"
pulldown="true"
class="org.eclipse.ui.articles.action.contribution.SetAction
2Delegate“/>
</actionSet>
</extension>
28
Configuration Markup:
<!ELEMENT extension (actionSet+)>
<!ATTLIST extension
point
CDATA #REQUIRED
id
CDATA #IMPLIED
name CDATA #IMPLIED >



point = “org.eclipse.ui.actionSets”
id – (simple) identifier of the extension instance
name - an optional name of the instance
29
actionset element
<!ELEMENT actionSet (menu* , action*)>
 Used to define a group of actions and/or menus.
<!ATTLIST actionSet
id
CDATA #REQUIRED
label
CDATA #REQUIRED
visible (true | false)
description CDATA #IMPLIED >
30
action element
<!ELEMENT action (selection* | enablement?)>
 defines an action that the user can invoke in the UI.
<!ATTLIST action id , label CDATA #REQUIRED
accelerator, definitionId CDATA #IMPLIED
menubarPath : location in menubar
toolbarPath : location in toolbar
icon, disabledIcon, hoverIcon,
tooltip, helpContextId CDATA #IMPLIED
style
(push|radio|toggle|pulldown) "push"
state
(true | false) :checked/selected initially for
radio/toggle style
pulldown
(true | false)
class
CDATA #IMPLIED
retarget (true | false)
allowLabelUpdate (true | false)
enablesFor
CDATA #IMPLIED >
31
Contributing actions to a view's
menu or toolbar


A view has a local toolbar and drop down menu
whose contents were initially populated by the
view itself.
Other plugins can contribute actions to these
places via the extension point:
» org.eclipse.ui.viewActions
32
Example 4: Adding actions to the
Navigator view's menu and toolbar
<extension point="org.eclipse.ui.viewActions">
<viewContribution
id="org.eclipse.ui.articles.action.contribution.view“
targetID="org.eclipse.ui.views.ResourceNavigator“ >
<action id="org.eclipse.ui.articles.action.contribution.view.action1“
label="View Action 1“
icon="icons/red_dot.gif"
tooltip="Tooltip for View Action 1“
menubarPath="additions"
class="org.eclipse.ui.articles.action.contribution.ViewAction1Delegate"
enablesFor="*"> </action>
<action
id="org.eclipse.ui.articles.action.contribution.view.action2"
label="View Action 2"
icon="icons/red_dot.gif"
tooltip="Tooltip for View Action 2"
toolbarPath="group1"
class="org.eclipse.ui.articles.action.contribution.ViewAction2Delegate"
enablesFor="*">
<selection class="org.eclipse.core.resources.IFile" name="*.java“ />
</action>
</viewContribution> </extension>
33
RelaxNG Schema for viewActions


Element extension {
» attr point {“org.eclipse.ui.viewActions”}
» attr id { fullyID }?
» attr name { text }?
» viewContribution* }
viewContribution = Element viewContribution {
» attr id {fullyID } ## ID of this contribution
» targetID {viewIDRef} ## ID of registered target
view
» Menu* ##contributed menus
» Action* } ##contributed actions
34

Menu = Element menu {
» attr id {fullyID } ## ID of this menu
» attr label {text} ## translatable text
» attr path { “menuID/…/menuID/GroupID” }
» Element seperator { ## an visible insertion point
– attr name {fullyID} }+
» Element groupMarker { ## an invisible insertion
point
– attr name {fullyID} }*
}
35
The action element

Action = Element action {
» attr id {fullyID}
attr lable {text}
» attr class { classFName } ## implement IViewActionDelegate
» ## icons
» attr icon, disableIcon, hoverIcon {path}?
» ## action location
» attr menubarPath, toolbarPath { … }?
» attr tooltip {text}?
» attr helpContextId { }?
» attr style { “toggle” | “push” (default) | “radio” }?
– actions with radio style in a menu or toolbar group form a radio set.
» attr state {“true” | “false” (default) }? ## used when toggle or radio
» attr enablesFor {text}? ## selection count to enable the action
» ( Selection* | ## selection rule to enable action
»
enablement? ) ##
36
enablesFor attr



enablesFor :
» a value indicating the selection count which must be met to enable the
action.
» If attribute given and condition met => action enabled.
» If attribute given and condition not met => disabled.
» If attribute not given => the action enabled for any number of items
selected.
Attribute formats supported:
» ! => 0 items selected
» ? => 0 or 1 items selected
» + => 1 or more items selected
» multiple, 2+ => 2 or more items selected
» n (n is any number) => a precise number of items selected.
Example:
» enablesFor=" 4" => enables the action only when 4 items are selected
» enablesFor =“*" - => eb=nabled when any number of items selected
37
The selection element

Selection = Element selection { ## This element
help determine the action enablement based on
the current selection. Ignored if the enablement
element is specified.
» attr class {className } ## the class or
interface name that the object selected must
implement to enable the action
» attr name {text}? ## additional wildcard name
filter, will disabled if match fails.
}
38
The enablement element





Enablement = Element enablement {
» ## used to define the enablement condition for
the action
» Component }
Component = (
» and
| or
|
not |
» objectClass | objectState
|
» pluginState | systemProperty )
and = Element and { Component Component }
or = Element or { Component Component }
not = Element not {Component }
39


objectClass = Element objectClass {
» attr name { ClassFName }
» ## true if all selected objects belong to this class or
interface }
objectState = Element objectState {
» attr name {text}
» attr value {text}
» ## true if the property specified by the name attr of
selected object is equal to the value attr.
» ## To evaluate, each selected object must implement
or adapt to …ui.IActionFilter
»}
40


pluginState = Element pluginState {
» attr id { PluginID }
» attr value { “installed” | “activate” }
» ## true if the specified plugin found and meet the value
condition.
»}
systemProperty = Element systemProperty {
» attr name {text}
» attr value {test}
» ## true if the java system property @name is @value.
»}
41
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.
42
Example 5: Adding actions to the default
text editor's toolbar
<extension point="org.eclipse.ui.editorActions">
<editorContribution
id="org.eclipse.ui.articles.action.contribution.editor"
targetID="org.eclipse.ui.DefaultTextEditor">
<action
id="org.eclipse.ui.articles.action.contribution.editor.action1"
label="Editor Action 1"
icon="icons/red_dot.gif"
tooltip="Tooltip for Editor Action 1"
toolbarPath="Normal/additions"
class="org.eclipse.ui.articles.action.contribution.EditorAction1Delegate"></action>
<action
id="org.eclipse.ui.articles.action.contribution.editor.action2"
label="Editor Action 2"
icon="icons/red_dot.gif"
tooltip="Tooltip for Editor Action 2"
helpContextId="org.eclipse.ui.articles.action.contribution.editor.action2"
toolbarPath="Normal/save.ext"
class="org.eclipse.ui.articles.action.contribution.EditorAction2Delegate"></action>
</editorContribution>
</extension>
43
The result of Ex5
44
Example 6: Adding actions to the default
text editor's menu bar

works: contribute to
the default text
editor's menu bar the
following:
» an action to the
File menu,
» a sub-menu with
two actions to the
Edit menu,
» a new top level
menu with one
action.
45
The extension
<extension point="org.eclipse.ui.editorActions">
<editorContribution
id="org.eclipse.ui.articles.action.contribution.editor2"
targetID="org.eclipse.ui.DefaultTextEditor">
<action id="org.eclipse.ui.articles.action.contribution.editor.action1"
label="Editor Action 1"
icon="icons/red_dot.gif"
tooltip="Tooltip for Editor Action 1"
menubarPath="file/save.ext"
class="org.eclipse.ui.articles.action.contribution.EditorAction1Delegate">
</action>
<menu
id="org.eclipse.ui.articles.action.contribution.editor.subMenu"
label="Editor Sub Menu"
path="edit/additions">
<separator name="group1"/></menu>
<action id="org.eclipse.ui.articles.action.contribution.editor.action2"
label="Editor Action 2"
icon="icons/red_dot.gif"
tooltip="Tooltip for Editor Action 2"
menubarPath="org.eclipse.ui.articles.action.contribution.editor.subMenu/group1"
class="org.eclipse.ui.articles.action.contribution.EditorAction2Delegate">
</action>
46
<action id="org.eclipse.ui.articles.action.contribution.editor.action3"
label="Editor Action 3"
icon="icons/red_dot.gif"
tooltip="Tooltip for Editor Action 3“
menubarPath="org.eclipse.ui.articles.action.contribution.editor.subMenu/group1"
class="org.eclipse.ui.articles.action.contribution.EditorAction3Delegate">
</action>
<menu
id="org.eclipse.ui.articles.action.contribution.editor.topLevelMenu"
label="EditorTopLevelMenu"
path="additions">
<separator name="group1"/></menu>
<action
id="org.eclipse.ui.articles.action.contribution.editor.action4"
label="Editor Action 4"
icon="icons/red_dot.gif"
tooltip="Tooltip for Editor Action 4"
menubarPath="org.eclipse.ui.articles.action.contribution.editor.topLevelMenu/
group1"
class="org.eclipse.ui.articles.action.contribution.EditorAction4Delegate">
</action></editorContribution> </extension>
47
RelaxNG Schema for editorActions


Element extension {
» attr point {“org.eclipse.ui.editorActions”}
» attr id { fullyID }?
» attr name { text }?
» editorContribution* }
editorContribution = Element editorContribution {
» attr id {fullyID } ## ID of this contribution
» targetID {viewIDRef} ## ID of registered target editor
» Menu* ##contributed menus; same as in viewActions
» Action* } ##contributed actions
48
The action element

Action = Element action {
» attr definitionId {commandID}
» … #some umimportants omitted
» attr id {fullyID}
attr lable {text}
» attr class { classFName } ## implement IEditorActionDelegate
» ## icons
» attr icon, disableIcon, hoverIcon {path}?
» ## action location
» attr menubarPath, toolbarPath { … }?
» attr tooltip {text}?
» attr helpContextId { }?
» attr style { “toggle” | “push” (default) | “radio” }?
– actions with radio style in a menu or toolbar group form a radio set.
» attr state {“true” | “false” (default) }? ## used when toggle or radio
» attr enablesFor {text}? ## selection count to enable the action
» ( Selection* | ## selection rule to enable action
»
enablement? ) ## Blue parts are the same as in viewActions.
49
Summary:
IActionDelegate Hierarchy

IActionDelegate (run(…), selectionChange(…) )
» IActionDelegate2 :( runwithEvent(),
init(…),dispose() )
» IWorkbenachWindowActinoDelegate
– IWorkbenchWindowPulldownActionDelegate
» IObjectActionDelegate
» EditorActionDelegate
» ViewActionDelegate
50
Contents of various actino delegates




IActionDelegate : // for all actions
» run(IAction)
» selectinoChange(IAction, ISelection)
IActionDelegate2 // for all actions
» dispose()
» runWithEvent(IAction, Event)
» init(IAction)
ActionDelegate implements IActionDelegate2.
IViewActionDelegate // for view or viewer
contribution
» init(IViewPart)
51




IEditorActionDelegate // for editorContribution or
viewContribution
» setActiveEditor(IActino, IEditorPArt)
IObjectActionDelegate // for objectContribution
» setActivePart(IAction, IWorkbenchPart)
IWorkbenchWindowActionDelegate // actionset
» dispose()
» init(IWorkbenchWindow)
IWorkbenchWindowPulldownDelegate (2) //
actionset
» getMenu(Control parent)
» getMenu(Menu) // for (2)
52
Eclipse Platform Command
Framework
53



Problem:
» How to trigger actions in Eclipse using
keyboard ?
Solution:
» use the platform command framework.
» see also Eclipse online help reference,
»
and Key
Concepts used:
» action, command, (command) category,
» keyBinding, (key binding) scheme,
» (key) context.
54