View Menus,Toolbars and Actions

Identifier: org.eclipse.ui.viewActions

Description: This extension point is used to add actions to the pulldown menu and toolbar for views registered by other plug-ins. Each view has a local pulldown menu normally activated by clicking on the top right triangle button. Other plug-ins can contribute submenus and actions to this menu. Plug-ins may also contribute actions to a view toolbar. View owners are first given a chance to populate these areas. Optional additions by other plug-ins are appended.

An action's enablement and/or visibility can be defined using the elements enablement and visibility respectively. These two elements contain a boolean expression that is evaluated to determine the enablement and/or visibility.

The syntax is the same for the enablement and visibility elements. Both contain only one boolean expression sub-element. In the simplest case, this will be an objectClass, objectState, pluginState, or systemProperty element. In the more complex case, the and, or, and not elements can be combined to form a boolean expression. Both the and, and or elements must contain 2 sub-elements. The not element must contain only 1 sub-element.

Configuration Markup:

   <!ELEMENT extension (viewContribution+)>

   <!ATTLIST extension
     point CDATA #REQUIRED
     id    CDATA #IMPLIED
     name  CDATA #IMPLIED
   >

   <!ELEMENT viewContribution (menu* , action*)>

   This element is used to define a group of view actions and/or menus.

   <!ATTLIST viewContribution
     id       CDATA #REQUIRED
     targetID CDATA #REQUIRED
   >

   <!ELEMENT action (selection* | enablement?)>

   This element defines an action that the user can invoke in the UI.

   <!ATTLIST action
     id            CDATA #REQUIRED
     label         CDATA #REQUIRED
     menubarPath   CDATA #IMPLIED
     toolbarPath   CDATA #IMPLIED
     icon          CDATA #IMPLIED
     disabledIcon  CDATA #IMPLIED
     hoverIcon     CDATA #IMPLIED
     tooltip       CDATA #IMPLIED
     helpContextId CDATA #IMPLIED
     style         (push|radio|toggle) "push"
     state         (true | false)
     class         CDATA #REQUIRED
     enablesFor    CDATA #IMPLIED
   >

   <!ELEMENT menu (separator+ , groupMarker*)>

   This element is used to defined a new menu.

   <!ATTLIST menu
     id    CDATA #REQUIRED
     label CDATA #REQUIRED
     path  CDATA #IMPLIED
   >

   <!ELEMENT separator EMPTY>

   This element is used to create a menu separator in the new menu.

   <!ATTLIST separator
     name CDATA #REQUIRED
   >

   <!ELEMENT groupMarker EMPTY>

   This element is used to create a named group in the new menu. It has no visual representation in the new menu, unlike the separator element.

   <!ATTLIST groupMarker
     name CDATA #REQUIRED
   >

   <!ELEMENT selection EMPTY>

   This element is used to help determine the action enablement based on the current selection. Ignored if the enablement element is specified.

   <!ATTLIST selection
     class CDATA #REQUIRED
     name  CDATA #IMPLIED
   >

   <!ELEMENT enablement (and | or | not | objectClass | objectState | pluginState | systemProperty)>

   This element is used to define the enablement for the action.

   <!ELEMENT visibility (and | or | not | objectClass | objectState | pluginState | systemProperty)>

   This element is used to define the visibility for the action.

   <!ELEMENT and (and | or | not | objectClass | objectState | pluginState | systemProperty)>

   This element represent a boolean AND operation on the result of evaluating it's two sub-element expressions.

   <!ELEMENT or (and | or | not | objectClass | objectState | pluginState | systemProperty)>

   This element represent a boolean OR operation on the result of evaluating it's two sub-element expressions.

   <!ELEMENT not (and | or | not | objectClass | objectState | pluginState | systemProperty)>

   This element represent a boolean NOT operation on the result of evaluating it's sub-element expressions.

   <!ELEMENT objectClass EMPTY>

   This element is used to evaluate the class or interface of each object in the current selection. If each object in the selection implements the specified class or interface, the expression is evaluated as true.

   <!ATTLIST objectClass
     name CDATA #REQUIRED
   >

   <!ELEMENT objectState EMPTY>

   This element is used to evaluate the attribute state of each object in the current selection. If each object in the selection has the specified attribute state, the expression is evaluated as true. To evaluate this type of expression, each object in the selection must implement, or adapt to, org.eclipse.ui.IActionFilter interface.

   <!ATTLIST objectState
     name  CDATA #REQUIRED
     value CDATA #REQUIRED
   >

   <!ELEMENT pluginState EMPTY>

   This element is used to evaluate the state of a plug-in. The state of the plug-in may be one of the following: installed or activated.

   <!ATTLIST pluginState
     id    CDATA #REQUIRED
     value (installed|activated) "installed"
   >

   <!ELEMENT systemProperty EMPTY>

   This element is used to evaluate the state of some system property. The property value is retrieved from the java.lang.System.

   <!ATTLIST systemProperty
     name  CDATA #REQUIRED
     value CDATA #REQUIRED
   >
