Commands

Identifier:
org.eclipse.ui.commands

Since:
2.1

Description:

The org.eclipse.ui.commands extension point is used to declare commands and command categories, using the command and category elements. A command is an abstract representation of some semantic behaviour, but not its actual implementation. This allows different developers to contribute specific behaviour for their individual parts. For example, there might be a "paste" command with one implementation in an editor and a different implementation in an explorer widget. These implementations are called handlers. Commands can also be viewed as declarative function pointers, or signal handlers.

Configuration Markup:

<!ELEMENT extension (category* , command* , commandParameterType* , keyBinding* , keyConfiguration* , context* , scope* , activeKeyConfiguration?)>

<!ATTLIST extension

id    CDATA #IMPLIED

name  CDATA #IMPLIED

point CDATA #REQUIRED

>


<!ELEMENT command (defaultHandler? , state* , commandParameter*)>

<!ATTLIST command

category       CDATA #IMPLIED

description    CDATA #IMPLIED

id             CDATA #REQUIRED

name           CDATA #REQUIRED

categoryId     IDREF #IMPLIED

defaultHandler CDATA #IMPLIED

returnTypeId   IDREF #IMPLIED

helpContextId  CDATA #IMPLIED

>

This element is used to define commands. A command represents an request from the user that can be handled by an action, and should be semantically unique among other commands. Do not define a command if there is already one defined with the same meaning. If more than one of these elements exist with the same id attribute, only the last declared element (in order of reading the plugin registry) is considered valid. See the extension points org.eclipse.ui.actionSets and org.eclipse.ui.editorActions to understand how actions are connected to commands.



<!ELEMENT category EMPTY>

<!ATTLIST category

description CDATA #IMPLIED

id          CDATA #REQUIRED

name        CDATA #REQUIRED

>

In the UI, commands are often organized by category to make them more manageable. This element is used to define these categories. Commands can add themselves to at most one category. If more than one of these elements exist with the same id attribute, only the last declared element (in order of reading the plugin registry) is considered valid.



<!ELEMENT commandParameter (values?)>

<!ATTLIST commandParameter

id       CDATA #REQUIRED

name     CDATA #REQUIRED

values   CDATA #IMPLIED

typeId   IDREF #IMPLIED

optional (true | false) "true"

>

Defines a parameter that a command should understand. A parameter is a way to provide more information to a handler at execution time. For example, a "show view" command might take a view as a parameter. Handlers should be able to understand these parameters, so they should be treated like API.

Since: 3.1



<!ELEMENT commandParameterType EMPTY>

<!ATTLIST commandParameterType

id        CDATA #REQUIRED

type      CDATA #IMPLIED

converter CDATA #IMPLIED

>

Defines the object type of a commandParameter and may specify an org.eclipse.core.commands.AbstractParameterValueConverter subclass to convert between string parameter values and objects.

Since: 3.2



<!ELEMENT values (parameter*)>

<!ATTLIST values

class CDATA #REQUIRED

>

The more verbose version of the values attribute on the commandParameter.

Since: 3.1



<!ELEMENT parameter EMPTY>

<!ATTLIST parameter

name  CDATA #REQUIRED

value CDATA #REQUIRED

>

A possible value for a parameter.

Since: 3.1



<!ELEMENT defaultHandler (parameter)>

<!ATTLIST defaultHandler

class CDATA #REQUIRED

>

The default handler for this command. If no other handler is active, this handler will be active. This handler will conflict with other handler definitions that specify no activeWhen conditions. If you are not creating an IExecutableExtension, you can use the defaultHandler attribute instead.

Since: 3.1



<!ELEMENT state (class?)>

<!ATTLIST state

class CDATA #IMPLIED

id    CDATA #REQUIRED

>

State information shared between all handlers, and potentially persisted between sessions.The state is simply a class that is loaded to look after the state. See the API Information for more details. This is not used for UI attributes like a menu contribution check box state or label.

