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

Class Action

java.lang.Object
com.vaadin.flow.component.trigger.internal.Action
All Implemented Interfaces:
Serializable
Direct Known Subclasses:
CallbackAction, PromiseAction, ReplaceChildrenTemporarilyAction, SetPropertyAction, SetPropertyTemporarilyAction
public abstract class Action extends Object implements Serializable
Something that runs on the client when a Trigger fires.

Actions are the unit of behaviour you attach to a trigger: copy text to the clipboard, download a file, scroll an element into view, and so on. Pair an Action with a Trigger (typically via trigger.triggers(action)) and the framework wires the action to run whenever the trigger fires.

An Action usually consumes one or more inputs that supply its values — a literal, the current value of a DOM property, an event-scoped expression — so the data the action acts on is read on the client at fire time rather than captured on the server. A trigger family may expose its event state as one or more Inputs, typically as public static final fields (for example MouseEventTrigger.EventData.screenX); other inputs read state independent of any trigger (for example PropertyInput).

For Action implementors: override toJs(Trigger) to produce the JavaScript that the trigger handler invokes; reference inputs through Action.Input.toJs(Trigger) so the same value-supplier abstractions work with every action.

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

See Also:

  • Nested Class Summary

    Nested Classes
    Modifier and Type
    Class
    Description
    static class 
    Action.Input<T>
    A value an Action consumes at fire time.

  • Constructor Summary

    Constructors
    Constructor
    Description
    Action()
     

  • Method Summary

    Modifier and Type
    Method
    Description
    protected static JsFunction
    applyTemporarily(Element stashElement, String stashKey, JsFunction snapshot, JsFunction apply, JsFunction revert, long timeoutMillis)
    Renders the boilerplate shared by every "apply X, then undo X" action: stashes the original value on the first fire of a cycle, coalesces rapid re-fires (clearing the previous revert timer instead of re-snapshotting the already-modified state), and reverts the stashed value when the timer expires.
    protected abstract JsFunction
    toJs(Trigger trigger)
    Builds the JsFunction that runs this action when the surrounding trigger fires.
    protected static void
    warnIfNotVisible(Component target, String actionDescription)
    Logs a warning if target is not visible.

    Methods inherited from class java.lang.Object

    clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

  • Constructor Details

    • Action

      public Action()

  • Method Details

    • toJs

      protected abstract JsFunction toJs(Trigger trigger)
      Builds the JsFunction that runs this action when the surrounding trigger fires. The returned function takes one runtime argument named event (declared by the framework when it composes the trigger handler); subclasses do not declare argument names themselves.

      The body is one statement. To embed a value produced on the client, capture an Action.Input's JsFunction as a capture and invoke it inside the body as $N(event).

      Parameters:
      trigger - the surrounding trigger this render is for, not null
      Returns:
      the action's JS function, not null

    • warnIfNotVisible

      protected static void warnIfNotVisible(Component target, String actionDescription)
      Logs a warning if target is not visible. Intended for actions that capture another component's element as a JsFunction reference: an invisible component is not sent to the client, the captured element reference resolves to null when the install JS runs, and the action fails at fire time. JsFunction captures are bound by value at install time, so restoring visibility later does not recover the binding.

      Call this after the target is known to be attached (typically inside a runWhenAttached callback) so the check sees the visibility state at the time the install JS would be sent to the client.

      Parameters:
      target - the component whose visibility to check, not null
      actionDescription - human-readable name of the action being wired, used in the warning message (e.g. "Fullscreen.enter()"), not null

    • applyTemporarily

      protected static JsFunction applyTemporarily(Element stashElement, String stashKey, JsFunction snapshot, JsFunction apply, JsFunction revert, long timeoutMillis)
      Renders the boilerplate shared by every "apply X, then undo X" action: stashes the original value on the first fire of a cycle, coalesces rapid re-fires (clearing the previous revert timer instead of re-snapshotting the already-modified state), and reverts the stashed value when the timer expires.

      Subclasses provide three payload-specific sub-functions:

      • snapshot — no arguments, returns the value to stash; only called on the first fire of a cycle.
      • apply — one argument named event, performs the temporary change; called on every fire.
      • revert — one argument named original, restores the stashed value; called once per cycle when the timer expires.
      The per-element stash is keyed by stashKey, so two temporary modifications on the same element with different keys (e.g. different property names) do not interfere; two with the same key (e.g. two triggers both flashing the same property) share an original and a single revert deadline.
      Parameters:
      stashElement - element to hang the stash off — typically the modified target, not null
      stashKey - identifier of what is being modified (e.g. property name); separates unrelated temporary modifications on the same element, not null
      snapshot - reads the current value to stash, no arguments, not null
      apply - performs the change, declares one argument named event, not null
      revert - restores the stashed value, declares one argument named original, not null
      timeoutMillis - delay before reverting, in milliseconds; must be non-negative
      Returns:
      a JsFunction with one runtime argument named event, suitable for returning from an action's toJs(Trigger), not null