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 final class`
  `KeyCombination.Modifier`
  This class represents a pair of modifier key and its value.
  `static enum`
  `KeyCombination.ModifierValue`
  `ModifierValue` specifies state of modifier keys.

- ## Field Summary

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

  Modifier and Type
  Method
  Description
  `boolean`
  `equals(Object obj)`
  Tests whether this `KeyCombination` equals to the specified object.
  `final KeyCombination.ModifierValue`
  `getAlt()`
  The state of the `alt` key in this key combination.
  `final 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).
  `final KeyCombination.ModifierValue`
  `getMeta()`
  The state of the `meta` key in this key combination.
  `String`
  `getName()`
  Returns a string representation of this `KeyCombination`.
  `final KeyCombination.ModifierValue`
  `getShift()`
  The state of the `shift` key in this key combination.
  `final 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 declared in class java.lang.Object

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

- ## Field Details

  - ### 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 Details

  - ### 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 Details

  - ### 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)`