Package docking.actions

Class KeyBindingUtils

java.lang.Object

docking.actions.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

Field Summary

Fields

Modifier and Type	Field	Description
static java.lang.String	PREFERENCES_FILE_EXTENSION

Method Summary

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, java.lang.String actionName)	Clears the currently assigned Java key binding for the action by the given name.
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(Tool tool)	A utility method to get all key binding actions.
static java.util.Set<DockingActionIf>	getKeyBindingActionsForOwner(Tool 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 void	retargetEvent(java.awt.Component newSource, java.awt.event.KeyEvent e)	Changes the given key event to the new source component and then dispatches that event.
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.

retargetEvent

public static void retargetEvent(java.awt.Component newSource,
                                 java.awt.event.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(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)).

clearKeyBinding

public static void clearKeyBinding(javax.swing.JComponent component,
                                   java.lang.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:

LookAndFeel

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(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 java.util.Set<DockingActionIf> getKeyBindingActionsForOwner(Tool 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 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 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
 

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)