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 menuclassE="org.eclipse.ui.articles.action.contribution.EditorAction1Delega

te">  </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 optional icon 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 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

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 implement IActionFilter).

25

The result

26

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.

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

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

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

51

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)

52

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)

53

Eclipse Platform Command Framework

54

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.