Package docking.actions

Class KeyBindingUtils

  • public class KeyBindingUtils
extends java.lang.Object
    A class to provide utilities for system key bindings, such as importing and exporting key binding configurations.
    Since:
    Tracker Id 329

    • Method Summary

      All Methods Static Methods Concrete Methods 
      Modifier and Type Method Description
      static javax.swing.Action adaptDockingActionToNonContextAction​(DockingAction action)
      Takes the existing docking action and allows it to be registered with Swing components
      static void assertSameDefaultKeyBindings​(DockingActionIf newAction, java.util.Collection<DockingActionIf> existingActions)
      Checks each action in the given collection against the given new action to make sure that they share the same default key binding.
      static void clearKeyBinding​(javax.swing.JComponent component, DockingActionIf action)
      Allows the client to clear Java key bindings when the client is creating a docking action.
      static void clearKeyBinding​(javax.swing.JComponent component, javax.swing.KeyStroke keyStroke)
      Allows clients to clear Java key bindings.
      static void clearKeyBinding​(javax.swing.JComponent component, javax.swing.KeyStroke keyStroke, int focusCondition)
      Allows clients to clear Java key bindings.
      static ToolOptions createOptionsforKeybindings​(java.io.InputStream inputStream)
      Imports key bindings from a location selected by the user.
      static void exportKeyBindings​(ToolOptions keyBindingOptions)
      Saves the key bindings from the provided options object to a file chosen by the user.
      static javax.swing.Action getAction​(javax.swing.JComponent component, javax.swing.KeyStroke keyStroke, int focusCondition)
      Returns the registered action for the given keystroke, or null of no action is bound to that keystroke.
      static java.util.Set<DockingActionIf> getActions​(java.util.Set<DockingActionIf> allActions, java.lang.String owner, java.lang.String name)
      Returns all actions that match the given owner and name
      static java.util.Map<java.lang.String,​java.util.List<DockingActionIf>> getAllActionsByFullName​(DockingTool tool)
      A utility method to get all key binding actions.
      static java.util.Set<DockingActionIf> getKeyBindingActionsForOwner​(DockingTool tool, java.lang.String owner)
      A utility method to get all key binding actions that have the given owner.
      static ToolOptions importKeyBindings()  
      static void logDifferentKeyBindingsWarnigMessage​(DockingActionIf newAction, DockingActionIf existingAction, javax.swing.KeyStroke existingDefaultKs)
      Logs a warning message for the two given actions to signal that they do not share the same default key binding
      static javax.swing.KeyStroke parseKeyStroke​(java.lang.String keyStroke)
      Parses the given text into a KeyStroke.
      static java.lang.String parseKeyStroke​(javax.swing.KeyStroke keyStroke)
      Convert the toString() form of the keyStroke.
      static void registerAction​(javax.swing.JComponent component, DockingAction action)
      A convenience method to register the given action with the given component.
      static void registerAction​(javax.swing.JComponent component, DockingAction action, ActionContextProvider contextProvider)
      A convenience method to register the given action with the given component.
      static void registerAction​(javax.swing.JComponent component, DockingAction action, ActionContextProvider contextProvider, int focusCondition)
      A convenience method to register the given action with the given component.
      static void registerAction​(javax.swing.JComponent component, javax.swing.KeyStroke keyStroke, javax.swing.Action action, int focusCondition)
      Registers the given action with the given key binding on the given component.
      static javax.swing.KeyStroke validateKeyStroke​(javax.swing.KeyStroke keyStroke)
      Updates the given data with system-independent versions of key modifiers.

      • Methods inherited from class java.lang.Object

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

    • Field Detail

      • PREFERENCES_FILE_EXTENSION

        public static final java.lang.String PREFERENCES_FILE_EXTENSION
        See Also:
        Constant Field Values

    • Method Detail

      • importKeyBindings

        public static ToolOptions importKeyBindings()

      • createOptionsforKeybindings

        public static ToolOptions createOptionsforKeybindings​(java.io.InputStream inputStream)
        Imports key bindings from a location selected by the user.

        If there is a problem reading the data then the user will be shown an error dialog.

        Parameters:
        inputStream - the input stream from which to read options
        Returns:
        An options object that is composed of key binding names and their associated keystrokes.

      • exportKeyBindings

        public static void exportKeyBindings​(ToolOptions keyBindingOptions)
        Saves the key bindings from the provided options object to a file chosen by the user.

        If there is a problem writing the data then the user will be shown an error dialog.

        Parameters:
        keyBindingOptions - The options that contains key binding data.

      • registerAction

        public static void registerAction​(javax.swing.JComponent component,
                                  DockingAction action)
        A convenience method to register the given action with the given component. This is not usually done, as the action system is usually managed by the application's tool. However, for actions that are not registered with a tool, they can instead be bound to a component, hence this method.

        The given action must have a keystroke assigned, or this method will do nothing.

        Parameters:
        component - the component to which the given action will be bound
        action - the action to bind

      • registerAction

        public static void registerAction​(javax.swing.JComponent component,
                                  DockingAction action,
                                  ActionContextProvider contextProvider)
        A convenience method to register the given action with the given component. This is not usually done, as the action system is usually managed by the application's tool. However, for actions that are not registered with a tool, they can instead be bound to a component, hence this method.

        The given action must have a keystroke assigned, or this method will do nothing.

        A typical use-case is to register an existing docking action with a text component, which is needed because the docking key event processing will not execute docking- registered actions if a text component has focus.

        Parameters:
        component - the component to which the given action will be bound
        action - the action to bind
        contextProvider - the provider of the context

      • registerAction

        public static void registerAction​(javax.swing.JComponent component,
                                  DockingAction action,
                                  ActionContextProvider contextProvider,
                                  int focusCondition)
        A convenience method to register the given action with the given component. This is not usually done, as the action system is usually managed by the application's tool. However, for actions that are not registered with a tool, they can instead be bound to a component, hence this method.

        The given action must have a keystroke assigned, or this method will do nothing.

        A typical use-case is to register an existing docking action with a text component, which is needed because the docking key event processing will not execute docking- registered actions if a text component has focus.

        Parameters:
        component - the component to which the given action will be bound
        action - the action to bind
        contextProvider - the provider of the context
        focusCondition - see JComponent for more info; the default is usually JComponent.WHEN_FOCUSED

      • registerAction

        public static void registerAction​(javax.swing.JComponent component,
                                  javax.swing.KeyStroke keyStroke,
                                  javax.swing.Action action,
                                  int focusCondition)
        Registers the given action with the given key binding on the given component.
        Parameters:
        component - the component to which the action will be registered
        keyStroke - the keystroke for to which the action will be bound
        action - the action to execute when the given keystroke is triggered
        focusCondition - the focus condition under which to bind the action (JComponent.getInputMap(int)). See JComponent for more info; the default is usually JComponent.WHEN_FOCUSED

      • clearKeyBinding

        public static void clearKeyBinding​(javax.swing.JComponent component,
                                   DockingActionIf action)
        Allows the client to clear Java key bindings when the client is creating a docking action. Without this call, any actions bound to the given component will prevent an action with the same key binding from firing. This is useful when your application is using tool-level key bindings that share the same keystroke as a built-in Java action, such as Ctrl-C for the copy action.
        Parameters:
        component - the component for which to clear the key binding
        action - the action from which to get the key binding

      • clearKeyBinding

        public static void clearKeyBinding​(javax.swing.JComponent component,
                                   javax.swing.KeyStroke keyStroke)
        Allows clients to clear Java key bindings. This is useful when your application is using tool-level key bindings that share the same keystroke as a built-in Java action, such as Ctrl-C for the copy action.

        Note: this method clears the key binding for the JComponent.WHEN_FOCUSED and JComponent.WHEN_ANCESTOR_OF_FOCUSED_COMPONENT focus conditions.

        Parameters:
        component - the component for which to clear the key binding
        keyStroke - the keystroke of the binding to be cleared
        See Also:
        clearKeyBinding(JComponent, KeyStroke, int)

      • clearKeyBinding

        public static void clearKeyBinding​(javax.swing.JComponent component,
                                   javax.swing.KeyStroke keyStroke,
                                   int focusCondition)
        Allows clients to clear Java key bindings. This is useful when your application is using tool-level key bindings that share the same keystroke as a built-in Java action, such as Ctrl-C for the copy action.
        Parameters:
        component - the component for which to clear the key binding
        keyStroke - the keystroke of the binding to be cleared
        focusCondition - the particular focus condition under which the given keystroke is used (see JComponent.getInputMap(int)).

      • getAction

        public static javax.swing.Action getAction​(javax.swing.JComponent component,
                                           javax.swing.KeyStroke keyStroke,
                                           int focusCondition)
        Returns the registered action for the given keystroke, or null of no action is bound to that keystroke.
        Parameters:
        component - the component for which to check the binding
        keyStroke - the keystroke for which to find a bound action
        focusCondition - the focus condition under which to check for the binding (JComponent.getInputMap(int))
        Returns:
        the action registered to the given keystroke, or null of no action is registered

      • getAllActionsByFullName

        public static java.util.Map<java.lang.String,​java.util.List<DockingActionIf>> getAllActionsByFullName​(DockingTool tool)
        A utility method to get all key binding actions. This method will only return actions that support key bindings.

        The mapping returned provides a list of items because it is possible for there to exists multiple actions with the same name and owner. (This can happen when multiple copies of a component provider are shown, each with their own set of actions that share the same name.)

        Parameters:
        tool - the tool containing the actions
        Returns:
        the actions mapped by their full name (e.g., 'Name (OwnerName)')

      • getKeyBindingActionsForOwner

        public static java.util.Set<DockingActionIf> getKeyBindingActionsForOwner​(DockingTool tool,
                                                                          java.lang.String owner)
        A utility method to get all key binding actions that have the given owner. This method will remove duplicate actions and will only return actions that support key bindings.
        Parameters:
        tool - the tool containing the actions
        owner - the action owner name
        Returns:
        the actions

      • getActions

        public static java.util.Set<DockingActionIf> getActions​(java.util.Set<DockingActionIf> allActions,
                                                        java.lang.String owner,
                                                        java.lang.String name)
        Returns all actions that match the given owner and name
        Parameters:
        allActions - the universe of actions
        owner - the owner
        name - the name
        Returns:
        the actions

      • adaptDockingActionToNonContextAction

        public static javax.swing.Action adaptDockingActionToNonContextAction​(DockingAction action)
        Takes the existing docking action and allows it to be registered with Swing components

        The new action will not be correctly wired into the Docking Action Context system. This means that the given docking action should not rely on DockingAction.isEnabledForContext(docking.ActionContext) to work when called from the Swing widget.

        Parameters:
        action - the docking action to adapt to a Swing Action
        Returns:
        the new action

      • assertSameDefaultKeyBindings

        public static void assertSameDefaultKeyBindings​(DockingActionIf newAction,
                                                java.util.Collection<DockingActionIf> existingActions)
        Checks each action in the given collection against the given new action to make sure that they share the same default key binding.
        Parameters:
        newAction - the action to check
        existingActions - the actions that have already been checked

      • logDifferentKeyBindingsWarnigMessage

        public static void logDifferentKeyBindingsWarnigMessage​(DockingActionIf newAction,
                                                        DockingActionIf existingAction,
                                                        javax.swing.KeyStroke existingDefaultKs)
        Logs a warning message for the two given actions to signal that they do not share the same default key binding
        Parameters:
        newAction - the new action
        existingAction - the action that has already been validated
        existingDefaultKs - the current validated key stroke

      • validateKeyStroke

        public static javax.swing.KeyStroke validateKeyStroke​(javax.swing.KeyStroke keyStroke)
        Updates the given data with system-independent versions of key modifiers. For example, the control key will be converted to the command key on the Mac.
        Parameters:
        keyStroke - the keystroke to validate
        Returns:
        the potentially changed keystroke

      • parseKeyStroke

        public static java.lang.String parseKeyStroke​(javax.swing.KeyStroke keyStroke)
        Convert the toString() form of the keyStroke.
        In Java 1.4.2 & earlier, Ctrl-M is returned as "keyCode CtrlM-P" and we want it to look like: "Ctrl-M".
        In Java 1.5.0, Ctrl-M is returned as "ctrl pressed M" and we want it to look like: "Ctrl-M".
        Parameters:
        keyStroke - the key stroke
        Returns:
        the string value; the empty string if the key stroke is null

      • parseKeyStroke

        public static javax.swing.KeyStroke parseKeyStroke​(java.lang.String keyStroke)
        Parses the given text into a KeyStroke. This method relies upon KeyStroke.getKeyStroke(String) for parsing. Before making that call, this method will perform fixup on the given text for added flexibility. For example, the given text may contain spaces or dashes as the separators between parts in the string. Also, the text is converted such that it is not case-sensitive. So, the following example formats are allowed: 
            Alt-F
    alt p
    Ctrl-Alt-Z
    ctrl Z
        Parameters:
        keyStroke -
        Returns:
        the new key stroke (as returned by KeyStroke.getKeyStroke(String)