Menus

org.eclipse.ui.menus

3.2

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.



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



<!ELEMENT group (location*)>

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



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



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



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



<!ELEMENT class (parameter*)>

<!ATTLIST class

class CDATA #REQUIRED>

A class element supporting the executable extension parsing syntax for both widget and dynamic elements.



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



<!ELEMENT part (popup | bar)>

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



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

To register a context menu, use the IWorkbenchPartSite.registerContextMenu methods.