Since: 3.2



<!ELEMENT class (parameter*)>

<!ATTLIST class

class CDATA #REQUIRED

>

The class that can be loaded to store the state of this command. This element is used if you wish to pass multiple parameters to an org.eclipse.core.runtime.IExecutableExtension.

Since: 3.2



The keyConfiguration element is deprecated

<!ELEMENT keyConfiguration EMPTY>

<!ATTLIST keyConfiguration

description CDATA #IMPLIED

id          CDATA #REQUIRED

name        CDATA #REQUIRED

parent      CDATA #IMPLIED

parentId    CDATA #IMPLIED

>

This element is used to define key configurations. If more than one of these elements exist with the same id attribute, only the last declared element (in order of reading the plugin registry) is considered valid. Please use the "org.eclipse.ui.bindings" extension point instead.



The context element is deprecated

<!ELEMENT context EMPTY>

<!ATTLIST context

description CDATA #IMPLIED

id          CDATA #REQUIRED

name        CDATA #REQUIRED

parent      CDATA #IMPLIED

parentId    CDATA #IMPLIED

>

This element is used to define contexts. If more than one of these elements exist with the same id attribute, only the last declared element (in order of reading the plugin registry) is considered valid. Please use the org.eclipse.ui.contexts extension point instead.



The scope element is deprecated

<!ELEMENT scope EMPTY>

<!ATTLIST scope

description CDATA #IMPLIED

id          CDATA #REQUIRED

name        CDATA #REQUIRED

parent      CDATA #IMPLIED

>

This element is used to define scopes. If more than one of these elements exist with the same id attribute, only the last declared element (in order of reading the plugin registry) is considered valid. @deprecated Please use the "org.eclipse.ui.contexts" extension point instead.



The activeKeyConfiguration element is deprecated

<!ELEMENT activeKeyConfiguration EMPTY>

<!ATTLIST activeKeyConfiguration

value              CDATA #IMPLIED

keyConfigurationId CDATA #IMPLIED

>

This element is used to define the initial active key configuration for Eclipse. If more than one of these elements exist, only the last declared element (in order of reading the plugin registry) is considered valid.

This element has been replaced with a preference. If your application needs to change the default key configuration, then specify the following in your plugin_customization.ini file: org.eclipse.ui/KEY_CONFIGURATION_ID=your.default.key.configuration.id.



The keyBinding element is deprecated

<!ELEMENT keyBinding EMPTY>

<!ATTLIST keyBinding

configuration      CDATA #IMPLIED

command            CDATA #IMPLIED

locale             CDATA #IMPLIED

platform           CDATA #IMPLIED

contextId          CDATA #IMPLIED

string             CDATA #IMPLIED

scope              CDATA #IMPLIED

keyConfigurationId CDATA #IMPLIED

commandId          CDATA #IMPLIED

keySequence        CDATA #IMPLIED

>

This element allows one to assign key sequences to commands. Please use the key element in the "org.eclipse.ui.bindings" extension point instead.



Examples:

The plugin.xml file in the org.eclipse.ui plugin makes extensive use of the org.eclipse.ui.commands extension point.

API Information:

Handlers can be registered with commands using the org.eclipse.ui.handlers.IHandlerService. This can be retrieved from various workbench components (e.g., workbench, workbench window, part site, etc.) by calling getService(IHandlerService.class).

In general, it is preferrably to declare all commands statically (in plugin.xml). This is so that users can attach key bindings to the commands. However, it is possible to declare commands at run-time. To do this, retrieve the org.eclipse.ui.commands.ICommandService from a workbench component, call getCommand(yourCommandID) and then call Command.define(...). Commands defined programmatically must be cleaned up by the plugin if it is unloaded.

There are a few default implementations of handler states that may be useful to users of this extension point:


Copyright (c) 2000, 2011 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 http://www.eclipse.org/legal/epl-v10.html