KeyCombination (JavaFX 13)

Module javafx.graphics
Package javafx.scene.input

## Class KeyCombination

- java.lang.Object
- - javafx.scene.input.KeyCombination

- Direct Known Subclasses:
    `KeyCharacterCombination`, `KeyCodeCombination`

      public abstract class KeyCombination
      extends Object

  Represents a combination of keys which are used in keyboard shortcuts. A key combination consists of a main key and a set of modifier keys. The main key can be specified by its key code - `KeyCodeCombination` or key character - `KeyCharacterCombination`. A modifier key is `shift`, `control`, `alt`, `meta` or `shortcut` and can be defined as `DOWN`, `UP` or `ANY`.

  The `shortcut` modifier is used to represent the modifier key which is used commonly in keyboard shortcuts on the host platform. This is for example `control` on Windows and `meta` (command key) on Mac. By using `shortcut` key modifier developers can create platform independent shortcuts. So the "Shortcut+C" key combination is handled internally as "Ctrl+C" on Windows and "Meta+C" on Mac.

  Since:
    JavaFX 2.0

- - ### Nested Class Summary

    Nested Classes
    Modifier and Type | Class | Description
    --- | --- | ---
    `static class` | `KeyCombination.Modifier` | This class represents a pair of modifier key and its value.
    `static class` | `KeyCombination.ModifierValue` | `ModifierValue` specifies state of modifier keys.

  - ### Field Summary

    Fields
    Modifier and Type | Field | Description
    --- | --- | ---
    `static KeyCombination.Modifier` | `ALT_ANY` | Modifier which specifies that the `alt` key can be either up or down.
    `static KeyCombination.Modifier` | `ALT_DOWN` | Modifier which specifies that the `alt` key must be down.
    `static KeyCombination.Modifier` | `CONTROL_ANY` | Modifier which specifies that the `control` key can be either up or down.
    `static KeyCombination.Modifier` | `CONTROL_DOWN` | Modifier which specifies that the `control` key must be down.
    `static KeyCombination.Modifier` | `META_ANY` | Modifier which specifies that the `meta` key can be either up or down.
    `static KeyCombination.Modifier` | `META_DOWN` | Modifier which specifies that the `meta` key must be down.
    `static KeyCombination` | `NO_MATCH` | A KeyCombination that will match with no events.
    `static KeyCombination.Modifier` | `SHIFT_ANY` | Modifier which specifies that the `shift` key can be either up or down.
    `static KeyCombination.Modifier` | `SHIFT_DOWN` | Modifier which specifies that the `shift` key must be down.
    `static KeyCombination.Modifier` | `SHORTCUT_ANY` | Modifier which specifies that the `shortcut` key can be either up or down.
    `static KeyCombination.Modifier` | `SHORTCUT_DOWN` | Modifier which specifies that the `shortcut` key must be down.

  - ### Constructor Summary

    Constructors
    Modifier | Constructor | Description
    --- | --- | ---
    `protected` | `KeyCombination​(KeyCombination.Modifier... modifiers)` | Constructs a `KeyCombination` with the specified list of modifiers.
    `protected` | `KeyCombination​(KeyCombination.ModifierValue shift, KeyCombination.ModifierValue control, KeyCombination.ModifierValue alt, KeyCombination.ModifierValue meta, KeyCombination.ModifierValue shortcut)` | Constructs a `KeyCombination` with an explicit specification of all modifier keys.

  - ### Method Summary

    All Methods Static Methods Instance Methods Concrete Methods
    Modifier and Type | Method | Description
    --- | --- | ---
    `boolean` | `equals​(Object obj)` | Tests whether this `KeyCombination` equals to the specified object.
    `KeyCombination.ModifierValue` | `getAlt()` | The state of the `alt` key in this key combination.
    `KeyCombination.ModifierValue` | `getControl()` | The state of the `control` key in this key combination.
    `String` | `getDisplayText()` | Returns a string representation of this `KeyCombination` that is suitable for display in a user interface (for example, beside a menu item).
    `KeyCombination.ModifierValue` | `getMeta()` | The state of the `meta` key in this key combination.
    `String` | `getName()` | Returns a string representation of this `KeyCombination`.
    `KeyCombination.ModifierValue` | `getShift()` | The state of the `shift` key in this key combination.
    `KeyCombination.ModifierValue` | `getShortcut()` | The state of the `shortcut` key in this key combination.
    `int` | `hashCode()` | Returns a hash code value for this `KeyCombination`.
    `static KeyCombination` | `keyCombination​(String name)` | Constructs a new `KeyCombination` from the specified string.
    `boolean` | `match​(KeyEvent event)` | Tests whether this key combination matches the combination in the given `KeyEvent`.
    `String` | `toString()` | Returns a string representation of this object.
    `static KeyCombination` | `valueOf​(String value)` | Constructs a new `KeyCombination` from the specified string.

    - ### Methods inherited from class java.lang.Object

      `clone, finalize, getClass, notify, notifyAll, wait, wait, wait`

