This extension point allows the plug-in developer to define menus, separators, logical groups and menu items -- appearing anywhere within the application, from status lines to context menus. It also allows sets of such contributions to be defined (i.e., action sets); these action sets can be turned on or off by the end user. In brief, the menus extension point contains all of the presentation elements (except the icons) for contributing to any menu or trim area in Eclipse.
Every element within this extension point is given a unique identifier. This is so that these elements can be referred to elsewhere without having to restate the element. For example, the identifier might be required for ordering or for defining an action set. Also, this allows third-party plug-in developers to place these elements in new locations within the interface, as appropriate.
NOTE: For 3.2 the only part of this extension mechanism that has been implemented is that part associated with 'trim' contributions. Attempting to add items, menus, toolbars or status line entries will act as a NO-OP.
<!ELEMENT extension (item* , menu* , group* , widget*)>
<!ATTLIST extension
point CDATA #REQUIRED
id CDATA #IMPLIED
name CDATA #IMPLIED>
<!ELEMENT item (parameter* , location* , visibleWhen?)>
<!ATTLIST item
id CDATA #REQUIRED
commandId CDATA #REQUIRED
menuId CDATA #IMPLIED>
An item could be a menu item or a trim item, depending on where it is placed. The text and image associated with the item will be drawn from the command.
org.eclipse.ui
might be called org.eclipse.ui.item1
.<!ELEMENT menu (location* , visibleWhen?)>
<!ATTLIST menu
id CDATA #REQUIRED
label CDATA #IMPLIED>
A menu can appear either attached to a tool item, or somewhere within a view menu, context menu or the top-level menu bar. For free, the plug-in developer can assume that there is a menu and tool bar for every view, and that the top-level menu bar exists. Context menus must be registered programmatically before they can be used (see API Information).
A menu can only contain groups.
org.eclipse.ui
might be called org.eclipse.ui.menu1
.<!ATTLIST group
id CDATA #REQUIRED
separatorsVisible (true | false) "true">
A logical group. It can either be visible (e.g., separators are drawn before and after, as appropriate) or invisible. By default, logicial groups are visible.
A group can contain menus, items and other groups.
org.eclipse.ui
might be called org.eclipse.ui.group1
.<!ELEMENT widget (location* , class? , visibleWhen? , layout?)>
<!ATTLIST widget
id CDATA #REQUIRED
class CDATA #REQUIRED>
A menu or trim element that is given direct access to the widgets. For example, this can be used to render a combo box. Unfortunately, this means that if a widget element becomes visible in the user interface, this will lead to plug-in loading. Use this element with caution, as it can cause performance problems. This also will cause problems for things like macro support, scripting and pretty much any other command-based mechanism. When used as trim the widget will only cause the plug-in to load when it becomes visible in the UI.
org.eclipse.ui
might be called org.eclipse.ui.widget1
.IWorkbenchWidget
. Clients may choose to use the default implementation; AbstractWorkbenchTrimWidget
. This implementation handles the 'init' method and caches the result for use through its getWorkbenchWindow
method.<!ELEMENT layout EMPTY>
<!ATTLIST layout
fillMajor (true | false)
fillMinor (true | false) >
This element can be used to specify various layout options for elements added into trim
locations.
false
.false
.<!ELEMENT location (order? , (bar | part | popup))>
<!ATTLIST location
mnemonic CDATA #IMPLIED
imageStyle CDATA #IMPLIED>
A location in which a menu
, group
, item
or widget
can appear. This element is used to control location-specific information.
<!ELEMENT bar EMPTY>
<!ATTLIST bar
type (menu|trim)
path CDATA #IMPLIED>
A leaf element within a location. This can be the menu bar or the trim area. If unqualified, this indicates the top-level menu bar or trim. If this is qualified with a part
element, then this indicates that part's menu or trim.
menu
or trim
. If contributing to the menu, then the item will be parented to some widget structure. In general, this means using widget elements does not make much sense, and an icon for an item's command is not strictly necessary. The default value is menu
.
If contributing to the trim
, then the bar will generally not require a command or an icon, it should be filled with a widget that displays the trim information.
Within the trim, the workbench defines five general groups which correspond to various positions around the window:
vertical1
.'/'
as a separator character.<!ATTLIST class
class CDATA #REQUIRED>
A class element supporting the executable extension parsing syntax for both widget
and dynamic
elements.
IExecutableExtension
.<!ELEMENT visibleWhen (not | or | and | instanceof | test | systemTest | equals | count | with | resolve | adapt | iterate)>
<!ATTLIST visibleWhen
checkEnabled (true | false) "false">
Controls the visibility of the given element.
true
, then there should be no sub-elements. This just checks the enabled state of the command, and makes the corresponding element visible if the command is enabled.<!ATTLIST part
id CDATA #IMPLIED
class CDATA #IMPLIED>
An element within a location. This qualifies the location to refer to a particular workbench part. This can be either a view or an editor. The qualification can use either the class name of the part (including inheritance), or it can refer to the identifier for the view or editor.
Only one of id
and class
can be specified.
<!ELEMENT parameter EMPTY>
<!ATTLIST parameter
name CDATA #REQUIRED
value CDATA #REQUIRED>
A parameter to either an executable extension or a command -- depending on where it appears in the extension.
<!ELEMENT order EMPTY>
<!ATTLIST order
position (start|end|before|after)
relativeTo CDATA #IMPLIED>
Controls the position of a menu, group, item or widget within a particular location.
This attribute accepts the following values: start
(put the element at the beginning of the container); end
(put the element at the end of its container); after
(put the element after the sibling element whose id matches ref
); and, before
(put the element before the sibling element whose id matches ref
). Relative ordering can be applied to any type of menu element.
In the event of conflicts, Eclipse will chose an arbitrary order. The only guarantee is that, in the event of a conflict, the order will remain the same as long as the following holds:
position
is before
or after
.<!ELEMENT popup EMPTY>
<!ATTLIST popup
id CDATA #IMPLIED
path CDATA #IMPLIED>
Part of a location. It indicates that the menu, group, item or widget should appear in the popup menu.
<!ELEMENT enablement (not , and , or , instanceof , test , systemTest , equals , count , with , resolve , adapt , iterate)*>
A generic root element. The element can be used inside an extension point to define its enablement expression. The children of an enablement expression are combined using the and operator.
<!ELEMENT not (not | and | or | instanceof | test | systemTest | equals | count | with | resolve | adapt | iterate)>
This element represent a NOT operation on the result of evaluating it's sub-element expression.
<!ELEMENT and (not , and , or , instanceof , test , systemTest , equals , count , with , resolve , adapt , iterate)*>
This element represent an AND operation on the result of evaluating all it's sub-elements expressions.
<!ELEMENT or (not , and , or , instanceof , test , systemTest , equals , count , with , resolve , adapt , iterate)*>
This element represent an OR operation on the result of evaluating all it's sub-element expressions.
<!ELEMENT instanceof EMPTY>
<!ATTLIST instanceof
value CDATA #REQUIRED>
This element is used to perform an instanceof check of the object in focus. The expression returns EvaluationResult.TRUE if the object's type is a sub type of the type specified by the attribute value. Otherwise EvaluationResult.FALSE is returned.
<!ELEMENT test EMPTY>
<!ATTLIST test
property CDATA #REQUIRED
args CDATA #IMPLIED
value CDATA #IMPLIED>
This element is used to evaluate the property state of the object in focus. The set of testable properties can be extended using the propery tester extension point. The test expression returns EvaluationResult.NOT_LOADED if teh property tester doing the actual testing isn't loaded yet.
<!ELEMENT systemTest EMPTY>
<!ATTLIST systemTest
property CDATA #REQUIRED
value CDATA #REQUIRED>
Tests a system property by calling the System.getProperty method and compares the result with the value specified through the value attribute.
<!ELEMENT equals EMPTY>
<!ATTLIST equals
value CDATA #REQUIRED>
This element is used to perform an equals check of the object in focus. The expression returns EvaluationResult.TRUE if the object is equal to the value provided by the attribute value. Otherwise EvaluationResult.FALSE is returned.
<!ELEMENT count EMPTY>
<!ATTLIST count
value CDATA #REQUIRED>
This element is used to test the number of elements in a collection.
<!ELEMENT with (not , and , or , instanceof , test , systemTest , equals , count , with , resolve , adapt , iterate)*>
<!ATTLIST with
variable CDATA #REQUIRED>
This element changes the object to be inspected for all its child element to the object referneced by the given variable. If the variable can not be resolved then the expression will throw a ExpressionException when evaluating it. The children of a with expression are combined using the and operator.
<!ELEMENT resolve (not , and , or , instanceof , test , systemTest , equals , count , with , resolve , adapt , iterate)*>
<!ATTLIST resolve
variable CDATA #REQUIRED
args CDATA #IMPLIED>
This element changes the object to be inspected for all its child element to the object referneced by the given variable. If the variable can not be resolved then the expression will throw a ExpressionException when evaluating it. The children of a with expression are combined using the and operator.
<!ELEMENT adapt (not , and , or , instanceof , test , systemTest , equals , count , with , resolve , adapt , iterate)*>
<!ATTLIST adapt
type CDATA #REQUIRED>
This element is used to adapt the object in focus to the type specified by the attribute type. The expression returns not loaded if either the adapter or the type referenced isn't loaded yet. It throws a ExpressionException during evaluation if the type name doesn't exist at all. The children of an adapt expression are combined using the and operator.
<!ELEMENT iterate (not , and , or , instanceof , test , systemTest , equals , count , with , resolve , adapt , iterate)*>
<!ATTLIST iterate
operator (or|and) >
This element is used to iterate over a variable that is of type java.util.Collection. If the object in focus is not of type java.util.Collection then an ExpressionException will be thrown while evaluating the expression.
A basic menu definition looks like this.
<menu id=
"com.mycompany.myplugin.projection"
label=
"%Folding.label"
>
<location mnemonic=
"%Folding.label.mnemonic"
>
<part id=
"AntEditor"
>
<popup id=
"#RulerContext"
path=
"rest"
/>
</part>
</location>
</menu>
In this example, the plug-in developer is contributing to all parts who subclass or implement the given type. This allows, for example, for some contributions to be added to all text editors.
<menu id=
"com.mycompany.myplugin.textEditorMenu"
label=
"Text Commands"
>
<location mnemonic=
"X"
>
<part class=
"AbstractTextEditor"
>
<popup id=
"#RulerContext"
path=
"rest"
/>
</part>
</location>
</menu>
It is possible to associate help with a menu.
<menu id=
"com.mycompany.myplugin.RunWithConfigurationAction"
label=
"Run With Configuration"
helpContextId=
"run_with_configuration_context"
>
<location>
<bar />
</location>
</menu>
Within a menu, it is possible to define logical groups. These logical groups can either be visible (e.g., separators are drawn before and after, as appropriate) or invisible. By default, logicial groups are visible.
<group id=
"com.mycompany.myplugin.stepGroup"
>
<location>
<bar path=
"org.eclipse.ui.run"
/>
</location>
</group>
<group id=
"com.mycompany.myplugin.stepIntoGroup"
separatorsVisible=
"false"
>
<location>
<bar path=
"org.eclipse.ui.run"
/>
</location>
</group>
It is possible to place menus, group, items and widgets in multiple locations.
<item id=
"com.mycompany.myplugin.ToggleStepFilters"
commandId=
"com.mycompany.myplugin.ToggleStepFilters"
>
<location mnemonic=
"%mnemonic"
>
<bar path=
"org.eclipse.ui.run/emptyStepGroup"
/>
</location>
<location>
<part id=
"org.eclipse.debug.ui.DebugView"
>
<bar type=
"trim"
path=
"renderGroup"
/>
</part>
</location>
<location mnemonic=
"%mnemonic"
>
<part id=
"org.eclipse.debug.ui.DebugView"
>
<popup path=
"renderGroup"
/>
</part>
</location>
</item>
If the popup element is specified with no id and no parent part element, then it applies to any context menu registered with the workbench. This is similar to the behaviour of the old object contributions. Similarly, a top-level popup element with an id will affect any context menu registered with the given name.
<item id=
"com.mycompany.myplugin.ObjectContribution"
commandId=
"com.mycompany.myplugin.ObjectContribution"
>
<location>
<popup path=
"additions"
/>
</location>
</item>
Sometimes, you might want to control the visibility of an item. While normally it is preferrable to maintain stability in the layout of menus and tool bars, it is sometimes desirable to hide items that aren't immediately relevent. This is particularly true on context menus, where space is limited. In this case, you would define a visibleWhen
element. This element is almost identical to the activeWhen
and enabledWhen
elements defined in the handlers extension point.
<item id=
"com.mycompany.myplugin.ConvertToWatchExpression"
commandId=
"com.mycompany.myplugin.ConvertToWatchExpression"
>
<location mnemonic=
"%mnemonic"
>
<part id=
"org.eclipse.debug.ui.DebugView"
>
<popup path=
"additions"
/>
</part>
</location>
<visibleWhen>
<with variable=
"selection"
>
<iterate operator=
"and"
>
<not>
<instanceof value=
"IWatchExpression"
/>
</not>
<instanceof value=
"IExpression"
/>
</iterate>
</with>
</visibleWhen>
</item>
The most common case is simply to make something visible when its handler is enabled. This is handled with some syntactic sugar. There is a checkEnabled
attribute on the visibleWhen
element.
<item id=
"com.mycompany.myplugin.compareWithPatch"
commandId=
"com.mycompany.myplugin.compareWithPatch"
>
<location mnemonic=
"%mnemonic"
>
<part id=
"MyPart"
>
<popup path=
"additions"
/>
</part>
</location>
<visibleWhen checkEnabled=
"true"
/>
</item>
Any item associated with a command can include parameter values. If the parameter of the given identifier is not defined, this is an error. If the item does not have a command, then this is also an error.
<item id=
"com.mycompany.myplugin.RunHistory"
commandId=
"com.mycompany.myplugin.RunHistory"
>
<location>
<bar path=
"org.eclipse.ui.run"
/>
</location>
<parameter name=
"index"
value=
"1"
/>
</item>
It also possible to specify relative ordering. This is done using the order attribute on the location element. The order attribute accepts the following values: start
(put the element at the beginning of the container); end (put the element at the end of its container); after
(put the element after the sibling element whose id matches ref
); and, before
(put the element before the sibling element whose id matches ref
). Relative ordering can be applied to any type of menu element.
<item id=
"com.mycompany.myplugin.MyFirstItem"
commandId=
"com.mycompany.myplugin.MyFirstCommand"
>
<location>
<order position=
"start"
/>
<bar path=
"org.eclipse.ui.run"
/>
</location>
</item>
<item id=
"com.mycompany.myplugin.MySecondItem"
commandId=
"com.mycompany.myplugin.MySecondCommand"
>
<location>
<order position=
"after"
relativeTo=
"com.mycompany.myplugin.MyFirstItem"
/>
<bar path=
"org.eclipse.ui.run"
/>
</location>
</item>
If you require direct access to the widgets (e.g., for rendering a combo box), then you can use a widget
element. Unfortunately, this means that if a widget element becomes visible in the user interface, this will lead to plug-in loading.
<widget id=
"com.mycompany.myplugin.MyComboBoxSimple"
class=
"com.mycompany.myplugin.MyComboBox"
>
<location>
<bar type=
"trim"
path=
"myGroup"
/>
</location>
</widget>
<widget id=
"com.mycompany.myplugin.MyComboBoxParameterized1"
class=
"com.mycompany.myplugin.MyComboBox:a,b,c"
>
<location>
<bar type=
"trim"
path=
"myGroup"
/>
</location>
</widget>
<widget id=
"com.mycompany.myplugin.MyComboBoxParameterized2"
>
<class class=
"com.mycompany.myplugin.MyComboBox"
>
<parameter name=
"list"
value=
"a,b,c"
/>
<parameter name=
"selected"
value=
"c"
/>
<parameter name=
"editable"
value=
"false"
/>
</class>
<location>
<bar type=
"trim"
path=
"myGroup"
/>
</location>
</widget>
You can also use widgets to contribute into the workbench trim. The following example defines a new 'HeapStatus' widget that should be placed, by default, immediately after the status line trim (i.e. at the bottom of the workbench window). See the description fo the 'bar' element for more information on the pre-defined groups.
Note that trim 'groups' can be re-located to the other trim areas. The location information's relativeTo
will presume that the group that is referenced is in its default position when determining the new trim's location. In general it is expected that contributors of this type will create their own group to host the new widget, allowing that trim element to be relocated independently of the other trim elements. One notable exception to this is the 'status' group.
<extension point=
"org.eclipse.ui.menus"
>
<group id=
"TestTrimAPI.heapStatusGroup"
separatorsVisible=
"true"
>
<location>
<bar type=
"trim"
/>
<order position=
"after"
relativeTo=
"status"
/>
</location>
</group>
<widget class=
"HeapStatusWidget"
id=
"TestTrimAPI.HeapStatus"
>
<location>
<bar path=
"heapStatusGroup"
type=
"trim"
/>
</location>
<layout fillMajor=
"false"
fillMinor=
"true"
/>
</widget>
</extension>
IWorkbenchPartSite.registerContextMenu
methods.
Copyright (c) 2005 IBM Corporation and others.
All rights reserved. This program and the accompanying materials are made
available under the terms of the Eclipse Public License v1.0 which accompanies
this distribution, and is available at http://www.eclipse.org/legal/epl-v10.html