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>

id - An optional identifier of the extension instance.
name - An optional name of the extension instance.
point - A fully qualified identifier of the target extension point.

<!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.

Deprecated category - Please use categoryId instead.
description - A translatable short description of this command for display in the UI.
id - The unique identifier of this command.
name - The translatable name of this command for display in the UI. Commands are typically named in the form of an imperative verb.
categoryId -
The unique id of the category for this command. If this command does not specify a category it will be placed in an global "Uncategorized" category and will be filtered by default on the Keys preference page, meaning users cannot assign a key binding unless they disable the filter for "Uncategorized" commands.

Since: 3.0
defaultHandler -
The default handler for this command (see the org.eclipse.ui.handlers extension point). 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 creating an IExecutableExtension, you can use the defaultHandler element instead.

Since: 3.1
returnTypeId -
The id of a commandParameterType indicating the type of value returned by this command. Specifying a returnTypeId allows clients executing the command to associate the value returned with a Java type and to convert the value to a String form that may be stored and/or passed to another command that accepts parameters of the same type.

Since: 3.2
helpContextId -
The identifier of the help context that relates to this command in general. Handlers can override this context identifier to provide help that is more specific to their particular behaviours.

Since: 3.2

<!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.

description - A translatable short description of this category for display in the UI.
id - The unique identifier of this category.
name - The translatable name of this category for display in the UI.

<!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

id - The unique identifier for this parameter.
name - The name for the parameter. This is the name as it will be displayed to an end-user. As such, it should be translatable. The name should be short -- preferrably one word.
values - The class providing a list of parameter values for the user to select. This class should implement org.eclipse.core.commands.IParameterValues. If this class is not specified, you must specify the more verbose values element. Please see org.eclipse.core.runtime.IExecutableExtension.
typeId - The id of a commandParameterType for this commandParameter. Specifying a typeId allows handlers of a command to convert string parameter values to objects in a consistent way and it allows potential callers of a command to look for commands that take objects of various types for their parameters.
optional - Whether this parameter is optional. If a parameter is optional, the handler should be able to handle the absence of the parameter. By default, all parameters are optional.

<!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

id - The unique identifier for this commandParameterType.
type - The fully qualified name of a Java class or interface to use as the type of this command parameter. This attribute is optional, however if omitted, java.lang.Object will be used as the parameter type.
converter - The class for converting between objects and string representations of objects for command parameter values. This class should extend org.eclipse.core.commands.AbstractParameterValueConverter. The converter should produce and consume objects of the type indicated in the type attribute. If this class is not specified, this facility to convert between string and object values for this parameter type will not be available (the getValueConverter() on class ParameterType will return null).

<!ELEMENT values (parameter*)>

<!ATTLIST values

class CDATA #REQUIRED>

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

Since: 3.1

class - The class providing a list of parameter values for the user to select. This class should implement org.eclipse.core.commands.IParameterValues. If this class is not specified, you must specify the more verbose values element. Please see org.eclipse.core.runtime.IExecutableExtension.

<!ELEMENT parameter EMPTY>

<!ATTLIST parameter

name CDATA #REQUIRED

value CDATA #REQUIRED>

A possible value for a parameter.

Since: 3.1

name - The name of the parameter to pass to the IExecutableExtension.
value - The value of the parameter to pass to the IExecutableExtension.

<!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

class - The class which implements org.eclipse.core.commands.IHandler.

<!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

class - The class that can be loaded to store the state of this command. State is shared amongst handlers, and can be persisted between sessions. This class must subclass org.eclipse.core.commands.State. Please see API Information.
id -
A unique identifier for this state. This is used for persisting the state between sessions (if the state is an instance of org.eclipse.jface.commands.PersistentState). Certain common identifiers (see org.eclipse.jface.menus.IMenuStateIds) are understood when the command is being rendered in the menus or tool bars. The identifier only needs to be unique within the command defining the state.

<!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

class - The class that can be loaded to store the state of this command. State is shared amongst handlers, and can be persisted between sessions. This class must implement org.eclipse.core.commands.State. Please see API Information.

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.

Deprecated description - A translatable short description of this key configuration for display in the UI.
Deprecated id - The unique identifier of this key configuration.
Deprecated name - The translatable name of this key configuration for display in the UI. If this key configuration has a parent, it is not necessary to add "(extends ...)" to the name. This will be automatically added by the UI where necessary.
Deprecated parent - The unique id of the parent key configuration. If this key configuration has a parent, it will borrow all key bindings from its parent, in addition to the key bindings defined in its own key configuration. @deprecated Please use parentId instead.
Deprecated parentId - The unique id of the parent key configuration. If this key configuration has a parent, it will borrow all key bindings from its parent, in addition to the key bindings defined in its own key configuration.

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.

Deprecated description - A translatable short description of this context for display in the UI.
Deprecated id - The unique identifier of this context.
Deprecated name - The translatable name of this context for display in the UI. If this context has a parent, it is not necessary to add "(extends parent)" to the name. This will be automatically added by the UI where necessary.
Deprecated parent - The unique id of the parent context. If this context has a parent, it will borrow all key bindings from its parent, in addition to the key bindings defined in its own context. @deprecated Please use "parentId" instead.
Deprecated parentId - The unique id of the parent context. If this context has a parent, it will borrow all key bindings from its parent, in addition to the key bindings defined in its own context.

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.

