Eclipse Plug-in Developer Guide
Previous Page	Home	Next Page

---

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

>

• 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

>

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

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 https://www.eclipse.org/legal/epl-v10.html