Command<TParam, TResult> class abstract

Command capsules a given handler function that can then be executed by its execute method. The result of this method is then published through its ValueListenable interface Additionally it offers other ValueListenables for it's current execution state, if the command can be executed and for all possibly thrown exceptions during command execution.

Command implements the ValueListenable interface so you can register notification handlers directly to the Command which emits the results of the wrapped function. If this function has a void return type registered handler will still be called so that you can listen for the end of the execution.

The results ValueListenable emits CommandResult<TResult> which is often easier in combination with Flutter ValueListenableBuilder because you have all state information at one place.

An Command is a generic class of type Command<TParam, TResult> where TParam is the type of data that is passed when calling execute and TResult denotes the return type of the handler function. To signal that a handler doesn't take a parameter or returns no value use the type void

Inheritance

Implementers

Available Extensions

FunctionaListener

Constructors

Command(TResult initialValue, ValueListenable<bool>? restriction, bool includeLastResultInCommandResults, bool noReturnValue, bool catchAlways, bool notifyOnlyWhenValueChanges, String? debugName, bool noParamValue)

Properties

asyncNotification → bool: If true, the listeners will be notified asynchronously, which can be helpful if you encounter problems that you trigger rebuilds during the build phase.
finalinherited
canExecute → ValueListenable<bool>: ValueListenable<bool> that changes its value on any change of the current executability state of the command. Meaning if the command can be executed or not. This will issue false while the command executes, but also if the command receives a false from the canExecute ValueListenable that you can pass when creating the Command. its value is restriction.value && !isExecuting.value
no setter
hashCode → int: The hash code for this object.
no setterinherited
hasListeners → bool: Whether any listeners are currently registered.
no setterinherited
isExecuting → ValueListenable<bool>: ValueListenable that changes its value on any change of the execution state change of the command
no setter
listenerCount ↔ int: getter/setter pairinherited
mode → CustomNotifierMode: finalinherited
results → ValueListenable<CommandResult<TParam?, TResult>>: emits CommandResult<TResult> the combined state of the command, which is often easier in combination with Flutter's ValueListenableBuilder because you have all state information at one place.
no setter
runtimeType → Type: A representation of the runtime type of the object.
no setterinherited
thrownExceptions → ValueListenable<CommandError?>: ValueListenable<CommandError> that reflects the Error State of the command it value is reset to null at the beginning of every command execution if the wrapped function throws an error, its value is set to the error is wrapped in an CommandError
no setter
value ↔ TResult: The current value of the object. When the value changes, the callbacks registered with addListener will be invoked.
getter/setter pairinherited

Methods

addListener(void listener()) → void: Register a closure to be called when the object changes.
inherited
call([TParam? param]) → void: This makes Command a callable class, so instead of myCommand.execute() you can write myCommand()
dispose() → void: If you don't need a command any longer it is a good practise to dispose it to make sure all registered notification handlers are remove to prevent memory leaks
override
execute([TParam? param]) → void: Calls the wrapped handler function with an optional input parameter
executeWithFuture([TParam? param]) → Future<TResult>: Executes an async Command and returns a Future that completes as soon as the Command completes. This is especially useful if you use a RefreshIndicator
noSuchMethod(Invocation invocation) → dynamic: Invoked when a nonexistent method or property is accessed.
inherited
notifyListeners() → void: Call all the registered listeners.
inherited
removeListener(void listener()) → void: Remove a previously registered closure from the list of closures that are notified when the object changes.
inherited
toString() → String: A string representation of this object.
inherited
toWidget({required Widget onResult(TResult lastResult, TParam? param), Widget whileExecuting(TResult lastResult, TParam? param)?, Widget onError(Object? error, TParam? param)?}) → Widget: Returns a the result of one of three builders depending on the current state of the Command. This function won't trigger a rebuild if the command changes states so it should be used together with get_it_mixin, provider, flutter_hooks and the like.

Operators

operator ==(Object other) → bool: The equality operator.
inherited

Static Properties

catchAlwaysDefault ↔ bool: if no individual value for catchAlways is passed to the factory methods, this variable defines the default. true : independent if there are listeners at thrownExceptions or results the Command will catch all Exceptions that might be thrown by the wrapped function. They will still get reported to the globalExceptionHandler false: unless no one listens on thrownExceptions or results, exceptions will be rethrown. This is can be very helpful while developing. Before the Exception is rethrown globalExeptionHandler will be called.
getter/setter pair
globalExceptionHandler ↔ (void Function(String? commandName, CommandError<Object> error)?): optional hander that will get called on any exception that happens inside any Command of the app. Ideal for logging. commandName the debugName of the Command
getter/setter pair
loggingHandler ↔ (void Function(String? commandName, CommandResult result)?): optional handler that will get called on all Command executions. commandName the debugName of the Command
getter/setter pair

