2.1
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 it's 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.
<!ELEMENT extension (activeKeyConfiguration , category , command , keyBinding , keyConfiguration , context , scope)>
<!ATTLIST extension
id CDATA #IMPLIED
name CDATA #IMPLIED
point CDATA #REQUIRED>
<!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
.
id
attribute) of the keyConfiguration element one wishes to be initially active.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.
<!ELEMENT command (commandParameter | defaultHandler?)>
<!ATTLIST command
category CDATA #IMPLIED
description CDATA #IMPLIED
id CDATA #REQUIRED
name CDATA #REQUIRED
categoryId CDATA #IMPLIED
defaultHandler 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.
activeWhen
conditions. If you are creating an IExecutableExtension
, you can use the defaultHandler
element instead.<!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.
java.util.Locale
.platform
attribute are the set of the possible values returned by org.eclipse.swt.SWT.getPlatform()
.schemeId
attribute on the key
element in the new "org.eclipse.ui.bindings" extension point.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.
<!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.
<!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.
<!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.
<!ELEMENT commandParameter (values)>
<!ATTLIST commandParameter
id CDATA #REQUIRED
name CDATA #REQUIRED
values CDATA #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.
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
.<!ATTLIST values
class CDATA #REQUIRED>
The more verbose version of the values
attribute on the commandParameter
.
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.
IExecutableExtension
.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.
org.eclipse.core.commands.IHandler
.
The plugin.xml
file in the org.eclipse.ui
plugin makes extensive use of the org.eclipse.ui.commands
extension point.
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, 2005 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