# Bindings

###### Identifier:

org.eclipse.ui.bindings

###### Since:

3.1

###### Description:

The `org.eclipse.ui.bindings` extension point is used to declare bindings and schemes. Schemes are sets of one or more bindings. A binding is a mapping between a certain group of conditions, some user input and a triggered command.

All bindings require a trigger of some kind, a context in which they are active and scheme in which they exist. If you're not sure which context to chose, then just leave it blank. It will default to `"org.eclipse.ui.contexts.window"` context. This context means that the binding will apply in any Eclipse main window. When the context becomes active, the binding will become active as well. Bindings from child contexts will override bindings from parent contexts. For more information about contexts, please see the `org.eclipse.ui.contexts` extension point.

If a binding does not define a command identifier, then it is a deletion marker. This means that if all the conditions are met, it will cancel any bindings with the same trigger in the same context. This mechanism can be used, for example, to change a binding on a particular platform.

One type of binding is a `key` binding (i.e., a keyboard shortcut). For example, binding `Ctrl+C` to `Copy` is considered a `key` binding. The trigger for a key binding is a sequence of key strokes.

A scheme is a group of these bindings into a set that the end user can select. For example, a user might want to use the default scheme, but they might also want an Emacs-style scheme or a Brief-style scheme.

###### Configuration Markup:

<!ELEMENT extension (scheme* , key* , sequenceModifier*)>

<!ATTLIST extension

point CDATA #REQUIRED

id CDATA #IMPLIED

name CDATA #IMPLIED>

<!ELEMENT scheme EMPTY>

<!ATTLIST scheme

id CDATA #REQUIRED

name CDATA #REQUIRED

description CDATA #IMPLIED

parentId IDREF #IMPLIED>

A scheme is a grouping of bindings that an end user can chose to use.

It is possible for schemes to inherit bindings from a parent scheme. This is intended to make it easier for plug-in developers to create customized binding sets. An active binding defined in a child scheme will always override an active binding in a parent scheme, if they have the same trigger. This technique is used to provide the Emacs scheme in the workbench.

- id - The unique identifier for this scheme.
- name - The name for this scheme, as it should be displayed to an end-user. This value should be translated.
- description - The description for this scheme, as it would be displayed to an end user. This value should be translated.
- parentId - The identifier for the parent of this scheme. If there is no parent, then do not specify this attribute.

<!ELEMENT key (parameter*)>

<!ATTLIST key

sequence CDATA #REQUIRED

schemeId IDREF #REQUIRED

contextId IDREF "org.eclipse.ui.contexts.window"

commandId IDREF #IMPLIED

platform CDATA #IMPLIED

locale CDATA #IMPLIED>

A binding between some keyboard input and the triggering of a command.

- sequence -

  The key sequence for this binding. This key sequence should consist of one or more key strokes. Key strokes are separated by spaces. Key strokes consist of one or more keys held down at the same time. This should be zero or more modifier keys, and one other key. The keys are separated by the `+` character.

  The recognized modifiers keys are `M1`, `M2`, `M3`, `M4`, `ALT`, `COMMAND`, `CTRL`, and `SHIFT`. The "M" modifier keys are a platform-independent way of representing keys, and these are generally preferred. `M1` is the `COMMAND` key on MacOS X, and the `CTRL` key on most other platforms. `M2` is the `SHIFT` key. `M3` is the `Option` key on MacOS X, and the `ALT` key on most other platforms. `M4` is the `CTRL` key on MacOS X, and is undefined on other platforms. Since `M2+M3+<Letter>` (`Alt+Shift+<Letter>`) is reserved on MacOS X for writing special characters, such bindings are commonly undefined for `platform="carbon"` and redefined as `M1+M3+<Letter>`.

  The actual key is generally specified simply as the ASCII character, in uppercase. So, for example `F` or `,` are examples of such keys. However, there are some special keys; keys that have no printable ASCII representation. The following is a list of the current special keys: `ARROW_DOWN`, `ARROW_LEFT`, `ARROW_RIGHT`, `ARROW_UP`, `BREAK`, `BS`, `CAPS_LOCK`, `CR`, `DEL`, `END`, `ESC`, `F1`, `F2`, `F3`, `F4`, `F5`, `F6`, `F7`, `F8`, `F9`, `F10`, `F11`, `F12`, `F13`, `F14`, `F15`, `FF`, `HOME`, `INSERT`, `LF`, `NUL`, `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`, `SCROLL_LOCK`, `SPACE`, `TAB` and `VT`.

  We also understand some alternative names for some common special keys. For example, we accept both `ESC` and `ESCAPE`, and `CR`, `ENTER` and `RETURN` are all the same.

  It is also strongly recommended that you keep the key sequences short. One or two is the most you should need. Use contexts to give key sequences different meanings in different parts of your application. At the very most, you should not use any key sequence that contains more than four key strokes.

