Class InputMap

java.lang.Object
jfx.incubator.scene.control.input.InputMap
public final class InputMap extends Object
InputMap is a property of the Control class which enables customization by allowing creation of custom key mappings and event handlers.

The InputMap serves as a bridge between the Control and its Skin. The InputMap provides an ordered repository of event handlers, working together with the input map managed by the skin, which guarantees the order in which handlers are invoked. It also stores key mappings with a similar guarantee that the application mappings always take precedence over mappings created by the skin, regardless of when the skin was created or replaced.

The class supports the following scenarios:

  • Mapping a key binding to a function
  • Removing a key binding
  • Mapping a new function to an existing key binding
  • Retrieving the default function
  • Ensuring that the application key mappings take priority over mappings created by the skin
For key mappings, the InputMap utilizes a two-stage lookup. First, the key event is matched to a FunctionTag which identifies a function provided either by the skin or the associated behavior (the "default" function), or by the application. When such a mapping exists, the found function tag is matched to a function registered either by the application or by the skin.

Additionally, the register(KeyBinding, Runnable) method allows mapping to a function directly, bypassing the function tag.

This mechanism allows for customizing the key mappings and the underlying functions independently and separately.

Since:
24

  • Constructor Details

    • InputMap

      public InputMap(Control control)
      The constructor.
      Parameters:
      control - the owner control

  • Method Details

    • addHandler

      public <T extends Event> void addHandler(EventType<T> type, EventHandler<T> handler)
      Adds an event handler for the specified event type. Event handlers added with this method will always be called before any handlers registered by the skin.
      Type Parameters:
      T - the actual event type
      Parameters:
      type - the event type
      handler - the event handler

    • removeHandler

      public <T extends Event> void removeHandler(EventType<T> type, EventHandler<T> handler)
      Removes the specified handler.
      Type Parameters:
      T - the event class
      Parameters:
      type - the event type
      handler - the handler to remove

    • register

      public void register(KeyBinding k, Runnable function)
      Registers a function for the given key binding. This mapping will take precedence over the default mapping set by the skin.
      Parameters:
      k - the key binding
      function - the function

    • registerFunction

      public void registerFunction(FunctionTag tag, Runnable function)
      Adds (or overrides) a user-specified function under the given function tag. This function will take precedence over any default function set by the skin.
      Parameters:
      tag - the function tag
      function - the function

    • registerKey

      public void registerKey(KeyBinding k, FunctionTag tag)
      Link a key binding to the specified function tag. When the key binding matches the input event, the function is executed, the event is consumed, and the process of dispatching is stopped.

      This method will take precedence over any default function set by the skin.

      Parameters:
      k - the key binding
      tag - the function tag

    • disableKeyBinding

      public void disableKeyBinding(KeyBinding k)
      Disables the specified key binding. Calling this method will disable any mappings made with register(KeyBinding, Runnable), registerKey(KeyBinding, FunctionTag), or registered by the skin.
      Parameters:
      k - the key binding

    • resetKeyBindings

      public void resetKeyBindings()
      Reverts all the key bindings set by user. This method restores key bindings set by the skin which were overwritten by the user.

    • restoreDefaultKeyBinding

      public void restoreDefaultKeyBinding(KeyBinding k)
      Restores the specified key binding to the value set by the skin, if any.
      Parameters:
      k - the key binding

    • restoreDefaultFunction

      public void restoreDefaultFunction(FunctionTag tag)
      Restores the specified function tag to the value set by the skin, if any.
      Parameters:
      tag - the function tag

    • getKeyBindings

      public Set<KeyBinding> getKeyBindings()
      Collects all mapped key bindings.
      Returns:
      the set of key bindings

    • getKeyBindingsFor

      public Set<KeyBinding> getKeyBindingsFor(FunctionTag tag)
      Returns the set of key bindings mapped to the specified function tag.
      Parameters:
      tag - the function tag
      Returns:
      the set of KeyBindings, non-null

    • removeKeyBindingsFor

      public void removeKeyBindingsFor(FunctionTag tag)
      Removes all the key bindings mapped to the specified function tag, either by the application or by the skin. This is an irreversible operation.
      Parameters:
      tag - the function tag