org.gudy.azureus2.ui.swt
Class KeyBindings

java.lang.Object
  org.gudy.azureus2.ui.swt.KeyBindings

public final class KeyBindings
extends java.lang.Object

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:

1. A function key is set or
3. 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 Azureus, platforms and localizations can "override" the default keybinding value. The order of parsing is as follows:

1. If a localized keybinding value exists for the current locale and platform, it is used
2. If the above is not found, this method looks for a keybinding value for the current locale without platform specificity
3. If the above is not found, this method looks for a keybinding value for the default locale and the currently running platform
4. If the above is not found, this method looks for a keybinding value for the default locale without platform specificity
5. 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 Azureus 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

Author:

CrazyAlchemist

Nested Class Summary

static class

KeyBindings.KeyBindingInfo A basic bean object containing the SWT accelerator and its display name.

Constructor Summary

KeyBindings()

Method Summary

static KeyBindings.KeyBindingInfo	getKeyBindingInfo(java.lang.String localizationKey)
static void	main(java.lang.String[] args) Runs simple tests on KeyBindings keybinding values
static void	removeAccelerator(org.eclipse.swt.widgets.MenuItem menu, java.lang.String localizationKey) Removes the keyboard accelerator for a SWT MenuItem
static void	setAccelerator(org.eclipse.swt.widgets.MenuItem menu, java.lang.String localizationKey) Sets the keyboard accelerator for a SWT MenuItem.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

KeyBindings

public KeyBindings()

Method Detail

removeAccelerator

public static void removeAccelerator(org.eclipse.swt.widgets.MenuItem menu,
                                     java.lang.String localizationKey)

Removes the keyboard accelerator for a SWT MenuItem

Parameters:

menu - SWT MenuItem

localizationKey - The MenuItem's localization key for the localization resource bundle

setAccelerator

public static void setAccelerator(org.eclipse.swt.widgets.MenuItem menu,
                                  java.lang.String localizationKey)

Sets the keyboard accelerator for a SWT MenuItem.

There is a specific order of accelerator setting in consideration with different platforms and localizations. Specifically:

1. If a localized keybinding value exists for the current locale and platform, it is used
2. If the above is not found, this method looks for a keybinding value for the current locale without platform specificity
3. If the above is not found, this method looks for a keybinding value for the default locale and the currently running platform
4. If the above is not found, this method looks for a keybinding value for the default locale without platform specificity
5. If the above is not found, no accelerator is set for the MenuItem

Parameters:

menu - SWT MenuItem

localizationKey - The MenuItem's localization key for the localization resource bundle

getKeyBindingInfo

public static KeyBindings.KeyBindingInfo getKeyBindingInfo(java.lang.String localizationKey)

main

public static void main(java.lang.String[] args)

Runs simple tests on KeyBindings keybinding values

Parameters:

args - Command-line arguments; they are not used