Class KeyBindings

java.lang.Object
com.biglybt.ui.swt.KeyBindings

public final class KeyBindings extends 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
  2. 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:

  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 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
  • Field Details

    • FUNC_EXP

      private static final Pattern FUNC_EXP
    • SANCTIONED_EXP

      private static final Pattern SANCTIONED_EXP
    • SPECIAL_KEYS

      private static final String[] SPECIAL_KEYS
    • SPECIAL_VALUES

      private static final int[] SPECIAL_VALUES
    • DELIM

      private static final String DELIM
      See Also:
    • DELIM_EXP

      private static final String DELIM_EXP
      See Also:
  • Constructor Details

    • KeyBindings

      public KeyBindings()
  • Method Details

    • getPlatformKeySuffix

      private static String 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

      private 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.
      Parameters:
      keyBindingValue - Keybinding value
      Returns:
      A KeyBindingInfo object, which consists of the SWT accelerator and its display name
    • removeAccelerator

      public static void removeAccelerator(org.eclipse.swt.widgets.MenuItem menu, 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, 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(String localizationKey)
    • 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 MenuItem
      kbInfo - KeyBindingInfo object, which contains the SWT accelerator value and its display name
    • main

      public static void main(String[] args)
      Runs simple tests on KeyBindings keybinding values
      Parameters:
      args - Command-line arguments; they are not used