contributing actions to the eclipse workbench
DESCRIPTION
Contributing Actions to the Eclipse Workbench. 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 - PowerPoint PPT PresentationTRANSCRIPT
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.