Editor Menus, Toolbars and Actions

This extension point is deprecated

Identifier:
org.eclipse.ui.editorActions

Description:

WARNING: This extension point is DEPRECATED.
Do not use this extension point, it will be removed in future versions of this product. Instead, use the extension point org.eclipse.ui.commands

This extension point is used to add actions to the menu and toolbar for editors registered by other plug-ins.

You can now use org.eclipse.ui.menus to place commands in menus and toolbars as well.

The initial contribution set for an editor is defined by another extension point (org.eclipse.ui.editors). One set of actions is created and shared by all instances of the same editor type. When invoked, these action act upon the active editor. This extension point follows the same pattern. Each action extension is created and shared by all instances of the same editor type. The action class is required to implement org.eclipse.ui.IEditorActionDelegate. The active editor is passed to the delegate by invoking IEditorActionDelegate.setActiveEditor.

Configuration Markup:

<!ELEMENT extension (editorContribution+)>

<!ATTLIST extension

point CDATA #REQUIRED

id    CDATA #IMPLIED

name  CDATA #IMPLIED>


The editorContribution element is deprecated

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

<!ATTLIST editorContribution

id       CDATA #REQUIRED

targetID IDREF #REQUIRED>

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



The action element is deprecated

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

<!ATTLIST action

id            CDATA #REQUIRED

label         CDATA #REQUIRED

accelerator   CDATA #IMPLIED

definitionId  IDREF #IMPLIED

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

actionID      CDATA #IMPLIED

mode          (FORCE_TEXT) >

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



The parameter element is deprecated

<!ELEMENT parameter EMPTY>

<!ATTLIST parameter

name  CDATA #REQUIRED

value CDATA #REQUIRED>

A parameter element to be used within an IExecutableExtension element. This will be passed as initialization data to the instantiated class.



The class element is deprecated

<!ELEMENT class (parameter*)>

<!ATTLIST class

class CDATA #IMPLIED>

The element version of the class attribute. This is used when the class implements org.eclipse.core.runtime.IExecutableExtension and there is parameterized data that you wish used in its initialization.



Examples:
The following is an example of an editor action extension:


   <extension point="org.eclipse.ui.editorActions"> 
      <editorContribution 
         id="com.xyz.xyzContribution" 
         targetID="com.ibm.XMLEditor"> 
         <menu
            id="XYZ"
            label="&amp;XYZ Menu"> 
            <separator name="group1"/> 
         </menu> 
         <action 
            id="com.xyz.runXYZ" 
            label="&amp;Run XYZ Tool" 
            menubarPath="XYZ/group1" 
            toolbarPath="Normal/additions"
            style="toggle"
            state="true" 
            icon="icons/runXYZ.png"
            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> 
      </editorContribution> 
   </extension> 

In the example above, the specified action will appear as a check box item in the new top-level menu named "XYZ Menu", and as a toggle button in the toolbar. The action is enabled if the selection contains only Java file resources.

The following is an other example of an editor action extension:


   <extension point="org.eclipse.ui.editorActions"> 
      <editorContribution 
         id="com.xyz.xyz2Contribution" 
         targetID="com.ibm.XMLEditor"> 
         <menu 
            id="XYZ2" 
            label="&amp;XYZ2 Menu" 
            path="edit/additions"> 
            <separator name="group1"/> 
         </menu> 
         <action 
            id="com.xyz.runXYZ2" 
            label="&amp;Run XYZ2 Tool" 
            menubarPath="edit/XYZ2/group1"
            style="push"
            icon="icons/runXYZ2.png"
            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 in the sub-menu named "XYZ2 Menu" in the top level "Edit" menu. 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.IEditorActionDelegate. This class is loaded as late as possible to avoid loading the entire plug-in before it is really needed. The method setActiveEditor will be called each time an editor of the specified type is activated. Only one set of actions and menus will be created for all instances of the specified editor type, regardless of the number of editor instances currently opened in the Workbench.

This extension point can be used to contribute actions into menus previously created by the target editor. In addition, menus and actions can be contributed to the Workbench window. The identifiers for actions and major groups within the Workbench window are defined in org.eclipse.ui.IWorkbenchActionConstants. These should be used as a reference point for the addition of new actions. Top level menus are created by using the following values for the path attribute:

Omitting the path attribute will result in adding the new menu into the additions menu bar group.

Actions and menus added into these paths will only be shown while the associated editor is active. When the editor is closed, menus and actions will be removed.

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:
The Workbench provides a built-in "Default Text Editor". Plug-ins can contribute into this default editor or editors provided by other plug-ins.


Copyright (c) 2000, 2019 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