Menus

Identifier:
org.eclipse.ui.menus

Since:
3.3

Description:

This extension point allows the plug-in developer to add (contribute) a variety of custom additions to the eclipse framework:

It provides a common implementation for and acts as a replacement of the following (legacy) eclipse extension points:

The general strategy for this mechanism is to separate the 'location' where the contributions should be inserted from the visibility and enablement state of the element. Each contribution first defines its insertion location through a Menu 'URI', a string (loosely) formatted according to the jave.net.URI format:

"[Scheme]:[ID]?[ArgList]"

This will define the location at which the contributions will appear in the eclipse UI. Once the insertion point has been defined the rest of the contributions describe the UI elements that will be added at that location. Each element supports a 'visibleWhen' expression that determines at run time whether a particular item should appear in the menu based on the system's current state (selection, active view/editor, context...). See org.eclipse.ui.ISources for a list of currently supported variables.

Configuration Markup:

<!ELEMENT extension (group* , widget* , menuContribution*)>

<!ATTLIST extension

point CDATA #REQUIRED

id    CDATA #IMPLIED

name  CDATA #IMPLIED>


The group element is deprecated

<!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, logical groups are visible.

A group can contain menus, items and other groups.

This element is deprecated. Groups are now expressed as id'd 'separator' elements. The menu insertion URI can be used to define an insertion point either 'before' or 'after' any id'd element and placing it after the separator is the same as contributing it to the group.

See the documentation for the 'locationURI' attribute of 'menuAddition' for more details on how to define insertion points and how they relate to the menu structure.



The widget element is deprecated

<!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. NOTE: 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. When used as trim the widget will only cause the plug-in to load when it becomes visible in the UI.

NOTE: This element is deprecated. Clients should contribute a Toolbar to one of the trim areas and place a control contribution inside it. See the Trim Contribution example for details.



The layout element is deprecated

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



The location element is deprecated

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

This element is deprecated. Users of this extension point should now define the location at which their contributions should appear using the 'locationURI' specification.



The bar element is deprecated

<!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 | reference)?>

<!ATTLIST visibleWhen

checkEnabled (true | false) "false">

A core Expression that controls the visibility of the given element.



The part element is deprecated

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

NOTE: This element is deprecated. It had been used for a previous technique for adding trim elements. Instead, clients should contribute a Toolbar to one of the trim areas and place a control contribution inside it. See the Trim Contribution example for details.



<!ELEMENT parameter EMPTY>

<!ATTLIST parameter

name  IDREF #REQUIRED

value CDATA #REQUIRED>

A parameter to either an executable extension or a command -- depending on where it appears in the extension.



The order element is deprecated

<!ELEMENT order EMPTY>

<!ATTLIST order

position   (start|end|before|after)

relativeTo CDATA #IMPLIED>

NOTE: This element is deprecated in favor of using the 'locationURI' to specify the location at which contributions should be placed.

Controls the position of a widget within a particular group.



The popup element is deprecated

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

NOTE: This element is deprecated. It had been used for a previous technique for adding trim elements. Instead, clients should contribute a Toolbar to one of the trim areas and place a control contribution inside it. See the Trim Contribution example for details.



<!ELEMENT menuContribution (menu* , command* , separator* , dynamic* , toolbar* , control*)>

<!ATTLIST menuContribution

locationURI CDATA #REQUIRED

class       CDATA #IMPLIED

allPopups   (true | false) "false">

Defines an ordered set of additions to the command UI structure. The defined elements will be added into the command UI structure at the location specified by the locationURI element.

This should be the starting point for all contributions into menus, toolbars or trim, wherever they occur in the UI.



<!ELEMENT menu (visibleWhen? , (menu? | command? | separator? | dynamic?)*)?>

<!ATTLIST menu

label     CDATA #REQUIRED

id        CDATA #IMPLIED

mnemonic  CDATA #IMPLIED

icon      CDATA #IMPLIED

tooltip   CDATA #IMPLIED

commandId IDREF #IMPLIED>

Defines a new menu contribution at the given insertion point.



<!ELEMENT command (visibleWhen? , parameter*)>

<!ATTLIST command

label         CDATA #IMPLIED

commandId     IDREF #REQUIRED

id            CDATA #IMPLIED

mnemonic      CDATA #IMPLIED

icon          CDATA #IMPLIED

disabledIcon  CDATA #IMPLIED

hoverIcon     CDATA #IMPLIED

tooltip       CDATA #IMPLIED

helpContextId CDATA #IMPLIED

style         (push|radio|toggle|pulldown) "push"

mode          (FORCE_TEXT) >

Defines a new Command Contribution at the defined insertion point.



<!ELEMENT separator EMPTY>

<!ATTLIST separator

name    CDATA #REQUIRED

visible (true | false) >

Inserts a separator at the current insertion point.



<!ELEMENT toolbar (visibleWhen? , (command? | separator? | dynamic? | control?)*)?>

<!ATTLIST toolbar

id    CDATA #REQUIRED

label CDATA #IMPLIED>

Contributes a new ToolBar at the current insertion point. This element is only currently valid for CoolBarManagers, which can contain toolbars. For example, the trim location URIs specified in org.eclipse.ui.menus.MenuUtil.



<!ELEMENT control (visibleWhen?)>

<!ATTLIST control

id    CDATA #IMPLIED

class CDATA #REQUIRED>

Used to contribute controls to ToolBars in the workbench. The 'class' attribute must be a derivative of the WorkbenchWindowControlContribution base class.

NOTE: Due to platform restrictions control contributions are only supported for toolbars; Attempts to contribute controls into a menu or popup will be treated as a NO-OP.



<!ELEMENT dynamic (class? , visibleWhen?)>

<!ATTLIST dynamic

id    CDATA #REQUIRED

class CDATA #REQUIRED>

The element provides a mechanism that will call back into the defined class to provide an IContributionItem to be shown when the menu or toolbar is built. The defined class must be a derivative of the org.eclipse.jface.action.ContributionItem base class. It can also use org.eclipse.ui.action.CompoundContributionItem and provide an implementation for the abstract getContributionItems method to provide a dynamic menu item.



Examples:

A basic extension looks like this.


   <extension
         id="add.item"
         point="org.eclipse.ui.menus">
      <menuContribution
         locationURI="menu:someorg.somemenu.id?after=additions">
         <command
               commandId="someorg.someid.someCommand"
               icon="icons/anything.png"
               id="someorg.someid.BasicCmdItem"
               label="Simple Item"
               mnemonic="S">
         </command>
      </menuContribution>
   </extension>

This is the simplest example; adding a command contribution after an existing menu's additions group.

API Information:

It is preferred that menu contributions be added in the plugin.xml. Plugins can programmatically add their own menu contributions using org.eclipse.ui.menus.IMenuService and org.eclipse.ui.menus.AbstractContributionFactory, but should be sure to remove them if the plugin is unloaded. The IMenuService can be retrieved through any of the IServiceLocators, the workbench, the workbench window, or the part site.

See org.eclipse.ui.commands to define a command and org.eclipse.ui.handlers to define an implementation for the command.

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


Copyright (c) 2005,2007 IBM Corporation and others.
This program and the accompanying materials are made available under the terms of the Eclipse Public License 2.0 which accompanies this distribution, and is available at https://www.eclipse.org/legal/epl-v20.html/ SPDX-License-Identifier: EPL-2.0