Package docking.actions

Class KeyBindingUtils

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

  • Field Details

  • Method Details

    • importKeyBindings

      public static ToolOptions importKeyBindings()

    • createOptionsforKeybindings

      public static ToolOptions createOptionsforKeybindings(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.

    • retargetEvent

      public static void retargetEvent(Component newSource, KeyEvent e)
      Changes the given key event to the new source component and then dispatches that event. This method is intended for clients that wish to effectively take a key event given to one component and give it to another component.

      This method exists to deal with the complicated nature of key event processing and how our (not Java's) framework processes key event bindings to trigger actions. If not for our special processing of action key bindings, then this method would not be necessary.

      This is seldom-used code; if you don't know when to use this code, then don't.

      Parameters:
      newSource - the new target of the event
      e - the existing event

    • registerAction

      public static void registerAction(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(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(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(JComponent component, KeyStroke keyStroke, 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(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(JComponent component, 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

      public static void clearKeyBinding(JComponent component, 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)).

    • clearKeyBinding

      public static void clearKeyBinding(JComponent component, String actionName)
      Clears the currently assigned Java key binding for the action by the given name. This method will find the currently assigned key binding, if any, and then remove it.
      Parameters:
      component - the component for which to clear the key binding
      actionName - the name of the action that should not have a key binding
      See Also:

    • getAction

      public static Action getAction(JComponent component, 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 Map<String,List<DockingActionIf>> getAllActionsByFullName(Tool 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 Set<DockingActionIf> getKeyBindingActionsForOwner(Tool tool, 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 Set<DockingActionIf> getActions(Set<DockingActionIf> allActions, String owner, 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 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

    • validateKeyStroke

      public static KeyStroke validateKeyStroke(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 String parseKeyStroke(KeyStroke keyStroke)
      Convert the toString() form of the keyStroke.
      In Java 1.4.2 and 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".
      In Java 11 we have seen toString() values get printed with repeated text, such as: "shift ctrl pressed SHIFT". We want to trim off the repeated modifiers.
      Parameters:
      keyStroke - the key stroke
      Returns:
      the string value; the empty string if the key stroke is null

    • parseKeyStroke

      public static KeyStroke parseKeyStroke(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

      Note: The returned keystroke will always correspond to a pressed event, regardless of the value passed in (pressed, typed or released).

      Parameters:
      keyStroke - the key stroke
      Returns:
      the new key stroke (as returned by KeyStroke.getKeyStroke(String)