- - ### Field Detail

    - #### SHIFT_DOWN

          public static final KeyCombination.Modifier SHIFT_DOWN

      Modifier which specifies that the `shift` key must be down.

    - #### SHIFT_ANY

          public static final KeyCombination.Modifier SHIFT_ANY

      Modifier which specifies that the `shift` key can be either up or down.

    - #### CONTROL_DOWN

          public static final KeyCombination.Modifier CONTROL_DOWN

      Modifier which specifies that the `control` key must be down.

    - #### CONTROL_ANY

          public static final KeyCombination.Modifier CONTROL_ANY

      Modifier which specifies that the `control` key can be either up or down.

    - #### ALT_DOWN

          public static final KeyCombination.Modifier ALT_DOWN

      Modifier which specifies that the `alt` key must be down.

    - #### ALT_ANY

          public static final KeyCombination.Modifier ALT_ANY

      Modifier which specifies that the `alt` key can be either up or down.

    - #### META_DOWN

          public static final KeyCombination.Modifier META_DOWN

      Modifier which specifies that the `meta` key must be down.

    - #### META_ANY

          public static final KeyCombination.Modifier META_ANY

      Modifier which specifies that the `meta` key can be either up or down.

    - #### SHORTCUT_DOWN

          public static final KeyCombination.Modifier SHORTCUT_DOWN

      Modifier which specifies that the `shortcut` key must be down.

    - #### SHORTCUT_ANY

          public static final KeyCombination.Modifier SHORTCUT_ANY

      Modifier which specifies that the `shortcut` key can be either up or down.

    - #### NO_MATCH

          public static final KeyCombination NO_MATCH

      A KeyCombination that will match with no events.

  - ### Constructor Detail

    - #### KeyCombination

          protected KeyCombination​(KeyCombination.ModifierValue shift,
                                   KeyCombination.ModifierValue control,
                                   KeyCombination.ModifierValue alt,
                                   KeyCombination.ModifierValue meta,
                                   KeyCombination.ModifierValue shortcut)

      Constructs a `KeyCombination` with an explicit specification of all modifier keys. Each modifier key can be set to `DOWN`, `UP` or `ANY`.
      Parameters:
        `shift` - the value of the `shift` modifier key
        `control` - the value of the `control` modifier key
        `alt` - the value of the `alt` modifier key
        `meta` - the value of the `meta` modifier key
        `shortcut` - the value of the `shortcut` modifier key

    - #### KeyCombination

          protected KeyCombination​(KeyCombination.Modifier... modifiers)

      Constructs a `KeyCombination` with the specified list of modifiers. All modifier keys which are not explicitly listed are set to the default `UP` value.

      All possible modifiers which change the default modifier value are defined as constants in the `KeyCombination` class.

      Parameters:
        `modifiers` - the list of modifier keys and their corresponding values

  - ### Method Detail

    - #### getShift

          public final KeyCombination.ModifierValue getShift()

      The state of the `shift` key in this key combination.
      Returns:
        The state of the `shift` key in this key combination

    - #### getControl

          public final KeyCombination.ModifierValue getControl()

      The state of the `control` key in this key combination.
      Returns:
        The state of the `control` key in this key combination

    - #### getAlt

          public final KeyCombination.ModifierValue getAlt()

      The state of the `alt` key in this key combination.
      Returns:
        The state of the `alt` key in this key combination.

    - #### getMeta

          public final KeyCombination.ModifierValue getMeta()

      The state of the `meta` key in this key combination.
      Returns:
        The state of the `meta` key in this key combination

    - #### getShortcut

          public final KeyCombination.ModifierValue getShortcut()

      The state of the `shortcut` key in this key combination.
      Returns:
        The state of the `shortcut` key in this key combination

    - #### match

          public boolean match​(KeyEvent event)

      Tests whether this key combination matches the combination in the given `KeyEvent`.

      The implementation of this method in the `KeyCombination` class does only a partial test with the modifier keys. This method is overridden in subclasses to include the main key in the test.

      Parameters:
        `event` - the key event
      Returns:
        `true` if the key combinations match, `false` otherwise

    - #### getName

          public String getName()

      Returns a string representation of this `KeyCombination`.

      The string representation consists of sections separated by plus characters. Each section specifies either a modifier key or the main key.

      A modifier key section contains the `KeyCode` name of a modifier key. It can be prefixed with the `Ignored` keyword. A non-prefixed modifier key implies its `DOWN` value while the prefixed version implies the `ANY` (ignored) value. If some modifier key is not specified in the string at all, it means it has the default `UP` value.

      The format of the main key section of the key combination string depends on the `KeyCombination` subclass. It is either the key code name for `KeyCodeCombination` or the single quoted key character for `KeyCharacterCombination`.

      Examples of `KeyCombination` string representations:

          "Ctrl+Alt+Q"
          "Ignore Shift+Ctrl+A"
          "Alt+'w'"

      Returns:
        the string representation of this `KeyCombination`

    - #### getDisplayText

          public String getDisplayText()

      Returns a string representation of this `KeyCombination` that is suitable for display in a user interface (for example, beside a menu item).
      Returns:
        A string representation of this `KeyCombination`, suitable for display in a user interface.
      Since:
        JavaFX 8u20

    - #### equals

          public boolean equals​(Object obj)

      Tests whether this `KeyCombination` equals to the specified object.
      Overrides:
        `equals` in class `Object`
      Parameters:
        `obj` - the object to compare to
      Returns:
        `true` if the objects are equal, `false` otherwise

    - #### hashCode

          public int hashCode()

      Returns a hash code value for this `KeyCombination`.
      Overrides:
        `hashCode` in class `Object`
      Returns:
        the hash code value

    - #### toString

          public String toString()

      Returns a string representation of this object. Implementation returns the result of the `getName()` call.
      Overrides:
        `toString` in class `Object`
      Returns:
        the string representation of this `KeyCombination`

    - #### valueOf

          public static KeyCombination valueOf​(String value)

      Constructs a new `KeyCombination` from the specified string. The string should be in the same format as produced by the `getName` method.

      If the main key section string is quoted in single quotes the method creates a new `KeyCharacterCombination` for the unquoted substring. Otherwise it finds the key code which name corresponds to the main key section string and creates a `KeyCodeCombination` for it. If this can't be done, it falls back to the `KeyCharacterCombination`.

      Parameters:
        `value` - the string which represents the requested key combination
      Returns:
        the constructed `KeyCombination`
      Since:
        JavaFX 2.1

    - #### keyCombination

          public static KeyCombination keyCombination​(String name)

      Constructs a new `KeyCombination` from the specified string. This method simply delegates to `valueOf(String)`.
      Parameters:
        `name` - the string which represents the requested key combination
      Returns:
        the constructed `KeyCombination`
      See Also:
        `valueOf(String)`