Class KeyBindings
Facilitates localization-specific and platform-specific keyboard shortcut handling through the use of keybinding values.
A keybinding value is a line of String that can be specified in the localization bundle properties file for a particular menu item. To do so, a localization key/value pair is used, with the key being the same as menu item's key plus ".keybinding".
For instance, if a keyboard shortcut needs to be specified for "MainWindow.menu.file.open", then a key/value pair with the key of "MainWindow.menu.file.open.keybinding" is created. The value is what would be used as the keyboard accelerator, with the following special values:
- Meta (or Cmd) - The "Meta" modifier; this is "Command" on OS X, and "Control" on all other platforms
- Ctrl - The "Control" modifier on all platforms. Use this only if you need to enforce the use of Control.
- Alt (or Opt) - The "Alt" modifier
- Shift - The "Shift" modifier
- Ins - Insert
- Backspace
- Del - Delete
- Esc - Escape
- PgUp - Page Up
- PgDn - Page Down
- Left - The left arrow
- Up - The up arrow
- Right - The right arrow
- Down - The down arrow
- Home
- End
- Tab
- Fx, where x is an integer from 1 to 15 (inclusive) - The function key (F1-F15)
Other valid values can be typed as is or as the Unicode representation. For security reasons, this is initially set with a very conservative scope, including alphanumerics, \, =, -, (comma), (period), and `.
As of version 1.2, keybindings are only set if the following conditions are met:
- A function key is set or
- Meta, Alt, or Ctrl is set (or their variations)
The keys were chosen to more conveniently address the issue on platforms like Windows where vanilla SWT does not display the shortcuts, as opposed to higher-level API like JFace or some platforms' native rendering.
For example, if File / Open / .torrent File is set to be Meta+O (Command+O or Ctrl+O), then in MessageBundle.properties (or the localization- specific equivalent), MainWindow.menu.file.open.torrent.keybinding=Meta+O will be entered. The label will be adjusted to Ctrl on non-OS X platforms (OS X will draw the glyph for Cmd).
As another example, if File / Exit is set to be Alt+F4, then in MessageBundle.properties (or the localization-specific equivalent), MainWindow.menu.file.exit.keybinding=Alt+F4 will be entered.
To accommodate for the variety of locales and platforms running on the client, platforms and localizations can "override" the default keybinding value.
The order of parsing is as follows:
- If a localized keybinding value exists for the current locale and platform, it is used
- If the above is not found, this method looks for a keybinding value for the current locale without platform specificity
- If the above is not found, this method looks for a keybinding value for the default locale and the currently running platform
- If the above is not found, this method looks for a keybinding value for the default locale without platform specificity
- If the above is not found, no accelerator is set for the MenuItem
For instance, to refer to the above example, if the Mac OS X target for the client wants to handle File / Exit as Command+Q, then MainWindow.menu.file.exit.keybinding.mac=Meta+Q is entered. If it is not entered, the value for the 'default' key MainWindow.menu.file.exit.keybinding will be used.
The platform suffix can be attached to the end of the localization key. Valid suffixes are:
- .linux - Linux
- .mac - Mac OS X
- .windows - Windows
- Version:
- 1.3 Added removeAccelerator
-
Nested Class Summary
Nested ClassesModifier and TypeClassDescriptionstatic class
A basic bean object containing the SWT accelerator and its display name. -
Field Summary
Fields -
Constructor Summary
Constructors -
Method Summary
Modifier and TypeMethodDescriptionstatic KeyBindings.KeyBindingInfo
getKeyBindingInfo
(String localizationKey) private static String
Gets the localization key suffix for the running platform for keybinding retrievalstatic void
Runs simple tests on KeyBindings keybinding valuesprivate static KeyBindings.KeyBindingInfo
parseKeyBinding
(String keyBindingValue) Parses the keybinding string according to the specifications documented at this class and gets the SWT value equivalent for keyboard accelerator settings.static void
removeAccelerator
(org.eclipse.swt.widgets.MenuItem menu, String localizationKey) Removes the keyboard accelerator for a SWT MenuItemprivate static void
setAccelerator
(org.eclipse.swt.widgets.MenuItem menu, KeyBindings.KeyBindingInfo kbInfo) Helper method to set a keyboard accelerator for a MenuItem.static void
setAccelerator
(org.eclipse.swt.widgets.MenuItem menu, String localizationKey) Sets the keyboard accelerator for a SWT MenuItem.
-
Field Details
-
FUNC_EXP
-
SANCTIONED_EXP
-
SPECIAL_KEYS
-
SPECIAL_VALUES
private static final int[] SPECIAL_VALUES -
DELIM
- See Also:
-
DELIM_EXP
- See Also:
-
-
Constructor Details
-
KeyBindings
public KeyBindings()
-
-
Method Details
-
getPlatformKeySuffix
Gets the localization key suffix for the running platform for keybinding retrieval
For now, as is with the client's Constants behaviour, supported platforms are Linux, Mac OS X, and Windows only
- Returns:
- The platform key suffix; or an empty string on an unsupported platform
-
parseKeyBinding
Parses the keybinding string according to the specifications documented at this class and gets the SWT value equivalent for keyboard accelerator settings.- Parameters:
keyBindingValue
- Keybinding value- Returns:
- A KeyBindingInfo object, which consists of the SWT accelerator and its display name
-
removeAccelerator
Removes the keyboard accelerator for a SWT MenuItem
- Parameters:
menu
- SWT MenuItemlocalizationKey
- The MenuItem's localization key for the localization resource bundle
-
setAccelerator
Sets the keyboard accelerator for a SWT MenuItem.
There is a specific order of accelerator setting in consideration with different platforms and localizations. Specifically:
- If a localized keybinding value exists for the current locale and platform, it is used
- If the above is not found, this method looks for a keybinding value for the current locale without platform specificity
- If the above is not found, this method looks for a keybinding value for the default locale and the currently running platform
- If the above is not found, this method looks for a keybinding value for the default locale without platform specificity
- If the above is not found, no accelerator is set for the MenuItem
- Parameters:
menu
- SWT MenuItemlocalizationKey
- The MenuItem's localization key for the localization resource bundle
-
getKeyBindingInfo
-
setAccelerator
private static void setAccelerator(org.eclipse.swt.widgets.MenuItem menu, KeyBindings.KeyBindingInfo kbInfo) Helper method to set a keyboard accelerator for a MenuItem. If kbInfo is SWT.NONE, no accelerator will be set.- Parameters:
menu
- SWT MenuItemkbInfo
- KeyBindingInfo object, which contains the SWT accelerator value and its display name
-
main
Runs simple tests on KeyBindings keybinding values- Parameters:
args
- Command-line arguments; they are not used
-