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.
You can now use
org.eclipse.ui.menus to place commands in menus and toolbars as well.
An action's enablement and/or visibility can be defined using the elements enablement and visibility respectively, if the extension point supports it. 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
>
-
point - a fully qualified identifier of the target extension point
-
id - an optional identifier of the extension instance
-
name - an optional name of the extension instance
<!ELEMENT viewContribution (
menu* ,
action*)>
<!ATTLIST viewContribution
id CDATA #REQUIRED
targetID IDREF #REQUIRED
>
This element is used to define a group of view actions and/or menus.
-
id - a unique identifier used to reference this contribution.
-
targetID - a unique identifier of a registered view that is the target of this contribution.
<!ELEMENT action ((
selection* |
enablement?) ,
class?)>
<!ATTLIST action
id CDATA #REQUIRED
label CDATA #REQUIRED
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|pulldown) "push"
state (true | false)
class CDATA #REQUIRED
enablesFor CDATA #IMPLIED
mode (FORCE_TEXT)
>
This element defines an action that the user can invoke in the UI.
-
id - a unique identifier used as a reference for this action.
-
label - a translatable name used either as the menu item text or toolbar button label. The name can include mnenomic information.
-
definitionId - Specifies the command that this action will handle. By specifying and action, the key binding service can assign a key sequence to this action. See the extension point
org.eclipse.ui.commands for more information.
-
menubarPath - a slash-delimited path ('/') used to specify the location of this action in the pulldown menu. Each token in the path, except the last one, must represent a valid identifier of an existing menu in the hierarchy. The last token represents the named group into which this action will be added. If the path is omitted, this action will not appear in the pulldown menu.
-
toolbarPath - a named group within the local toolbar of the target view. If the group does not exist, it will be created. If omitted, the action will not appear in the local toolbar.
-
icon - a relative path of an icon used to visually represent the action in its context.
If omitted and the action appears in the toolbar, the Workbench will use a placeholder icon. The path is relative to the location of the plugin.xml file of the contributing plug-in. The icon will appear in the toolbar but not in the pulldown menu.
-
disabledIcon - a relative path of an icon used to visually represent the action in its context when the action is disabled. If omitted, the normal icon will simply appear greyed out. The path is relative to the location of the plugin.xml file of the contributing plug-in. The disabled icon will appear in the toolbar but not in the pulldown menu.
-
hoverIcon - a relative path of an icon used to visually represent the action in its context when the mouse pointer is over the action. If omitted, the normal icon will be used. The path is relative to the location of the plugin.xml file of the contributing plug-in.
-
tooltip - a translatable text representing the action's tool tip. Only used if the action appears in the toolbar.
-
helpContextId - a unique identifier indicating the help context for this action. On some platforms, if the action appears as a menu item, then pressing the appropriate help key while the menu item is highlighted will display help. Not all platforms support this behaviour.
-
style - an optional attribute to define the user interface style type for the action. If defined, the attribute value will be one of the following:
|
push
|
- as a regular menu item or tool item. |
|
radio
|
- as a radio style menu item or tool item. Actions with the radio style within the same menu or toolbar group behave as a radio set. The initial value is specified by the state attribute. |
|
toggle
|
- as a checked style menu item or as a toggle tool item. The initial value is specified by the state attribute. |
|
pulldown
|
- as a pulldown tool item. The initial value is specified by the state attribute. |
-
state - an optional attribute indicating the initial state (either true or false), used when the style attribute has the value radio or toggle.
-
class - name of the fully qualified class that implements org.eclipse.ui.IViewActionDelegate.
-
enablesFor - a value indicating the selection count which must be met to enable the action.
If this attribute is specified and the condition is met, the action is enabled.
If the condition is not met, the action is disabled.
If no attribute is specified, the action is enabled for any number of items selected.
The following attribute formats are supported:
|
!
|
- 0 items selected |
|
?
|
- 0 or 1 items selected |
|
+
|
- 1 or more items selected |
|
multiple, 2+
|
- 2 or more items selected |
|
n
|
- a precise number of items selected.a precise number of items selected.
For example: enablesFor=" 4" enables the action only when 4
items are selected |
|
*
|
- any number of items selected |
-
mode - For actions appearing in a toolbar,
FORCE_TEXT
will show text even if there is an icon. See ActionContribuitonItem.
<!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.
-
name - the parameter name
-
value - the parameter value
<!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.
-
class - A class that implements
org.eclipse.ui.IViewActionDelegate
. It may also implement org.eclipse.core.runtime.IExecutableExtension
.
<!ELEMENT menu (
separator* ,
groupMarker*)>
<!ATTLIST menu
id CDATA #REQUIRED
label CDATA #REQUIRED
path CDATA #IMPLIED
icon CDATA #IMPLIED
>
This element is used to defined a new menu.
-
id - a unique identifier that can be used to reference this menu.
-
label - a translatable name used by the Workbench for this new menu. The name should include mnemonic information.
-
path - the location of the new menu starting from the root of the menu. Each token in the path must refer to an existing menu, except the last token which should represent a named group in the last menu in the path. If omitted, the new menu will be added to the additions named group of the menu.
-
icon - a relative path of an icon used to visually represent the menu in its context.
The path is relative to the location of the plugin.xml file of the contributing plug-in.
<!ELEMENT separator EMPTY>
<!ATTLIST separator
name CDATA #REQUIRED
>
This element is used to create a menu separator in the new menu.
-
name - the name of the menu separator. This name can later be referenced as the last token in a menu path. Therefore, a separator also serves as named group into which actions and menus can be added.
<!ELEMENT groupMarker EMPTY>
<!ATTLIST groupMarker
name CDATA #REQUIRED
>
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.
-
name - the name of the group marker. This name can later be referenced as the last token in the menu path. It serves as named group into which actions and menus can be added.
<!ELEMENT selection EMPTY>
<!ATTLIST selection
class CDATA #REQUIRED
name CDATA #IMPLIED
>
This element is used to help determine the action enablement based on the current selection. Ignored if the enablement element is specified.
-
class - a fully qualified name of the class or interface that each object in the selection must implement in order to enable the action.
-
name - an optional wild card filter for the name that can be applied to all objects in the selection. If specified and the match fails, the action will be disabled.
<!ELEMENT enablement (
and |
or |
not |
objectClass |
objectState |
pluginState |
systemProperty)>
This element is used to define the enablement for the extension.
<!ELEMENT visibility (
and |
or |
not |
objectClass |
objectState |
pluginState |
systemProperty)>
This element is used to define the visibility for the extension.
<!ELEMENT and (
and |
or |
not |
objectClass |
objectState |
pluginState |
systemProperty)>
This element represent a boolean AND operation on the result of evaluating its 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 its 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 its sub-element expressions.
<!ELEMENT objectClass EMPTY>
<!ATTLIST objectClass
name CDATA #REQUIRED
>
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.
-
name - a fully qualified name of a class or interface. The expression is evaluated as true only if all objects within the selection implement this class or interface.
<!ELEMENT objectState EMPTY>
<!ATTLIST objectState
name CDATA #REQUIRED
value CDATA #REQUIRED
>
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.
-
name - the name of an object's attribute. Acceptable names reflect the object type, and should be publicly declared by the plug-in where the object type is declared.
@see IResourceActionFilter for a list of the supported constants
-
value - the required value of the object's attribute. The acceptable values for the object's attribute should be publicly declared.
<!ELEMENT pluginState EMPTY>
<!ATTLIST pluginState
id CDATA #REQUIRED
value (installed|activated) "installed"
>
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 (equivalent to the OSGi concept of "resolved") or activated (equivalent to the OSGi concept of "active").
-
id - the identifier of a plug-in which may or may not exist in the plug-in registry.
-
value - the required state of the plug-in. The state of the plug-in may be one of the following: installed (equivalent to the OSGi concept of "resolved") or activated (equivalent to the OSGi concept of "active").
<!ELEMENT systemProperty EMPTY>
<!ATTLIST systemProperty
name CDATA #REQUIRED
value CDATA #REQUIRED
>
This element is used to evaluate the state of some system property. The property value is retrieved from the java.lang.System.
-
name - the name of the system property.
-
value - the required value of the system property.
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=
"&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=
"&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>
</viewContribution>
</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.
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) 2002, 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 https://www.eclipse.org/legal/epl-v10.html