org.fxmisc.wellbehaved.event

Interface InputMap<E extends javafx.event.Event>

Type Parameters:

E - type of events that this InputMap may handle. That is, InputMap<E> certainly does not handle any events that are not of type E; it does not mean it handles any event of type E.

Functional Interface:

This is a functional interface and can therefore be used as the assignment target for a lambda expression or method reference.

@FunctionalInterface
public interface InputMap<E extends javafx.event.Event>

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 InputMapTemplate to create an InputMap for each created Node as this saves some memory. See the template class' javadoc for more details.

Nested Class Summary

Nested Classes

Modifier and Type	Interface and Description
static interface	InputMap.HandlerConsumer<E extends javafx.event.Event>

Field Summary

Fields

Modifier and Type	Field and Description
static InputMap<?>	EMPTY

Method Summary

Modifier and Type	Method and Description
static <T extends javafx.event.Event,U extends T> InputMap<U>	consume(EventPattern<? super T,? extends U> eventPattern) If the given EventPattern matches the given event type, consumes the event and does not attempt to match additional InputMaps (if they exist).
static <T extends javafx.event.Event,U extends T> InputMap<U>	consume(EventPattern<? super T,? extends U> eventPattern, java.util.function.Consumer<? super U> action) If the given EventPattern matches the given event type, runs the given action, consumes the event, and does not attempt to match additional InputMaps (if they exist).
static <T extends javafx.event.Event> InputMap<T>	consume(javafx.event.EventType<? extends T> eventType) When the given event type occurs, consumes the event and does not attempt to match additional InputMaps (if they exist).
static <T extends javafx.event.Event> InputMap<T>	consume(javafx.event.EventType<? extends T> eventType, java.util.function.Consumer<? super T> action) When the given event type occurs, runs the given action, consumes the event, and does not attempt to match additional InputMaps (if they exist).
static <T extends javafx.event.Event,U extends T> InputMap<U>	consumeUnless(EventPattern<? super T,? extends U> eventPattern, java.util.function.BooleanSupplier condition, java.util.function.Consumer<? super U> action) If the given EventPattern matches the given event type and condition is false, consumes the event and does not attempt to match additional InputMaps (if they exist).
static <T extends javafx.event.Event> InputMap<T>	consumeUnless(javafx.event.EventType<? extends T> eventType, java.util.function.BooleanSupplier condition, java.util.function.Consumer<? super T> action) When the given event type occurs and condition is false, consumes the event and does not attempt to match additional InputMaps (if they exist).
static <T extends javafx.event.Event,U extends T> InputMap<U>	consumeWhen(EventPattern<? super T,? extends U> eventPattern, java.util.function.BooleanSupplier condition, java.util.function.Consumer<? super U> action) If the given EventPattern matches the given event type and condition is true, consumes the event and does not attempt to match additional InputMaps (if they exist).
static <T extends javafx.event.Event> InputMap<T>	consumeWhen(javafx.event.EventType<? extends T> eventType, java.util.function.BooleanSupplier condition, java.util.function.Consumer<? super T> action) When the given event type occurs and condition is true, consumes the event and does not attempt to match additional InputMaps (if they exist).
static <E extends javafx.event.Event> InputMap<E>	empty()
void	forEachEventType(InputMap.HandlerConsumer<? super E> f) For each EventPattern that matches the given event, run the corresponding InputHandler
default InputMap<E>	ifConsumed(java.util.function.Consumer<? super E> postConsumption) Executes some additional handler if the event was consumed (e.g.
default InputMap<E>	ifIgnored(java.util.function.Consumer<? super E> postIgnore) Executes some additional handler if the event was ignored (e.g.
default InputMap<E>	ifProcessed(java.util.function.Consumer<? super E> postProceed) Executes some additional handler if the event was matched but not consumed (e.g.
static <T extends javafx.event.Event,U extends T> InputMap<U>	ignore(EventPattern<? super T,? extends U> eventPattern) If the given EventPattern matches the given event type, does nothing and does not attempt to match additional InputMaps (if they exist).
static <T extends javafx.event.Event> InputMap<T>	ignore(javafx.event.EventType<? extends T> eventType) When the given event type occurs, does nothing and does not attempt to match additional InputMaps (if they exist).
default InputMap<E>	orElse(InputMap<? extends E> that) Shorthand for sequence(this, that)
static <E extends javafx.event.Event> InputMap<E>	postResult(InputMap<? extends E> map, InputHandler.Result checkedResult, java.util.function.Consumer<? super E> postDesiredResult)
static <T extends javafx.event.Event,U extends T> InputMap<U>	process(EventPattern<? super T,? extends U> eventPattern, java.util.function.Function<? super U,InputHandler.Result> action) If the given EventPattern matches the given event type, runs the given action, and then attempts to pattern match the event type with the next InputMap (if one exists).
static <T extends javafx.event.Event> InputMap<T>	process(javafx.event.EventType<? extends T> eventType, java.util.function.Function<? super T,InputHandler.Result> action) When the given event type occurs, runs the given action, and then attempts to pattern match the event type with the next InputMap (if one exists).
static <E extends javafx.event.Event> InputMap<E>	sequence(InputMap<? extends E>... inputMaps) Creates a single InputMap that pattern matches a given event type against all the given input maps.
static <T extends javafx.event.Event> InputMap<T>	unless(java.util.function.BooleanSupplier condition, InputMap<T> im) When the given condition is false, pattern matches the event with the given InputMap or proceeds to the next InputMap (if it exists).
static <E extends javafx.event.Event> InputMap<E>	upCast(InputMap<? extends E> inputMap)
static <T extends javafx.event.Event> InputMap<T>	when(java.util.function.BooleanSupplier condition, InputMap<T> im) When the given condition is true, pattern matches the event with the given InputMap or proceeds to the next InputMap (if it exists).
default InputMap<E>	without(InputMap<?> that) Returns an InputMap that does nothing when this.equals(that); otherwise, returns this input map.

Field Detail

EMPTY

static final InputMap<?> EMPTY

Method Detail

empty

static <E extends javafx.event.Event> InputMap<E> empty()

forEachEventType

void forEachEventType(InputMap.HandlerConsumer<? super E> f)

For each EventPattern that matches the given event, run the corresponding InputHandler

orElse

default InputMap<E> orElse(InputMap<? extends E> that)

Shorthand for sequence(this, that)

without

default InputMap<E> without(InputMap<?> that)

Returns an InputMap that does nothing when this.equals(that); otherwise, returns this input map.

ifConsumed

default InputMap<E> ifConsumed(java.util.function.Consumer<? super E> postConsumption)

Executes some additional handler if the event was consumed (e.g. InputHandler.process(Event) returns InputHandler.Result.CONSUME).

ifIgnored

default InputMap<E> ifIgnored(java.util.function.Consumer<? super E> postIgnore)

Executes some additional handler if the event was ignored (e.g. InputHandler.process(Event) returns InputHandler.Result.IGNORE).

ifProcessed

default InputMap<E> ifProcessed(java.util.function.Consumer<? super E> postProceed)

Executes some additional handler if the event was matched but not consumed (e.g. InputHandler.process(Event) returns InputHandler.Result.PROCEED).

postResult

static <E extends javafx.event.Event> InputMap<E> postResult(InputMap<? extends E> map,
                                                             InputHandler.Result checkedResult,
                                                             java.util.function.Consumer<? super E> postDesiredResult)

upCast

static <E extends javafx.event.Event> InputMap<E> upCast(InputMap<? extends E> inputMap)

sequence

@SafeVarargs
static <E extends javafx.event.Event> InputMap<E> sequence(InputMap<? extends E>... inputMaps)

Creates a single InputMap that pattern matches a given event type against all the given input maps. This is often the InputMap installed on a given node since it contains all the other InputMaps.

process

static <T extends javafx.event.Event,U extends T> InputMap<U> process(EventPattern<? super T,? extends U> eventPattern,
                                                                      java.util.function.Function<? super U,InputHandler.Result> action)

If the given EventPattern matches the given event type, runs the given action, and then attempts to pattern match the event type with the next InputMap (if one exists).

process

static <T extends javafx.event.Event> InputMap<T> process(javafx.event.EventType<? extends T> eventType,
                                                          java.util.function.Function<? super T,InputHandler.Result> action)

When the given event type occurs, runs the given action, and then attempts to pattern match the event type with the next InputMap (if one exists).

consume

static <T extends javafx.event.Event,U extends T> InputMap<U> consume(EventPattern<? super T,? extends U> eventPattern,
                                                                      java.util.function.Consumer<? super U> action)

If the given EventPattern matches the given event type, runs the given action, consumes the event, and does not attempt to match additional InputMaps (if they exist).

consume

static <T extends javafx.event.Event> InputMap<T> consume(javafx.event.EventType<? extends T> eventType,
                                                          java.util.function.Consumer<? super T> action)

When the given event type occurs, runs the given action, consumes the event, and does not attempt to match additional InputMaps (if they exist).

consume

static <T extends javafx.event.Event,U extends T> InputMap<U> consume(EventPattern<? super T,? extends U> eventPattern)

If the given EventPattern matches the given event type, consumes the event and does not attempt to match additional InputMaps (if they exist).

consume

static <T extends javafx.event.Event> InputMap<T> consume(javafx.event.EventType<? extends T> eventType)

When the given event type occurs, consumes the event and does not attempt to match additional InputMaps (if they exist).

consumeWhen

static <T extends javafx.event.Event,U extends T> InputMap<U> consumeWhen(EventPattern<? super T,? extends U> eventPattern,
                                                                          java.util.function.BooleanSupplier condition,
                                                                          java.util.function.Consumer<? super U> action)

If the given EventPattern matches the given event type and condition is true, consumes the event and does not attempt to match additional InputMaps (if they exist).

consumeWhen

static <T extends javafx.event.Event> InputMap<T> consumeWhen(javafx.event.EventType<? extends T> eventType,
                                                              java.util.function.BooleanSupplier condition,
                                                              java.util.function.Consumer<? super T> action)

When the given event type occurs and condition is true, consumes the event and does not attempt to match additional InputMaps (if they exist).

consumeUnless

static <T extends javafx.event.Event,U extends T> InputMap<U> consumeUnless(EventPattern<? super T,? extends U> eventPattern,
                                                                            java.util.function.BooleanSupplier condition,
                                                                            java.util.function.Consumer<? super U> action)

If the given EventPattern matches the given event type and condition is false, consumes the event and does not attempt to match additional InputMaps (if they exist). If condition is true, continues to try to pattern match the event type with the next InputMap (if one exists).

consumeUnless

static <T extends javafx.event.Event> InputMap<T> consumeUnless(javafx.event.EventType<? extends T> eventType,
                                                                java.util.function.BooleanSupplier condition,
                                                                java.util.function.Consumer<? super T> action)

When the given event type occurs and condition is false, consumes the event and does not attempt to match additional InputMaps (if they exist). If condition is true, continues to try to pattern match the event type with the next InputMap (if one exists).

ignore

static <T extends javafx.event.Event,U extends T> InputMap<U> ignore(EventPattern<? super T,? extends U> eventPattern)

If the given EventPattern matches the given event type, does nothing and does not attempt to match additional InputMaps (if they exist).

ignore

static <T extends javafx.event.Event> InputMap<T> ignore(javafx.event.EventType<? extends T> eventType)

When the given event type occurs, does nothing and does not attempt to match additional InputMaps (if they exist).

when

static <T extends javafx.event.Event> InputMap<T> when(java.util.function.BooleanSupplier condition,
                                                       InputMap<T> im)

When the given condition is true, pattern matches the event with the given InputMap or proceeds to the next InputMap (if it exists).

unless

static <T extends javafx.event.Event> InputMap<T> unless(java.util.function.BooleanSupplier condition,
                                                         InputMap<T> im)

When the given condition is false, pattern matches the event with the given InputMap or proceeds to the next InputMap (if it exists).