A command is the declaration of a user action by id. Commands are used to declare semantic actions so that action implementations defined in action sets and editors can associate themselves with a particular semantic command. The separation of the command from the action implementation allows multiple plug-ins to define actions that implement the same semantic command. The command is what gets associated with a particular key binding.
The workbench defines many common commands in its plugin.xml file, and plug-ins are encouraged to associate their own actions with these commands where it makes sense. In this way, semantically similar actions implemented in different plug-ins may share the same key binding.
Commands are defined using the org.eclipse.ui.commands extension point. The following comes from the workbench markup:
<extension point="org.eclipse.ui.commands"> ... <command category="org.eclipse.ui.category.file" name="%command.close.name" description="%command.close.description" id="org.eclipse.ui.file.close"> </command> <command category="org.eclipse.ui.category.file" name="%command.closeAll.name" description="%command.closeAll.description" id="org.eclipse.ui.file.closeAll"> </command> <command category="org.eclipse.ui.category.file" name="%command.save.name" icon="icons/full/ctool16/save_edit.gif" description="%command.save.description" id="org.eclipse.ui.file.save"> </command> ...
The command definition specifies a name, description, and id for the action. It also specifies a category for the command, which is used to group commands in the preferences dialog. The categories are also defined in the org.eclipse.ui.commands extension point:
... <category name="%category.file.name" description="%category.file.description" id="org.eclipse.ui.category.file"> </category> ...
Note that there is no implementation specified for a command. A command only becomes concrete when a plug-in associates its action with the command id.
Actions can be associated with a command 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); ...
(Note: The method name setActionDefinitionID could more appropriately be named setCommandID. The method name reflects the original implementation of key bindings and uses outdated terminology.)
By invoking setActionDefinitionID, the implementation action (SaveAction) is associated with the command id 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";
This constant defines the string ID that was used in the command definition markup. 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 an action 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 a command ID in your 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 a command ID for the action.
Using either technique, associating your action with a command ID causes any key bindings that get defined for the command org.eclipse.ui.file.save to invoke your action when appropriate.
Now let's look at how these key bindings get defined.