Menus

Identifier:

Since:

Description:

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, tool bar or status line 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.

Configuration Markup:

<!ELEMENT extension (item* , menu* , group* , widget* , actionSet*)>

<!ATTLIST extension

point CDATA #REQUIRED

id    CDATA #IMPLIED

name  CDATA #IMPLIED>

• point - org.eclipse.ui.menus
• id - An optional identifier of the extension instance.
• name - An optional name of the extension instance.

<!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 tool item, depending on where it is placed. It could also be something in the status line. The text and image associated with the item will be drawn from the command.

• id - A unique identifier for this item. It is recommended that the identifier be prefixed by the plug-in name, to guarantee uniqueness. For example, an item contributed by org.eclipse.ui might be called org.eclipse.ui.item1.
• commandId - The identifier of the command that should be executed when this item is triggered by the user. Commands are defined in the commands extension point.
• menuId - Attaches a drop-down menu to a tool item. If this item appears somewhere other than a tool bar, then a warning will be printed to the log on start-up.

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

• id - A unique identifier for this menu. It is recommended that the identifier be prefixed by the plug-in name, to guarantee uniqueness. For example, a menu contributed by org.eclipse.ui might be called org.eclipse.ui.menu1.
• label - The human-readable text to associate with this menu.

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

• id - A unique identifier for this group. It is recommended that the identifier be prefixed by the plug-in name, to guarantee uniqueness. For example, a group contributed by org.eclipse.ui might be called org.eclipse.ui.group1.
• separatorsVisible - Whether separators should be drawn around the group. The workbench will take care of deciding whether a separator needs to be drawn at the top or bottom -- accounting for the top and bottom of the menu and duplicate separators. By default, separators are visible.

<!ELEMENT widget (location* , class? , visibleWhen?)>

<!ATTLIST widget

id    CDATA #REQUIRED

class CDATA #IMPLIED>

A menu elements 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.

• id - A unique identifier for this widget. It is recommended that the identifier be prefixed by the plug-in name, to guarantee uniqueness. For example, a widget contributed by org.eclipse.ui might be called org.eclipse.ui.widget1.
• class - This class is loaded to fill the appropriate spot in the menu, tool bar or status line when it shows. This class must implement IWidget. It is possible to use the class element instead.

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

• mnemonic - The mnemonic that should be associated with this element in the given location. A mnemonic should be a single character.
• imageStyle - The image style to associate with this location. It is possible for commands to have different styles of images associated with them. For example, a different icon could be selected for the tool bar and for the menu. This is especially important for developers using drop-down tool items in the tool bar, as they may wish to display an icon more appropriate for the drop-down.

<!ELEMENT bar EMPTY>

<!ATTLIST bar

type (menu|trim)

path CDATA #IMPLIED>

A leaf element within a location. This can be the menu bar, the tool bar or the status line. If unqualified, this indicates the top-level menu bar, tool bar or status line. If this is qualified with a part element, then this indicates that part's menu, tool bar or status line.

• type -

  What type of bar to contribute to. This can be 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 item's command will generally require an icon, and widget elements make more sense.

  Within the trim, the workbench defines five general groups which correspond to various positions around the window. By positioning the trim contribution within or with respect to this groups, the position is inferred by the workbench. The five trim group ids are: coolbar, perspective, status, leadingEdge and trailingEdge.

• path - The path from the root of the bar, including menus and groups. This path uses '/' as a separator character.

<!ELEMENT class (parameter*)>

<!ATTLIST class

class CDATA #REQUIRED>

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

• class - The class to load as an 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.

• checkEnabled - If this attribute is set to 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.

<!ELEMENT actionSet (reference+)>

<!ATTLIST actionSet

id          CDATA #REQUIRED

label       CDATA #REQUIRED

description CDATA #IMPLIED

visible     CDATA "false">

A named group of elements. The workbench allows the user to view action sets, and disable or enable them as desired. It is also possible for certain action sets to be associated with particular parts or perspectives.

An action set has a name and a unique identifier. It is also possible to specify whether the action set should be visible by default. Within the action set is simply a list of references to menus, groups, items and widgets that have been declared elsewhere.

• id - A unique identifier for this action set. It is recommended that the identifier be prefixed by the plug-in name, to guarantee uniqueness. For example, an action set contributed by org.eclipse.ui might be called org.eclipse.ui.actionSet1.
• label - The human-readable text to associate with this action set. This text will appear in the "Customize Perspective" dialog.
• description - A longer human-readable description of the action set.
• visible - Whether the action set should be visible by default. If an action set is not visible, then the associated elements will not be visible. If an action set is visible, then the visibleWhen criteria for the associated elements will be evaluated as normal. By default, action sets are not visible.

<!ELEMENT part (popup | part)>

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

• id - The identifier of the view or editor.
• class - The class of the part. This can be a superclass, interface or superinterface of the part, and it will still match.

<!ELEMENT reference EMPTY>

<!ATTLIST reference

id   CDATA #REQUIRED

type (menu|group|item|widget) >

A reference to an already existing element. This is used for action sets.

• id - The identifier of the element to which this reference refers.
• type - The type of element to which this reference refers. This is only required if there are elements of different types with the same id.

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

• name - The name is either the name of the parameter to pass to the executable extension, or the identifier of the parameter for the command.
• value - The value to pass for this parameter.

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

• position -

  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:

  • The Eclipse version is the same.
  • The list of elements is the same (i.e., no dynamic elements, no plug-ins added or removed).
• relativeTo - The identifier of the element to which this position is relative. This value is required if the 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.

• id - The identifier of the popup menu. If none is specified, then it will appear in all popup menus.
• path - The path within the popup menu to place the element. If not specified, then this is added to the "additions" group.

Examples:

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>
  
<menubar />
 
</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>
  
<menubar path=
"org.eclipse.ui.run"
 />
 
</location>
</group>
<group
 id=
"com.mycompany.myplugin.stepIntoGroup"

 separatorsVisible=
"false"
 >
 
<location>
  
<menubar 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"
>
  
<menubar path=
"org.eclipse.ui.run/emptyStepGroup"
 />
 
</location>
 
<location>
  
<part id=
"org.eclipse.debug.ui.DebugView"
>
   
<toolbar 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>
  
<menubar 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"
 />
  
<menubar 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"
 />
  
<menubar 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>
  
<toolbar path=
"myGroup"
>
 
</location>
</widget>
<widget
 id=
"com.mycompany.myplugin.MyComboBoxParameterized1"

 class=
"com.mycompany.myplugin.MyComboBox:a,b,c"
>
 
<location>
  
<toolbar 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>
  
<toolbar pathd=
"myGroup"
 />
 
</location>
</widget>

It is possible to define action sets, or groups of elements with a name. The workbench allows the user to view acton sets, and disable or enable them as desired. It is also possible for certain action sets to be associated with particular parts or perspectives.

<actionSet
 label=
"%ProfileActionSet.label"

 visible=
"false"

 id=
"org.eclipse.debug.ui.profileActionSet"
>
 
<reference id=
"ProfileDropDownAction"
 type=
"menu"
/>
 
<reference id=
"ProfileWithConfigurationAction"
 type=
"menu"
/>
 
<reference id=
"ProfileHistoryMenuAction"
 type=
"menu"
 />
 
<reference id=
"OpenProfileConfigurations"
 type=
"item"
/>
  
<reference id=
"ProfileLast"
 type=
"item"
/>
</actionSet>

API Information:

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