Static Methods

createAsync<TParam, TResult>(Future<TResult> func(TParam x), TResult initialValue, {ValueListenable<bool>? restriction, bool includeLastResultInCommandResults = false, bool? catchAlways, bool notifyOnlyWhenValueChanges = false, String? debugName}) → Command<TParam, TResult>: Creates a Command for an asynchronous handler function with parameter that returns a value func: handler function initialValue sets the .value of the Command. restriction : ValueListenable<bool> that can be used to enable/disable the command based on some other state change. If omitted the command can be executed always except it's already executing includeLastResultInCommandResults will include the value of the last successful execution in all CommandResult values unless there is no result. This can be handy if you always want to be able to display something even when you got an error or while the command is still running. catchAlways : overrides the default set by catchAlwaysDefault. If false, Exceptions thrown by the wrapped function won't be caught but rethrown unless there is a listener on thrownExceptions or results. notifyOnlyWhenValueChanges : the default is that the command notifies it's listeners even if the value hasn't changed. If you set this to true the command will only notify it's listeners if the value has changed. debugName optional identifier that is included when you register a globalExceptionHandler or a loggingHandler
createAsyncNoParam<TResult>(Future<TResult> func(), TResult initialValue, {ValueListenable<bool>? restriction, bool includeLastResultInCommandResults = false, bool? catchAlways, bool notifyOnlyWhenValueChanges = false, String? debugName}) → Command<void, TResult>: Creates a Command for an asynchronous handler function with no parameter that returns a value func: handler function initialValue sets the .value of the Command. restriction : ValueListenable<bool> that can be used to enable/disable the command based on some other state change. If omitted the command can be executed always except it's already executing includeLastResultInCommandResults will include the value of the last successful execution in all CommandResult values unless there is no result. This can be handy if you always want to be able to display something even when you got an error or while the command is still running. catchAlways : overrides the default set by catchAlwaysDefault. If false, Exceptions thrown by the wrapped function won't be caught but rethrown unless there is a listener on thrownExceptions or results. notifyOnlyWhenValueChanges : the default is that the command notifies it's listeners even if the value hasn't changed. If you set this to true the command will only notify it's listeners if the value has changed. debugName optional identifier that is included when you register a globalExceptionHandler or a loggingHandler
createAsyncNoParamNoResult(Future action(), {ValueListenable<bool>? restriction, bool? catchAlways, bool notifyOnlyWhenValueChanges = false, String? debugName}) → Command<void, void>: Creates a Command for an asynchronous handler function with no parameter and no return type action: handler function restriction : ValueListenable<bool> that can be used to enable/disable the command based on some other state change. If omitted the command can be executed always except it's already executing Can't be used with an ValueListenableBuilder because it doesn't have a value, but you can register a handler to wait for the completion of the wrapped function. catchAlways : overrides the default set by catchAlwaysDefault. If false, Exceptions thrown by the wrapped function won't be caught but rethrown unless there is a listener on thrownExceptions or results. notifyOnlyWhenValueChanges : the default is that the command notifies it's listeners even if the value hasn't changed. If you set this to true the command will only notify it's listeners if the value has changed. debugName optional identifier that is included when you register a globalExceptionHandler or a loggingHandler
createAsyncNoResult<TParam>(Future action(TParam x), {ValueListenable<bool>? restriction, bool? catchAlways, bool notifyOnlyWhenValueChanges = false, String? debugName}) → Command<TParam, void>: Creates a Command for an asynchronous handler function with one parameter and no return type action: handler function restriction : ValueListenable<bool> that can be used to enable/disable the command based on some other state change. If omitted the command can be executed always except it's already executing Can't be used with an ValueListenableBuilder because it doesn't have a value but you can register a handler to wait for the completion of the wrapped function. catchAlways : overrides the default set by catchAlwaysDefault. If false, Exceptions thrown by the wrapped function won't be caught but rethrown unless there is a listener on thrownExceptions or results. notifyOnlyWhenValueChanges : the default is that the command notifies it's listeners even if the value hasn't changed. If you set this to true the command will only notify it's listeners if the value has changed. debugName optional identifier that is included when you register a globalExceptionHandler or a loggingHandler
createSync<TParam, TResult>(TResult func(TParam x), TResult initialValue, {ValueListenable<bool>? restriction, bool includeLastResultInCommandResults = false, bool? catchAlways, bool notifyOnlyWhenValueChanges = false, String? debugName}) → Command<TParam, TResult>: Creates a Command for a synchronous handler function with parameter that returns a value func: handler function initialValue sets the .value of the Command. restriction : ValueListenable<bool> that can be used to enable/disable the command based on some other state change. If omitted the command can be executed always except it's already executing includeLastResultInCommandResults will include the value of the last successful execution in all CommandResult values unless there is no result. This can be handy if you always want to be able to display something even when you got an error. As synchronous function doesn't give the UI any chance to react on on a change of .isExecuting,isExecuting isn't supported for synchronous commands and will throw an assert if you try to use it. catchAlways : overrides the default set by catchAlwaysDefault. If false, Exceptions thrown by the wrapped function won't be caught but rethrown unless there is a listener on thrownExceptions or results. notifyOnlyWhenValueChanges : the default is that the command notifies it's listeners even if the value hasn't changed. If you set this to true the command will only notify it's listeners if the value has changed. debugName optional identifier that is included when you register a globalExceptionHandler or a loggingHandler
createSyncNoParam<TResult>(TResult func(), TResult initialValue, {ValueListenable<bool>? restriction, bool includeLastResultInCommandResults = false, bool? catchAlways, bool notifyOnlyWhenValueChanges = false, String? debugName}) → Command<void, TResult>: Creates a Command for a synchronous handler function with no parameter that returns a value func: handler function initialValue sets the .value of the Command. restriction : ValueListenable<bool> that can be used to enable/disable the command based on some other state change. If omitted the command can be executed always except it's already executing includeLastResultInCommandResults will include the value of the last successful execution in all CommandResult values unless there is no result. This can be handy if you always want to be able to display something even when you got an error. As synchronous function doesn't give any the UI any chance to react on on a change of .isExecuting,isExecuting isn't supported for synchronous commands and will throw an assert if you try to use it. catchAlways : overrides the default set by catchAlwaysDefault. If false, Exceptions thrown by the wrapped function won't be caught but rethrown unless there is a listener on thrownExceptions or results. notifyOnlyWhenValueChanges : the default is that the command notifies it's listeners even if the value hasn't changed. If you set this to true the command will only notify it's listeners if the value has changed. debugName optional identifier that is included when you register a globalExceptionHandler or a loggingHandler
createSyncNoParamNoResult(void action(), {ValueListenable<bool>? restriction, bool? catchAlways, bool notifyOnlyWhenValueChanges = false, String? debugName}) → Command<void, void>: Creates a Command for a synchronous handler function with no parameter and no return type action: handler function restriction : ValueListenable<bool> that can be used to enable/disable the command based on some other state change. If omitted the command can be executed always except it's already executing As synchronous function doesn't give any the UI any chance to react on on a change of .isExecuting,isExecuting isn't supported for synchronous commands ans will throw an assert if you try to use it. Can't be used with an ValueListenableBuilder because it doesn't have a value, but you can register a handler to wait for the completion of the wrapped function. catchAlways : overrides the default set by catchAlwaysDefault. If false, Exceptions thrown by the wrapped function won't be caught but rethrown unless there is a listener on thrownExceptions or results. notifyOnlyWhenValueChanges : the default is that the command notifies it's listeners even if the value hasn't changed. If you set this to true the command will only notify it's listeners if the value has changed. debugName optional identifier that is included when you register a globalExceptionHandler or a loggingHandler
createSyncNoResult<TParam>(void action(TParam x), {ValueListenable<bool>? restriction, bool? catchAlways, bool notifyOnlyWhenValueChanges = false, String? debugName}) → Command<TParam, void>: Creates a Command for a synchronous handler function with one parameter and no return type action: handler function restriction : ValueListenable<bool> that can be used to enable/disable the command based on some other state change. If omitted the command can be executed always except it's already executing As synchronous function doesn't give the UI any chance to react on on a change of .isExecuting,isExecuting isn't supported for synchronous commands and will throw an assert if you try to use it. Can't be used with an ValueListenableBuilder because it doesn't have a value, but you can register a handler to wait for the completion of the wrapped function. catchAlways : overrides the default set by catchAlwaysDefault. If false, Exceptions thrown by the wrapped function won't be caught but rethrown unless there is a listener on thrownExceptions or results. notifyOnlyWhenValueChanges : the default is that the command notifies it's listeners even if the value hasn't changed. If you set this to true the command will only notify it's listeners if the value has changed. debugName optional identifier that is included when you register a globalExceptionHandler or a loggingHandler