Contributing Actions to the Eclipse Workbench

1. Contributing Actions to the Eclipse Workbench

2. 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

3. The Workbench

4. Where you can contribute actions

5. 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.

6. 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.

7. 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>

8. 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.

9. 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 optionalicon attribute is specified as a path relative to the plug-in directory.

10. 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.

11. 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.

12. 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.

13. 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.

14. 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.

15. Example 1

16. 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>

17. <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>

18. Result

19. 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)

20. 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.

21. 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>

22. 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.

23. nameFilter • used to further constraintthe 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

24. 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 implementIActionFilter).

25. The result

26. Contributing actions via action sets • An action set is a set of actions thatmay 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.

27. 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“/>

28. <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.SetAction2Delegate“/> </actionSet> </extension>

29. 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

30. 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 >

31. 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 >

32. 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

33. 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“>    <actionid="org.eclipse.ui.articles.action.contribution.view.action1“ label="View Action1“ icon="icons/red_dot.gif"          tooltip="Tooltip for View Action1“ 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>

34. 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

35. 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} }* }

36. 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? ) ##

37. enablesFor attr • enablesFor: • a value indicating the selection count which must be met to enable the action. • If attribute givenand condition met => action enabled. • If attribute givenand 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

38. 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. }

39. 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 }

40. 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 • }

41. 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. • }

42. 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.

43. 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>

44. The result of Ex5

45. 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.

46. 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>

47. <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>

48. 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

49. 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.

50. Summary: IActionDelegate Hierarchy • IActionDelegate (run(…), selectionChange(…) ) • IActionDelegate2 :( runwithEvent(), init(…),dispose() ) • IWorkbenachWindowActinoDelegate • IWorkbenchWindowPulldownActionDelegate • IObjectActionDelegate • EditorActionDelegate • ViewActionDelegate