Deprecated description - A translatable short description of this scope for display in the UI. @deprecated Please use the "org.eclipse.ui.contexts" extension point instead.
Deprecated id - The unique identifier of this scope. @deprecated Please use the "org.eclipse.ui.contexts" extension point instead.
Deprecated name - The translatable name of this scope for display in the UI. If this scope has a parent, it is not necessary to add "(extends parent)" to the name. This will be automatically added by the UI where necessary. @deprecated Please use the "org.eclipse.ui.contexts" extension point instead.
Deprecated parent - The unique id of the parent scope. If this scope has a parent, it will borrow all key bindings from its parent, in addition to the key bindings defined in its own scope. @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.

Deprecated value - The unique id (id attribute) of the keyConfiguration element one wishes to be initially active.
Deprecated keyConfigurationId - The unique id (id attribute) of the keyConfiguration element one wishes to be initially active.

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.

Deprecated configuration - The unique id of the key configuration of this key binding. @deprecated Please use keyConfigurationId instead.
Deprecated command - The unique identifier of the command to which the key sequence specified by this key binding is assigned. If the value of this attribute is an empty string, the key sequence is assigned to an internal 'no operation' command. This is useful for 'undefining' key bindings in specific key configurations and contexts which may have been borrowed from their parents. @deprecated Please use "commandId" instead.
Deprecated locale - An optional attribute indicating that this key binding is only defined for the specified locale. Locales are specified according to the format declared in java.util.Locale.
Deprecated platform - An optional attribute indicating that this key binding is only defined for the specified platform. The possible values of the platform attribute are the set of the possible values returned by org.eclipse.swt.SWT.getPlatform().
Deprecated contextId - The unique id of the context of this key binding.
Deprecated string - The key sequence to assign to the command. Key sequences consist of one or more key strokes, where a key stroke consists of a key on the keyboard, optionally pressed in combination with one or more of the following modifiers: Ctrl, Alt, Shift, and Command. Key strokes are separated by spaces, and modifiers are separated by '+' characters. @deprecated Please use "keySequence" instead.
Deprecated scope - The unique id of the context of this key binding. @deprecated Please use "contextId" instead. The old default scope, "org.eclipse.ui.globalScope", has been changed to "org.eclipse.ui.contexts.window". The old name is still supported, but it is deprecated.
Deprecated keyConfigurationId - The unique id of the key configuration of this key binding. @deprecated Please use the schemeId attribute on the key element in the new "org.eclipse.ui.bindings" extension point.
Deprecated commandId - The unique identifier of the command to which the key sequence specified by this key binding is assigned. If the value of this attribute is an empty string, the key sequence is assigned to an internal 'no operation' command. This is useful for 'undefining' key bindings in specific key configurations and contexts which may have been borrowed from their parents.
Deprecated keySequence -
The key sequence to assign to the command. Key sequences consist of one or more key strokes, where a key stroke consists of a key on the keyboard, optionally pressed in combination with one or more of the following modifiers: Ctrl, Alt, Shift, and Command. Key strokes are separated by spaces, and modifiers are separated by '+' characters.

The modifier keys can also be expressed in a platform-independent way. On MacOS X, for example, "Command" is almost always used in place of "Ctrl". So, we provide "M1" which will map to either "Ctrl" or "Command", as appropriate. Similarly, "M2" is "Shift"; "M3" is "Alt"; and "M4" is "Ctrl" (MacOS X). If more platforms are added, then you can count on these aliases being mapped to good platform defaults.

The syntax for this string is defined in org.eclipse.ui.internal.keys. Briefly, the string is case insensitive -- though all capitals is preferred stylistically. If the key is a letter, then simply append the letter. If the key is a special key (i.e., non-ASCII), then use one of the following: ARROW_DOWN, ARROW_LEFT, ARROW_RIGHT, ARROW_UP, BREAK, CAPS_LOCK, END, F1, F2, F3, F4, F5, F6, F7, F8, F9, F10, F11, F12, F13, F14, F15, HOME, INSERT, NUM_LOCK, NUMPAD_0, NUMPAD_1, NUMPAD_2, NUMPAD_3, NUMPAD_4, NUMPAD_5, NUMPAD_6, NUMPAD_7, NUMPAD_8, NUMPAD_9, NUMPAD_ADD, NUMPAD_DECIMAL, NUMPAD_DIVIDE, NUMPAD_ENTER, NUMPAD_EQUAL, NUMPAD_MULTIPLY, NUMPAD_SUBTRACT, PAGE_UP, PAGE_DOWN, PAUSE, PRINT_SCREEN, or SCROLL_LOCK. If the key is a non-printable ASCII key, then use one of the following: BS, CR, DEL, ESC, FF, LF, NUL, SPACE, TAB, or VT. Note that the main keyboard enter/return key is CR.

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:

org.eclipse.jface.commands.TextState
org.eclipse.jface.commands.RadioState
org.eclipse.jface.commands.ToggleState
org.eclipse.ui.handlers.RegistryRadioState
org.eclipse.ui.handlers.RegistryToggleState

Copyright (c) 2000, 2018 IBM Corporation and others.
This program and the accompanying materials are made available under the terms of the Eclipse Public License 2.0 which accompanies this distribution, and is available at https://www.eclipse.org/legal/epl-v20.html/ SPDX-License-Identifier: EPL-2.0