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.



<!ELEMENT enablement (not , and , or , instanceof , test , systemTest , equals , count , with , resolve , adapt , iterate , reference)*>

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

This element represents a NOT operation on the result of evaluating its sub-element expression.



<!ELEMENT and (not , and , or , instanceof , test , systemTest , equals , count , with , resolve , adapt , iterate , reference)*>

This element represents an AND operation on the result of evaluating all its sub-elements expressions.



<!ELEMENT or (not , and , or , instanceof , test , systemTest , equals , count , with , resolve , adapt , iterate , reference)*>

This element represent an OR operation on the result of evaluating all its 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

forcePluginActivation (true | false)

>

This element is used to evaluate the property state of the object in focus. The set of testable properties can be extended using the org.eclipse.core.expressions.propertyTesters extension point. The test expression returns EvaluationResult.NOT_LOADED if the property tester doing the actual testing isn't loaded yet and the attribute forcePluginActivation is set to false. If forcePluginActivation is set to true and the evaluation context used to evaluate this expression support plug-in activation then evaluating the property will result in activating the plug-in defining the tester.



<!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 , reference)*>

<!ATTLIST with

variable CDATA #REQUIRED

>

This element changes the object to be inspected for all its child element to the object referenced by the given variable. If the variable can not be resolved then the expression will throw an 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 , reference)*>

<!ATTLIST resolve

variable CDATA #REQUIRED

args     CDATA #IMPLIED

>

This element changes the object to be inspected for all its child element to the object referenced by the given variable. If the variable can not be resolved then the expression will throw an ExpressionException when evaluating it. The children of a resolve expression are combined using the "and" operator.



<!ELEMENT adapt (not , and , or , instanceof , test , systemTest , equals , count , with , resolve , adapt , iterate , reference)*>

<!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 EvaluationResult.NOT_LOADED if either the adapter or the type referenced isn't loaded yet. It throws an 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 , reference)*>

<!ATTLIST iterate

operator (or|and)

ifEmpty  (true | false)

>

This element is used to iterate over a variable that is of type java.util.Collection, or a variable that adapts to org.eclipse.core.expressions.IIterable. If the object in focus is not one of the above then a CoreException with an ExpressionStatus will be thrown while evaluating the expression. The child expressions of an iterate expression are combined using the "and" operator.



<!ELEMENT reference EMPTY>

<!ATTLIST reference

definitionId IDREF #REQUIRED

>

This element is used to reference an expression from the org.eclipse.core.expressions.definitions extension point. The expression definition will be evaluated within the current expression element using the current evaluation context.



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.gif"
               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.
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