Description: This extension point is used to add new actions to pop-up menus owned by other plug-ins. Action contribution may be made against a specific object type (objectContribution) or against a specific popup menu. When registered for an object type, a contribution will appear in all viewers where objects of the specified type are selected. In contrast, registration against a popup menu will only appear in the specified menu, regardless of the selection.
When selection is heterogeneous, contribution will be applied if registered against a common type of the selection, if possible. If a direct match is not possible, matching against superclasses and superinterfaces will be attempted.
Selection can be further constrained through the use of a name filter. If used, all the objects in the selection must match the filter in order to apply the contribution.
Individual actions in an object contribution can use attribute enablesFor to specify if it should only apply for a single, multiple, or any other selection type.
If these filtering mechanisms are inadequate an action contribution may use the filter mechanism. In this case the attributes of the target object are described in a series of key value pairs. The attributes which apply to the selection are type specific and beyond the domain of the workbench itself, so the workbench will delegate filtering at this level to the actual selection.
<!ELEMENT objectContribution (filter | menu | action)*> <!ATTLIST objectContribution id CDATA #REQUIRED objectClass CDATA #REQUIRED nameFilter CDATA #IMPLIED >
<!ELEMENT viewerContribution (menu | action)*> <!ATTLIST viewerContribution id CDATA #REQUIRED targetID CDATA #REQUIRED >
<!ELEMENT filter EMPTY> <!ATTLIST filter name CDATA #REQUIRED value CDATA #REQUIRED >
<!ELEMENT menu (separator)+> <!ATTLIST menu id CDATA #REQUIRED label CDATA #REQUIRED path CDATA #IMPLIED >
<!ELEMENT separator EMPTY> <!ATTLIST separator name CDATA #REQUIRED >
<!ELEMENT action EMPTY> <!ATTLIST action id NMTOKEN #REQUIRED label CDATA #REQUIRED menubarPath CDATA #IMPLIED icon CDATA #IMPLIED helpContextId CDATA #IMPLIED state (true | false) #IMPLIED class CDATA #REQUIRED enablesFor CDATA #IMPLIED >
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:
The following is an example of a pop-up menu extension point:
<extension point="org.jlense.uiworks.popupMenus"> <objectContribution id="com.xyz.C1" objectClass="org.eclipse.core.resources.IFile" nameFilter="*.java"> <menu id="com.xyz.xyzMenu" path="additions" label="&XYZ Java Tools"> <separator name="group1"/> </menu> <action id="com.xyz.runXYZ" label="&Run XYZ Tool" menubarPath="com.xyz.xyzMenu/group1" icon="icons/runXYZ.gif" helpContextId="com.xyz.run_action_context" class="com.xyz.actions.XYZToolActionDelegate" enablesFor="1"> </action> </objectContribution> <viewerContribution id="com.xyz.C2" targetID="org.eclipse.ui.views.TaskList"> <action id="com.xyz.showXYZ" label="&Show XYZ" menubarPath="additions" icon="icons/showXYZ.gif" helpContextId="com.xyz.show_action_context" class="com.xyz.actions.XYZShowActionDelegate"> </action> </viewerContribution> </extension>
In the example above, the specified action will only enable for a single selection (enablesFor attribute). In addition, each object in the selection must implement the specified interface (IFile) and must be a Java file. This action will be added into a submenu previously created. This contribution will be effective in any view that has the required selection.
In contrast, the viewer contribution above will only appear in the Tasks view, and will not be affected by the selection in the view.
The following is an example of the filter mechanism. In this case the action will only appear for IMarkers which are completed and have high priority.
<extension point="org.jlense.uiworks.popupMenus"> <objectContribution id="com.xyz.C1" objectClass="org.eclipse.core.resources.IMarker"> <filter name="done" value="true"/> <filter name="priority" value="2"/> <action id="com.xyz.runXYZ" label="High Priority Completed Action Tool" icon="icons/runXYZ.gif" class="com.xyz.actions.MarkerActionDelegate"> </action> </objectContribution> </extension>
API Information: The value of the action attribute class must be a fully qualified class name of a Java class that implements org.jlense.uiworks.workbench.IObjectActionDelegate in the case of object contributions, org.jlense.uiworks.workbench.IViewActionDelegate for contributions to viewers that belong to views. In all cases, the implementing class is loaded as late as possible to avoid loading the entire plug-in before it is really needed.
Note: For backwards compatability, org.jlense.uiworks.workbench.IActionDelegate may be implemented for object contributions.
Popup menu extension within a part is only possible when the target part publishes a menu for extension. This is heartily encouraged, as it improves the extensability of the product. To accomplish this each part should publish any popup menus which are defined by calling IWorkbenchPartSite#registerContextMenu. Once this has been done the workbench will automatically insert any action extensions which exist.
A menu id must be provided for each registered menu. For consistency across parts the following strategy should be adopted by all part implementors.
An object in the workbench which is the selection in a context menu may define an org.jlense.uiworks.workbench.IActionFilter. This is a filtering strategy which can perform type specific filtering. The workbench will retrieve the filter for the selection by testing to see if it implements IActionFilter. If that fails, the workbench will ask for a filter through the IAdaptable mechanism.
Supplied Implementation: The workbench view have built-in pop-up menus that already come loaded with a number of actions. Plug-ins can contribute to these menus. If a viewer has reserved slots for these contributions and they are made public, slot names can be used as paths. Otherwise, actions and submenus will be added at the end of the pop-up menu.