Class 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
    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
    • Nested Class Summary

      Nested Classes 
      Modifier and Type Class Description
      static class  KeyBindings.KeyBindingInfo
      A basic bean object containing the SWT accelerator and its display name.
    • Field Summary

      Fields 
      Modifier and Type Field Description
      private static java.lang.String DELIM  
      private static java.lang.String DELIM_EXP  
      private static java.util.regex.Pattern FUNC_EXP  
      private static java.util.regex.Pattern SANCTIONED_EXP  
      private static java.lang.String[] SPECIAL_KEYS  
      private static int[] SPECIAL_VALUES  
    • Constructor Summary

      Constructors 
      Constructor Description
      KeyBindings()  
    • Method Summary

      All Methods Static Methods Concrete Methods 
      Modifier and Type Method Description
      static KeyBindings.KeyBindingInfo getKeyBindingInfo​(java.lang.String localizationKey)  
      private static java.lang.String getPlatformKeySuffix()
      Gets the localization key suffix for the running platform for keybinding retrieval
      static void main​(java.lang.String[] args)
      Runs simple tests on KeyBindings keybinding values
      private static KeyBindings.KeyBindingInfo parseKeyBinding​(java.lang.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, java.lang.String localizationKey)
      Removes the keyboard accelerator for a SWT MenuItem
      private 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, 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
    • Field Detail

      • FUNC_EXP

        private static final java.util.regex.Pattern FUNC_EXP
      • SANCTIONED_EXP

        private static final java.util.regex.Pattern SANCTIONED_EXP
      • SPECIAL_KEYS

        private static final java.lang.String[] SPECIAL_KEYS
      • SPECIAL_VALUES

        private static final int[] SPECIAL_VALUES
    • Constructor Detail

      • KeyBindings

        public KeyBindings()
    • Method Detail

      • getPlatformKeySuffix

        private static java.lang.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​(java.lang.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,
                                             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
      • 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​(java.lang.String[] args)
        Runs simple tests on KeyBindings keybinding values
        Parameters:
        args - Command-line arguments; they are not used