View Menus, Toolbars and Actions
Identifier: org.eclipse.ui.viewActions
Description: This extension point is used to add actions
to the 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
area. 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.
Configuration Markup:
<!ELEMENT viewContribution (menu | action)*>
<!ATTLIST viewContribution
id
CDATA #REQUIRED
targetID CDATA #REQUIRED
>
id - a unique identifier that can be used to reference this contribution
targetID - the unique identifier of the view (as specified in the registry) into
which the contribution is made
<!ELEMENT menu (separator)+>
<!ATTLIST menu
id
CDATA #REQUIRED
label
CDATA #REQUIRED
path
CDATA #IMPLIED
>
-
id - a unique identifier that can be used to reference this menu
-
label - the text label of the new menu. The label should include
mnemonic information.
-
path - the location of the menu starting from the pulldown, with
the last token representing the named group. If omitted, the menu will
be added at the end of the pulldown.
<!ELEMENT separator EMPTY>
<!ATTLIST separator
name
CDATA #REQUIRED
>
name - name of the separator that can later be referenced as the
last token in the action path. Therefore, separators serve as named groups
into which actions can be added.
<!ELEMENT action (selection)*>
<!ATTLIST action
id
NMTOKEN #REQUIRED
label
CDATA #REQUIRED
menubarPath
CDATA #IMPLIED
toolbarPath
CDATA #IMPLIED
icon
CDATA #IMPLIED
tooltip
CDATA #IMPLIED
helpContextId
CDATA #IMPLIED
state
(true | false) #IMPLIED
class
CDATA #REQUIRED
enablesFor
CDATA #IMPLIED
>
-
id - a unique identifier that can be used as a reference for this
action.
-
label - a translatable name that is used in various ways, depending
on the context. In menus, it is used as the menu text. In toolbars, it
is used as the button label. The label can contain JFace-encoded mnemonic
and accelerator information (see example).
-
menubarPath - a slash-delimited path ('/') that is used to specify
the location of the action in the pulldown menu. Each token in the path,
except the last one, represents an existing menu in the hierarchy. The
last token represents the named separator group into which the action will
be added. If the path is omitted, the action will not appear in the pulldown.
-
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 for an icon that will be used to visually
represent the action in its context. If omitted and the action should appear
in the local toolbar, the workbench will use a place holder icon. The path
is relative to the location of the plugin.xml file of the contributing
plug-in.
-
state - an optional attribute indicating that the action should
be of a toggle type. When added to a menu, it will manifest itself as a
check box item. When added to a toolbar, it will become a toggle button.
If defined, the attribute value will be used as the initial state (either
true
or false).
-
tooltip - used if the action is to appear in the local toolbar.
Otherwise, it is ignored.
-
helpContextId - a unique identifier indicating the help context
id for this action. If the action appears as a menu item, then pressing
F1 while the menu item is highlighted will display help for the given context
id.
-
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. Example: 4.
* - any number of items selected
<!ELEMENT selection EMPTY>
<!ATTLIST selection
class
CDATA #REQUIRED
name
CDATA #IMPLIED
>
-
class - a fully qualified name of the class or interface that each
object in the selection must subclass or implement in order to enable the
action.
-
name - a wild card filter that can optionally be applied to objects
in the selection. If this filter is specified and the match fails, the
action will be disabled.
The enablement criteria for an action extension are initially defined by
enablesFor
and selection. 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
and accelerators using the following rules:
-
Mnemonics are specified using the ampersand ('&') character in front
of a mnemonic character in the translatable text. Since ampersand is not
allowed in XML strings, use & character entity.
-
Optional accelerators are specified at the and of the name string, using
@
followed by a series of modifiers and the final accelerator character (for
example, &Save@Ctrl+S). Modified can be chained using
the '+' sign as the delimiter (as in @Ctrl+Shift+S).
Examples:
The following is an example of a view actions extension point (note
the subelements and the way attributes are used):
<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/XYZ"
icon="icons/runXYZ.gif"
tooltip="Run XYZ Tool"
helpContextId="com.xyz.run_action_context"
class="com.xyz.actions.RunXYZ"
enablesFor="1"/>
<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, each object in
this selection must implement the specified interface (IFile)
and must be a Java file. Multiple selection elements can be specified,
meaning 'one of'.
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 interface is loaded as late as possible to avoid loading the entire
plug-in before it is really needed. It extends org.eclipse.ui.IActionDelegate
and adds an additional method that allows the delegate to initialize with
the view instance it is contributing into.
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.
It is helpful to publish the action identifiers for a view within a public
interface. For example, the actions and major groups for the workbench
window are defined in org.eclipse.ui.IWorkbenchActionConstants.