Examples: The following is an example of a view action extension:

   <extension point="org.eclipse.ui.viewActions"> 
      <viewContribution 
         id="com.xyz.xyzViewC1" 
         targetID="org.eclipse.ui.views.navigator.ResourceNavigator"> 
         <menu
            id="com.xyz.xyzMenu" 
            label="XYZ Menu" 
            path="additions"> 
            <separator name="group1"/> 
         </menu> 
         <action
            id="com.xyz.runXYZ" 
            label="&amp;Run XYZ Tool" 
            menubarPath="com.xyz.xyzMenu/group1" 
            toolbarPath="Normal/additions"
            style="toggle"
            state="true" 
            icon="icons/runXYZ.gif" 
            tooltip="Run XYZ Tool" 
            helpContextId="com.xyz.run_action_context" 
            class="com.xyz.actions.RunXYZ"> 
            <selection class="org.eclipse.core.resources.IFile" name="*.java"/> 
         </action> 
     </viewContribution> 
   </extension> 

In the example above, the specified action will only enable for a single selection (enablesFor attribute). In addition, the object in the selection must be a Java file resource.

The following is an other example of a view action extension:

   <extension point="org.eclipse.ui.viewActions"> 
      <viewContribution 
         id="com.xyz.xyzViewC1" 
         targetID="org.eclipse.ui.views.navigator.ResourceNavigator"> 
         <menu
            id="com.xyz.xyzMenu" 
            label="XYZ Menu" 
            path="additions"> 
            <separator name="group1"/> 
         </menu> 
         <action 
            id="com.xyz.runXYZ2" 
            label="&amp;Run XYZ2 Tool" 
            menubarPath="com.xyz.xyzMenu/group1"
            style="push"
            icon="icons/runXYZ2.gif" 
            tooltip="Run XYZ2 Tool" 
            helpContextId="com.xyz.run_action_context2" 
            class="com.xyz.actions.RunXYZ2"> 
            <enablement>
               <and>
                  <objectClass name="org.eclipse.core.resources.IFile"/>
                  <not>
                     <objectState name="extension" value="java"/>
                  </not>
               </and>
            </enablement>
         </action> 
      </editorContribution> 
   </extension> 

In the example above, the specified action will appear as a menu item. The action is enabled if the selection contains no Java file resources.

API Information: The value of the class attribute must be a fully qualified name of a Java class that implements org.eclipse.ui.IViewActionDelegate. This class is loaded as late as possible to avoid loading the entire plug-in before it is really needed.

The interface org.eclipse.ui.IViewActionDelegate extends org.eclipse.ui.IActionDelegate and adds an additional method that allows the delegate to initialize with the view instance it is contributing into.

This extension point can be used to contribute actions into menus previously created by the target view. Omitting the menu path attribute will result in adding the new menu or action at the end of the pulldown menu.

The enablement criteria for an action extension is initially defined by enablesFor, and also either selection or enablement. However, once the action delegate has been instantiated, it may control the action enable state directly within its selectionChanged method.

Action and menu labels may contain special characters that encode mnemonics using the following rules:

  1. Mnemonics are specified using the ampersand ('&') character in front of a selected character in the translated text. Since ampersand is not allowed in XML strings, use &amp; character entity.
If two or more actions are contributed to a menu or toolbar by a single extension the actions will appear in the reverse order of how they are listed in the plugin.xml file. This behavior is admittedly unintuitive. However, it was discovered after the Eclipse Platform API was frozen. Changing the behavior now would break every plug-in which relies upon the existing behavior.

The selection and enablement elements are mutually exclusive. The enablement element can replace the selection element using the sub-elements objectClass and objectState. For example, the following:

 <selection
  class="org.eclipse.core.resources.IFile"
  name="*.java">
 </selection>
can be expressed using:
 <enablement>
  <and>
   <objectClass name="org.eclipse.core.resources.IFile"/>
   <objectState name="extension" value="java"/>
  </and>
 </enablement>

Supplied Implementation: Each view normally comes with a number of standard items on the pulldown menu and local toolbar. Additions from other plug-ins will be appended to the standard complement.

Copyright (c) 2000, 2003 IBM Corporation and others. All rights reserved. This program and the accompanying materials are made available under the terms of the Common Public License v1.0 which accompanies this distribution, and is available at http://www.eclipse.org/legal/cpl-v10.html