Pattern matching for Events.

General Concept as an Analogy

Think of an InputMap as a powerful switch statement:

switch (eventType) {
    case KEY_PRESSED:    // the basic EventPattern
         doCodeWithEvent(e); // the basic InputHandler
         break;

    // an EventPattern with a condition
    // it only matches KeyTyped events whose text is a space character
    // other KeyTyped events don't run the space insertion code beow
    case KEY_TYPED e if e.getText().equals(" "):
         addSpaceToText();
         break;

    // an EventPattern with another condition
    case MOUSE_MOVED && otherNode.isVisible():
         otherNode.hide();
         thirdNode.show();
         break;

    // runs the same behavior for multiple event types
    case MOUSE_PRESSED || MOUSE_RELEASED || MOUSE_DRAGGED || MOUSE_ENTERED_TARGET:
         showPopupThatSays("You did something with the mouse!")

    // sometimes there is no "default" behavior and the event bubbles back up
    default:
         break;
}

Types of InputMaps

There are a few types of InputMaps:

• The base ones: ignore(EventType), consume(EventType), and process(EventType, Function) (and all their variations).
• The composable ones: sequence(InputMap[])/orElse(InputMap), upCast(InputMap), and without(InputMap).
• The condition-adding ones: when(BooleanSupplier, InputMap) and unless(BooleanSupplier, InputMap)
• (convenience) Consume with conditions: consumeWhen(EventType, BooleanSupplier, Consumer) and consumeUnless(EventType, BooleanSupplier, Consumer)
• The post-conditions: ifIgnored(Consumer), ifProcessed(Consumer), ifConsumed(Consumer).

Examples

InputMap<KeyEvent> typeTheLetter = consume(
     // event pattern (e.g. the "case" line in a switch statement)
     keyTyped(),

     // input handler (e.g. the "block of code" for a case in a switch statement
     e -> textField.addLetter(e.getText)
);

InputMap<KeyEvent> copy = consume(
     anyOf(
         keyPressed(KeyCode.C, KeyCode.SHORTCUT),
         keyPressed(KeyCode.COPY)
     ),
     e -> textField.copyToClipboard()
);

InputMap<KeyEvent> pasteThenClearTextField = consume(
     // event pattern
     anyOf(
         keyPressed(KeyCode.V, KeyCode.SHORTCUT),
         keyPressed(KeyCode.PASTE)
     ),
     e -> textField.copyToClipboard()
).ifConsumed(ignoreMe -> textField.clearText();

InputMap<CustomEvent> someCustomEventInputMap = // imagine I put something here...

// notice the very generic "Event" event type
InputMap<? super Event> allBehaviorForCustomTextField = sequence(
     // when an event occurs, check whether the below input map's EventPattern matches the given event
     typeTheLetter,
     // only pattern match against the below input map if the previous one didn't match
     copy,
     // check this one only if the above two didn't match
     pasteThenClearTextField,

     someCustomEventInputMap

     // If reach this part, none of them matched, so do nothing
);

// at this point, "allBehaviorForCustomTextField" could be installed into a Node
Nodes.addFallbackInputMap(node, allBehaviorForCustomTextField);

// when user types a letter, the text field adds that letter
// when user moves the mouse over the text field, nothing happens

Last Words

When creating a subclass of a node that will be instantiated multiple times, use org.fxmisc.wellbehaved.event.template.InputMapTemplate to create an InputMap for each created javafx.scene.Node as this saves some memory. See the template class' javadoc for more details.