#
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. Through this extension point, one can also assign key sequences to commands using the `keyBinding` element. Key sequences are bound to commands based on key configurations and contexts which are declared here as well, using the `keyConfiguration` and `context` elements.

###### Configuration Markup:

<!ELEMENT extension (activeKeyConfiguration , category , command , keyBinding , keyConfiguration , context)>

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

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

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

<!ATTLIST command

category CDATA #IMPLIED

description CDATA #IMPLIED

id CDATA #REQUIRED

name CDATA #REQUIRED

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

- category - The unique id of the category for this command. If this command does not specify a category, it will still appear in all UI, alongside other specifically categorized commands. @deprecated 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. Command 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 still appear in all UI, alongside other specifically categorized commands.

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

- configuration - The unique id of the key configuration of this key binding. @deprecated Please use keyConfigurationId instead.
- 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. @deprecate Please use "commandId" instead.
- 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`.
- 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()`.
- contextId - The unique id of the context of this key binding.
- 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. @deprecate Please user "keySequence" instead.
- scope - The unique id of the context of this key binding. @deprecated Please use "contextId" instead.
- keyConfigurationId - The unique id of the key configuration of this key binding.
- 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.
- 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.

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

- description - A translatable short description of this key configuration for display in the UI.
- id - The unique identifier of this key configuration.
- 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.
- 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.
- 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.

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

- description - A translatable short description of this context for display in the UI.
- id - The unique identifier of this context.
- 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.
- 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.
- 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.

<!ELEMENT handlerSubmission EMPTY>

<!ATTLIST handlerSubmission

commandId CDATA #REQUIRED

handler CDATA #REQUIRED>

This element declares a handler for a command. This handler is then associated with the command with the given restrictions. This association is done at start-up. Associating a handler does not mean that this handler will always be the one chosen by the workbench; the actual choice is done by examining the workbench state and comparing with the various handler submissions.

This particular API should still be considered experimental. While you may use it, you must be willing to accept that this API may change radically or be removed entirely at some point in the future. We appreciate feedback on this API to platform-ui-dev@eclipse.org.

- commandId - The identifier of the command to which this handler should be associated.
- handler - The name of the class of the handler. If the class is an implementation of IExecutableExtension, then it is possible to pass data into the object. This handler will be proxied until the handler is queried for information -- at which point the class will be loaded, and an instance created.

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

- description - A translatable short description of this scope for display in the UI. @deprecated Please use the "org.eclipse.ui.contexts" extension point instead.
- id - The unique identifier of this scope. @deprecated Please use the "org.eclipse.ui.contexts" extension point instead.
- 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.
- 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.

###### Examples:

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

###### API Information:

This is no public API for declaring commands, categories, key bindings, key configurations, or contexts other than this extension point. Public API for querying and setting contexts, as well as registering actions to handle specific commands can be found in `org.eclipse.ui.IKeyBindingService`.

Copyright (c) 2000, 2004 IBM Corporation and others.
All rights reserved. This program and the accompanying materials are made available under the terms of the Common Public License v1.0 which accompanies this distribution, and is available at http://www.eclipse.org/legal/cpl-v10.html