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

Class Trigger

java.lang.Object
com.vaadin.flow.component.trigger.internal.Trigger
All Implemented Interfaces:
Serializable
Direct Known Subclasses:
DomEventTrigger
public abstract class Trigger extends Object implements Serializable
Something that fires on the client when some condition is met — a DOM event, a signal change, an observer firing, a timer elapsing, an idle timeout, a BroadcastChannel message, a media-query match, … — and, when it does, runs one or more actions.

Actions run synchronously inside the browser's handler when the trigger fires; for triggers that originate from a user gesture (click, keypress, …) this preserves the gesture context for downstream actions, letting them invoke browser APIs that require it (clipboard, fullscreen, file picker, share, …). Note that most such APIs are themselves asynchronous: the action is dispatched synchronously, but any server-observable effect — for example, a callback reporting whether navigator.clipboard.writeText resolved — may reach the server arbitrarily later than the gesture itself, after one or more event-loop turns.

Each Action passed to triggers(Action...) produces one addJsInitializer registration on the host element via install(JsFunction) — so a call with N actions yields N registrations, all detached by remove(). Subclasses implement install to wire the rendered JsFunction to whatever client API the trigger wraps (typically passing it to addJsInitializer alongside whatever literal values the install expression needs).

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

See Also:

  • Constructor Details

    • Trigger

      protected Trigger(Component host)
      Creates a new trigger bound to the given host component's root element.
      Parameters:
      host - the component whose root element the trigger fires on, not null

  • Method Details

    • getHost

      public final Element getHost()
      The host element this trigger fires on.
      Returns:
      the host element, never null

    • triggers

      public final void triggers(Action... actions)
      Wires the given actions to this trigger. They run in the order given the next time this trigger fires. Each call adds another wiring; the existing ones are kept.
      Parameters:
      actions - the actions to run, not null or empty

    • install

      protected abstract Registration install(JsFunction action)
      Installs the given rendered action as a client-side listener and returns the Registration that detaches it. Called once per action passed to triggers(Action...).

      Implementations typically call getHost().addJsInitializer with an install expression that hands the action JsFunction to whatever client API the trigger wraps: 

      
 return getHost().addJsInitializer(
         "this.addEventListener($1, $0);"
                 + "return () => this.removeEventListener($1, $0);",
         action, eventName);
      The expression runs with this bound to the host element. The captures are made available as $0, $1, … in the order passed.
      Parameters:
      action - the rendered action JsFunction; takes one runtime argument named event (the trigger's event payload), not null
      Returns:
      the registration whose Registration.remove() detaches the listener, not null

    • remove

      public final void remove()
      Removes this trigger and all wirings created from it. The corresponding client-side listeners are detached as part of the next synchronisation.