future_debounce_button 0.3.0

SDKflutter
Platformandroidioswindowslinuxmacosweb

Button for asynchronous calls. Keeps your code clean, improves UI/UX through visual indication.

Future Debounce Button (FDB)


Button for asynchronous calls. Keeps your code clean, improves UI/UX through visual indication.

Future Debounce Button

Features

A button widget that provides complete boilerplate for handling and debouncing of asynchronous requests (API calls etc.). The FDB button handles the future (debounce, abort, block) and indicates its state based on the state of that future and other provided parameters.


Getting started

The only required parameter for this button is the onPressed future. Everything else is optional.

// A button that handles a future of type `Future<int>`
FutureDebounceButton<int>(
    onPressed: // TODO: (required) a future to handle
    onSuccess: // TODO: (optional) what to do with the result of the future
    onError: // TODO: (optional) your error handler
    onAbort: // TODO: (optional) what to do if the user canceled the request
);

The following example displays a "Submit" [OutlinedButton] widget, which triggers a future. If the future fails - the button will enter the error state for 2 seconds. If the future completes successfully - the button will enter success state forever, preventing user from calling the future again.

/// Submit request to server
Future<bool> submit() async {
    // ...
}

   // ...

/// A button that says 'Submit'
FutureDebounceButton<bool>(
    buttonType: FDBType.outlined, // Shows OutlinedButton widget
    onPressed: submit,
    actionCallText: 'Submit',
    errorStateDuration: Duration(seconds:2), // show 'Error' for 2 seconds
    successStateDuration: null // will lock in 'Success!' forever
);

Button Types

The button type can be selected from one of the following values: elevated, filled, filledTonal, outlined and text. See buttonType property of FDB:

ValueMaterial Widget
FDBType.elevatedElevatedButton
FDBType.filledFilledButton
FDBType.filledTonalFilledButton.tonal
FDBType.outlinedOutlinedButton
FDBType.textTextButton

Future Debounce Button Types

States

The button manages its own state based on the state of the future provided to it. The possible states are:

  • disabled - button is either completely disabled, or disabled for the duration of debounceDuration value after the button was pressed (see Properties > debounceDuration).
  • ready - the button is in its normal "call to action" state. In this state it displays either actionCallChild widget, actionCallText text, or text 'Go' if none of those values are provided.
  • loading - the button has been pressed and the future is executing. The onAbort handler is not provided to the button. The button in this state displays either loadingChid widget, loadingText text, or the default [CircularProgressIndicator] widget if none of the former is provided. Clicking on the button in this state does nothing. The button awaits for the future to complete or time out.
  • abort - the abort button has been pressed while the future was executing. The button displays either abortPressedChild widget, abortPressedText text, or Cancelled text if none of the former are provided. See the abortStateDuration property for more options on this state. When the user presses the abort button - the future is abandoned.
  • success - the future has completed with a value. The value is passed to the onSuccess handler if one is provided. The button displays either successChild widget, successText text, or Success! text if none of the former are provided. See the successStateDuration property for more options on this state
  • error - the future has completed with an error or timed out. The error and the stack trace are passed to the onError handler if one is provided. The button displays either errorChild widget, errorText text, or Error text if none of the former are provided. See the errorStateDuration property for more options on this state

API

The following handlers and properties are available for customization:

Handlers

The following handlers are available:

HandlerRequiredDescription
onPressedrequireda future to handle
onSuccessoptionalcalled when the onPressed future has completed with a value.
onErroroptionalThe future has produced an error. The error and stackTrace objects are passed to the method.
onAbortoptionalIf onAbort handler is provided, the button becomes "abortable" (the future could be abandoned and the possible result is dropped instead of being fed to onSuccess handler). If onAbort is not provided - the button will lock in the "loading" state until the future completes with success, error, or times out (see timeout property).
onStateChangeoptionalNotifies its listeners about the button's state changes. The possible values as per FDBState enum

Properties

PropertyTypeDefault valueDescription
General
enabledbooltrueif enabled is false - the button will be disabled
buttonTypeenumFDBType.filledAllows you to choose from one of the five avaliable button widgets. See Button Types above
Ready state
actionCallChildWidget?nullCall to action (ready) state widget. This widget is displayed when the button is ready to be pressed. This overrides the actionCallText text
actionCallTextString?nullDisplays provided text. Defaults to Go if left null
actionCallButtonStyleButtonStyle?nullButton style for the ready/disabled state. Uses theme defaults if left null
Loading state
loadingChildWidget?nullWidget to show when the future is running (non-abortable). This overrides loadingText text
loadingTextString?nullText to display when the future is running (non-abortable). Displays [CircularProgressIndicator] widget if left null
loadingButtonStyleButtonStyle?nullButton style for the loading state. Uses theme defaults if left null
Abort state
abortChildWidget?nullWidget to show when the future is running (abortable), This overrides abortText text
abortPressedChildWidget?nullWidget to show when the user presses abort button, This overrides abortPressedText text
abortTextString?nullText to display when the future is running (abortable). Displays [CircularProgressIndicator] widget with Abort text if left null
abortPressedTextString?nullText to display when the user presses abort button. Displays text widget with Cancelled text if left null
abortButtonStyleButtonStyle?nullButton style for the abort state. Uses theme defaults if left null
abortStateDurationDuration1sThe duration for which the abort state is maintained. If abortStateDuration is set to null - the abort state will never clear. If abortStateDuration is set to Duration.zero - the abort state will clear instantly
Error state
errorChildWidget?nullWidget to show when the future has failed or timed out. This overrides errorText text
errorTextString?nullText to display when the future has failed or timed out. Displays Error text if left null
errorButtonStyleButtonStyle?nullButton style for the error state. Uses theme internal static style if left null
errorStateDurationDuration1sThe duration for which the error state is maintained. If errorStateDuration is set to null - the error state will never clear. If errorStateDuration is set to Duration.zero - the error state will clear instantly
Success state
successChildWidget?nullWidget to show when the future has completed with a value. This overrides successText text
successTextString?nullText to display when the future has completed with a value. Displays Success! text if left null
successButtonStyleButtonStyle?nullButton style for the success state. Uses theme internal static style if left null
successStateDurationDuration1sThe duration for which the error state is maintained. If successStateDuration is set to null - the success state will never clear. If successStateDuration is set to Duration.zero - the error state will clear instantly
Debounce and Timeout
debounceDurationDuration250msA delay between the first hit of the button and until the button starts accepting Abort hits (debounce). This is needed to prevent users from double-clicking the button.
timeoutDuration?nullMaximum duration of a future. If timeout is set and the time ran out - the FDB will produce [TimeoutException] and port it to onError handler if one is provided