Package com.vaadin.flow.component.trigger.internal

Class KeyboardEventTrigger

java.lang.Object
com.vaadin.flow.component.trigger.internal.Trigger
com.vaadin.flow.component.trigger.internal.DomEventTrigger
com.vaadin.flow.component.trigger.internal.KeyboardEventTrigger
All Implemented Interfaces:
Serializable
Direct Known Subclasses:
ShortcutTrigger
public class KeyboardEventTrigger extends DomEventTrigger
Fires on a DOM keyboard event (keydown, keyup). Exposes the KeyboardEvent properties as static Action.Input fields on KeyboardEventTrigger.EventData, and supports filtering by key via forKeys(Key...) so only the configured keys produce a server-side fire.

The single-argument constructor defaults to keydown, the standard event for keyboard shortcuts. A typical shortcut wiring looks like: 


 new KeyboardEventTrigger(ui).forKeys(Key.ENTER, Key.ESCAPE).triggers(action);

Without a filter, the trigger fires on every keyboard event of the configured name. With one or more forKeys(Key...) calls, the client compares event.key against the configured set and only invokes the action on a match — unmatched events do not cross the network.

The modifier-key fields (shiftKey, ctrlKey, altKey, metaKey) are intentionally duplicated from MouseEventTrigger.EventData: although the underlying JS property is the same, each field is class-scoped so a single instance can't be safely shared across unrelated event families. Subclasses bound to a specific event name may extend KeyboardEventTrigger.EventData to add event-specific properties.

For internal use only. May be renamed or removed in a future release.

See Also:

  • Constructor Details

    • KeyboardEventTrigger

      public KeyboardEventTrigger(Component host)
      Creates a keyboard-event trigger that fires on keydown. Use this constructor for shortcut wirings; keydown is the standard event for that purpose (it fires immediately on press, repeats while held, and is dispatched before the browser's default action).
      Parameters:
      host - the component whose root element listens for the event, not null

    • KeyboardEventTrigger

      public KeyboardEventTrigger(Component host, String eventName)
      Creates a keyboard-event trigger that fires when the host receives a DOM event with the given name.
      Parameters:
      host - the component whose root element listens for the event, not null
      eventName - the DOM keyboard-event name (e.g. "keydown", "keyup"), not null

  • Method Details

    • forKeys

      public KeyboardEventTrigger forKeys(Key... keys)
      Restricts the trigger to fire only when event.key matches one of the given keys. Multiple calls accumulate; with no call the trigger fires on every keyboard event of the configured name.

      Matching is done client-side against every printable representation in Key.getKeys(), so a key like Key.SPACE (whose event.key value is " ") matches the spacebar press. Events that don't match are dropped in the browser handler — they do not reach the server.

      Parameters:
      keys - the keys to allow; not null, none of the entries null
      Returns:
      this trigger, for chaining

    • preventDefault

      public KeyboardEventTrigger preventDefault()
      Description copied from class: DomEventTrigger
      Configures the trigger to call event.preventDefault() when it fires, suppressing the browser's default action (e.g. submitting a form on Enter, scrolling on Space). Affects Trigger.triggers(Action...) calls made after this method; existing wirings are not retroactively changed.
      Overrides:
      preventDefault in class DomEventTrigger
      Returns:
      this trigger, for chaining

    • stopPropagation

      public KeyboardEventTrigger stopPropagation()
      Description copied from class: DomEventTrigger
      Configures the trigger to call event.stopPropagation() when it fires, preventing the event from bubbling to ancestor listeners. Affects Trigger.triggers(Action...) calls made after this method; existing wirings are not retroactively changed.
      Overrides:
      stopPropagation in class DomEventTrigger
      Returns:
      this trigger, for chaining

    • appendHandlerBody

      protected void appendHandlerBody(StringBuilder body, List<Object> extraCaptures)
      Description copied from class: DomEventTrigger
      Hook for subclasses to contribute statements to the wrapper handler body and extra captures referenced by those statements. The base implementation appends e.preventDefault(); and e.stopPropagation(); when the corresponding flags are set.

      Subclasses overriding this method typically prepend their own guard statements (and call super.appendHandlerBody afterwards) so the guard runs before preventDefault — preventing the default action on events the guard would have rejected would be wrong. Each entry added to extraCaptures is appended after the event name capture, so the first extra is referenced as $2 in the body, the next as $3, and so on.

      Overrides:
      appendHandlerBody in class DomEventTrigger
      Parameters:
      body - the wrapper body so far; statements appended here run inside the const h = e => { ... $0(e); } wrapper, in order, with the event available as e
      extraCaptures - mutable list of captures appended after the event-name capture ($1); the first capture added is $2, etc.