Package org.vaadin.firitin.components.button

Class ActionButton<T>

java.lang.Object
com.vaadin.flow.component.Component
com.vaadin.flow.component.Composite<com.vaadin.flow.component.html.Div>
org.vaadin.firitin.components.button.ActionButton<T>
Type Parameters:
T - the type of the result of the slow task
All Implemented Interfaces:
com.vaadin.flow.component.AttachNotifier, com.vaadin.flow.component.DetachNotifier, com.vaadin.flow.component.HasElement, com.vaadin.flow.component.HasStyle, Serializable
@StyleSheet("context://assets/org/vaadin/firitin/components/action-button.css") public class ActionButton<T> extends com.vaadin.flow.component.Composite<com.vaadin.flow.component.html.Div>
A button that can be used to run a slow action in the background without blocking the UI. Even if you would disable/block other parts of your UI during the action, this can be better approach as the global progress indicator can make people think the app has crashed. A good UI pattern for long-running actions (that can't run on background and keep the UI funtional), is to show for example a dialog with a progress indicator and possibly a cancel button.

NOTE! This class is still in early development and likely to get some changes still in the future. Suggestions/contributions are more than welcome!

The button is disabled while the task is running (which blocks re-triggering) and re-enabled when it is done; aria-busy marks it busy for assistive technology. The busy state is shown as a built-in (indeterminate) progress bar for buttons with text, and — since a greyed-out static icon is poor feedback and there is no room for a bar — as a spinner replacing the icon for icon-only buttons. A trackable/estimated action shows the (determinate) progress bar even on an icon-only button. See isShowSpinner() / setShowSpinner(boolean) / setBusyIcon(Component) and isShowProgressBar() / setShowProgressBar(boolean).

The actual task, set with setAction(Supplier) or setCompletableFutureAction(Supplier), is run in a separate thread. If your task wants to update the UI during its execution, you need to synchronize with the UI thread using UI.access(Command).

UI updates are suggested to be done in #setPostTaskAction(Consumer) which is called after the task has completed or #setPreTaskAction(Runnable) which is called before the task is started. These are run in the UI thread.

The button will automatically enable polling if push is not enabled and call push() if "manual server push" is active.

See Also:

  • Constructor Details

  • Method Details

    • setAction

      public ActionButton<T> setAction(Supplier<T> action)

    • setAction

      public ActionButton<Void> setAction(Runnable action)

    • setCompletableFutureAction

      public ActionButton<T> setCompletableFutureAction(Supplier<CompletableFuture<T>> task)

    • setPostUiAction

      public ActionButton<T> setPostUiAction(Consumer<? super T> postUiAction)
      Sets an action to update the UI after the actual slow actions is completed. This is "run in the UI thread", meaning you don't need to synchronize with the UI using UI.access().
      Parameters:
      postUiAction - the action to run after the slow task
      Returns:
      this for chaining

    • setPostUiUpdate

      @Deprecated public ActionButton<T> setPostUiUpdate(Consumer<? super T> postUiUpdate)
      Deprecated.
      use setPostUiAction(Consumer) instead
      Parameters:
      postUiUpdate - the action to run after the slow task
      Returns:
      this for chaining

    • setPreUiAction

      public ActionButton<T> setPreUiAction(Runnable preUiAction)
      Sets an action to update the UI before the actual slow actions is started. This is "run in the UI thread", meaning you don't need to synchronize with the UI using UI.access().
      Parameters:
      preUiAction - the action to run before the slow task
      Returns:
      this for chaining

    • setPreUiUpdate

      @Deprecated(forRemoval=true) public ActionButton<T> setPreUiUpdate(Runnable preUiUpdate)
      Deprecated, for removal: This API element is subject to removal in a future version.
      use setPreUiAction(Runnable) instead

    • onAttach

      protected void onAttach(com.vaadin.flow.component.AttachEvent attachEvent)
      Overrides:
      onAttach in class com.vaadin.flow.component.Component

    • getCompletableFuture

      public CompletableFuture<T> getCompletableFuture()

    • setText

      public void setText(String s)

    • setIcon

      public ActionButton<T> setIcon(com.vaadin.flow.component.Component icon)
      Sets the button's icon. Delegates to the underlying VButton.

    • addThemeVariants

      public ActionButton<T> addThemeVariants(com.vaadin.flow.component.button.ButtonVariant... variants)
      Adds theme variants to the underlying VButton.

    • removeThemeVariants

      public ActionButton<T> removeThemeVariants(com.vaadin.flow.component.button.ButtonVariant... variants)
      Removes theme variants from the underlying VButton.

    • setAriaLabel

      public ActionButton<T> setAriaLabel(String ariaLabel)
      Sets the accessible name of the underlying VButton.

    • setTooltipText

      public ActionButton<T> setTooltipText(String tooltipText)
      Sets the tooltip of the underlying VButton.

    • setBusyText

      public ActionButton setBusyText(String text)
      Set the text of the button to show while the task is running (and button disabled).
      Parameters:
      text - the text to show
      Returns:

    • reEnableAfterAction

      protected void reEnableAfterAction()

    • createSpinner

      protected com.vaadin.flow.component.Component createSpinner()
      Creates the default busy indicator: an empty vaadin-icon drawn as a spinning ring purely in CSS (see action-button.css). Being a vaadin-icon, the theme sizes it exactly like the icon it replaces (icon sizes vary a lot between themes), while the ring's thickness is under our control rather than baked into a glyph. Override setBusyIcon(Component) for a custom one.

    • isShowSpinner

      public boolean isShowSpinner()
      Whether, while the task runs, the button's icon is replaced by a spinning busy indicator (the button is also disabled, as always). By default this is enabled automatically for icon-only buttons (an icon, no text), where a greyed-out static icon is poor feedback and there is no room for a progress bar. Buttons with text (or that otherwise show a progress bar) use that bar instead. Set it explicitly with setShowSpinner(boolean) to force it on or off.

    • setShowSpinner

      public ActionButton<T> setShowSpinner(boolean showSpinner)
      Forces the spinning busy indicator on or off (see isShowSpinner() for the default behavior). Call before the button is attached.

    • setBusyIcon

      public ActionButton<T> setBusyIcon(com.vaadin.flow.component.Component busyIcon)
      Sets a custom component to show in place of the icon while the task runs (instead of the default spinner). Implies isShowSpinner().

    • isShowProgressBar

      public boolean isShowProgressBar()

    • setShowProgressBar

      public void setShowProgressBar(boolean showProgressBar)
      Parameters:
      showProgressBar - true if the built-in progress bar should be shown while the task is running

    • prepareProgressBar

      protected VProgressBar prepareProgressBar()

    • updateProgressAsync

      public void updateProgressAsync(double progress, double min, double max)
      API for updating the progress bar from the task. This method is safe to call from the task thread.
      Parameters:
      progress - the progress value to set
      min - the minimum value of the progress bar
      max - the maximum value of the progress bar

    • updateProgressAsync

      public void updateProgressAsync(double progress)
      API for updating the progress bar from the task. This method is safe to call from the task thread.
      Parameters:
      progress - the progress value to set

    • getExecutor

      public Executor getExecutor()

    • setExecutor

      public void setExecutor(Executor executor)
      Set an executor to be used for running the task. If not set, the default executor is used.
      Parameters:
      executor - the executor to use for the task

    • getEstimatedDuration

      public Integer getEstimatedDuration()

    • setEstimatedDuration

      public void setEstimatedDuration(Integer estimatedDuration)
      Set the estimated duration of the task in milliseconds. This can be used to show a progress bar that is not indeterminate.
      Parameters:
      estimatedDuration -

    • getButton

      public VButton getButton()
      Returns the underlying button component, for further configaration.
      Returns:
      the underlying button component

    • isEnableAfterAction

      public boolean isEnableAfterAction()
      Returns:
      true if the button should be automatically enabled after the action is completed

    • setEnableAfterAction

      public ActionButton setEnableAfterAction(boolean enableAfterAction)
      Parameters:
      enableAfterAction - true (default) if the button should be automatically enabled after the action is completed
      Returns:
      this for chaining