Action definitions

An action definition is the declaration of an action by id.  Action definitions are used to declare semantic actions so that actions defined in action sets and editors can associate themselves with a particular semantic action definition.  The separation of the action definition from the action implementation allows multiple plug-ins to define actions that implement the same semantic action.  The action definition is what gets associated with accelerator key combinations.

The workbench defines many common action definitions in its plugin.xml file, and plug-ins are encouraged to associate their own actions with these definitions where it makes sense.  In this way, semantically similar actions implemented in different plug-ins may share the same key binding.

Defining an action definition

Action definitions are defined using the org.eclipse.ui.actionDefinitions extension point.  The following comes from the workbench markup:

<extension
         point="org.eclipse.ui.actionDefinitions">
      <actionDefinition
            id="org.eclipse.ui.file.close">
      </actionDefinition>
      <actionDefinition
            id="org.eclipse.ui.file.closeAll">
      </actionDefinition>
      <actionDefinition
            id="org.eclipse.ui.file.save">
      </actionDefinition>
      ...

The definition itself is simple.  It merely specifies an id for a semantic action.  An action definition only becomes concrete when a plug-in associates its action with the definition.

Associating an action with an action definition

Actions can be associated with an action definition in code or in the plugin.xml for action sets..  Your choice depends on where the action is defined.

Actions that are instantiated in code can also be associated with an action definition using IAction protocol.  This is typically done when the action is created.  The WorkbenchActionBuilder uses this technique to initialize its actions.  

private void makeActions() {
	...
	saveAction = new SaveAction(window);
	saveAction.setImageDescriptor(WorkbenchImages.getImageDescriptor(IWorkbenchGraphicConstants.IMG_CTOOL_SAVE_EDIT));
	saveAction.setHoverImageDescriptor(WorkbenchImages.getImageDescriptor(IWorkbenchGraphicConstants.IMG_CTOOL_SAVE_EDIT_HOVER));
	saveAction.setDisabledImageDescriptor(WorkbenchImages.getImageDescriptor(IWorkbenchGraphicConstants.IMG_CTOOL_SAVE_EDIT_DISABLED));
	partService.addPartListener(saveAction);
	saveAction.setActionDefinitionId(saveActionDefId);
	...

In this way, the implementation action (SaveAction) is associated with the action definition saveActionDefId.  What is saveActionDefId?  A quick look at the static field definitions in WorkbenchActionBuilder shows the following:

private static final String saveActionDefId = "org.eclipse.ui.file.save";

It is good practice to define constants for your action definitions so that they are easily referenced in code. 

If you define an action in an action set, then you typically do not need to instantiate it yourself.  The workbench will do it for you when the user invokes your action from a menu or the keyboard.  In this case, you can associate your action with an action definition in the XML markup.  The following shows a hypothetical markup for an action set:

<extension point = "org.eclipse.ui.actionSets">
	   <actionSet id="com.example.actions.actionSet"
		   label="Example Actions"
		   visible="true">
		   <action id="com.example.actions.action1"
			   menubarPath="additions"
			   label="Example Save Action"
			   class="org.example.actions.ExampleActionDelegate"
			   definitionID="org.eclipse.ui.file.save">
		   </action>
		   ...
	   </actionSet>
   </extension>

The definitionID attribute is used to declare an action definition id for the action.

Using either technique, associating your action with an action definition causes any key bindings that get defined for the action definition org.eclipse.ui.file.save to invoke your action when appropriate. 

Now let's look at how these key bindings get defined.

 

Copyright IBM Corp. and others 2000,2002.