- schemeId - The identifier of the scheme in which this key binding is active.
- contextId - The identifier of the context in which this key binding is active. Please see the `org.eclipse.ui.contexts` extension point. If this is not specified, then it defaults to `org.eclipse.ui.contexts.window`.
- commandId -

  The identifier of the command which should be executed when this binding is triggered.

  If no command identifier is specified, this is a deletion marker. This means that any binding in the same context with the same sequence, platform and locale will become inactive when this binding becomes active. If the platform or locale on a deletion is not specified, then it matches any platform or locale.

- platform - The platform on which this binding applies. The platform should be specified in the same way as the string from `SWT.getPlatform()`. For example, the following strings are considered valid: `win32`, `gtk`, `motif`, `carbon` and `photon`.
- locale - The locale on which this bindings applies. This is useful for changing bindings that conflict with locale-specific input method editors (IMEs). The locale is specified in the same way as `Locale.toString()`. For example, `"en"` or `"en_CA"` are both understood.

<!ELEMENT parameter EMPTY>

<!ATTLIST parameter

id IDREF #IMPLIED

value CDATA #IMPLIED>

A parameter name and value that should be passed to the command when it is executed. This allows for the command to be qualified in some way. For example, a "Show View" command might accept the view id as a parameter.

- id - The parameter name as understood by the command. This is not a translatable name, but the key to name-value map.
- value - The value for the parameter. This value is a free-form string, but it should be parseable by the command. Consult the command to see what format it expects these values to take.

<!ELEMENT sequenceModifier EMPTY>

<!ATTLIST sequenceModifier

find CDATA #REQUIRED

replace CDATA #REQUIRED

platforms CDATA #REQUIRED>

Sequence Modifiers transform the key bindings on this extension. If a keybinding defined in this extension starts with the 'find' string, it will replace that portion with the 'replace' string. This replacement happens either if the platform in the keybinding is one of the platform in the 'platforms' or the platform in keybinding is not specified, but the current platform is one of the platform specified in 'platforms'

- find -

  The key sequence that has to be replaced. This key sequence should consist of one or more modifier keys without the actual key. The keys are separated by the `+` character.

  The recognized modifiers keys are `M1`, `M2`, `M3`, `M4`, `ALT`, `COMMAND`, `CTRL`, and `SHIFT`. The "M" modifier keys are a platform-independent way of representing keys, and these are generally preferred. `M1` is the `COMMAND` key on MacOS X, and the `CTRL` key on most other platforms. `M2` is the `SHIFT` key. `M3` is the `Option` key on MacOS X, and the `ALT` key on most other platforms. `M4` is the `CTRL` key on MacOS X, and is undefined on other platforms.

- replace -

  The key sequence that will be replaced with. This key sequence should consist of one or more modifier keys without the actual key. The keys are separated by the `+` character.

  The recognized modifiers keys are `M1`, `M2`, `M3`, `M4`, `ALT`, `COMMAND`, `CTRL`, and `SHIFT`. The "M" modifier keys are a platform-independent way of representing keys, and these are generally preferred. `M1` is the `COMMAND` key on MacOS X, and the `CTRL` key on most other platforms. `M2` is the `SHIFT` key. `M3` is the `Option` key on MacOS X, and the `ALT` key on most other platforms. `M4` is the `CTRL` key on MacOS X, and is undefined on other platforms.

- platforms - A comma seperated value of the platforms for which the modifier to be applied on . The individual platform string should be specified in the same way as the string from `SWT.getPlatform()`. For example, the following strings are considered valid for a platform: `win32`, `gtk`, `motif`, `carbon` and `photon`.

###### Examples:

    <extension
     point="org.eclipse.ui.bindings">
     <sequenceModifier
      find="M1+M2"
      replace="M2+M3"
      platforms="cocoa,carbon" />
     <key
      sequence="M2+F5"
      commandId="example.commandId"
      schemeId="org.eclipse.ui.defaultAcceleratorConfiguration"
      contextId="org.eclipse.ui.contexts.dialog" />
     <key
      sequence="M1+M2+8"
      commandId="another.example.commandId"
      schemeId="org.eclipse.ui.defaultAcceleratorConfiguration"
      contextId="org.eclipse.ui.contexts.window" />
     <key
      sequence="M2+F7"
      commandId="other.commandId"
      schemeId="default.id"
      contextId="org.eclipse.ui.contexts.dialog" />
     <scheme
      name="Default"
      description="Default shortcuts for Eclipse"
      id="default.id" />
    </extension>

In this example, on win32 `another.example.commandId` would be bound to M1+M2+8, but on cocoa it would be bound to M2+M3+8.

###### API Information:

There is no public API for defining bindings. To try to achieve stability for the user, bindings are only defined through the extension points. If you are an RCP application, you should be able to override this behaviour in the `WorkbenchAdvisor`.

For bindings to work, you must have defined a command. For the binding to work, the command must have an active handler. Handlers can be registered programmatically; please see the org.eclipse.ui.handlers extension point.

Copyright (c) 2005,2009 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