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
-
- Object
- ChangeNotifier
- CustomValueNotifier<
TResult> - Command
- Implementers
- Available Extensions
Constructors
-
Command({required TResult initialValue, required ValueListenable<
bool> ? restriction, required ExecuteInsteadHandler<TParam> ? ifRestrictedExecuteInstead, required bool includeLastResultInCommandResults, required bool noReturnValue, required bool notifyOnlyWhenValueChanges, ErrorFilter? errorFilter, required String? debugName, required 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 issuefalse
while the command executes, but also if the command receives atrue
from therestriction
ValueListenable
that you can pass when creating the Command. its value is!restriction.value && !isExecuting.value
no setter - debugName → String?
-
no setter
-
errors
→ ValueListenable<
CommandError?> -
ValueListenable<CommandError>
that reflects the Error State of the command if the wrapped function throws an error, its value is set to the error is wrapped in anCommandError
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 commandno 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'sValueListenableBuilder
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 if the wrapped function throws an error, its value is set to the error is wrapped in anCommandError
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 writemyCommand()
-
clearErrors(
) → void -
clears the error state of the command. This will trigger any listeners
especially useful if you use
watch_it
to watch the errors property. However the prefered way to handle thd errors property is either userregisterHandler
orlisten
ininitState
of aStatefulWidget
-
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
- assertionsAlwaysThrow ↔ bool
-
AssertionErrors
are almost never wanted in production, so by default they will dirextly be rethrown, so that they are found early in development In case you want them to be handled like any other error, meaning an ErrorFilter will decide what should happen, set this to false.getter/setter pair - debugErrorsThrowAlways ↔ bool
-
getter/setter pair
- detailedStackTraces ↔ bool
-
Will capture detailed stacktraces for any Command execution. If this has negative impact on performance
you can set this to false. This is a global setting for all Commands in the app.
getter/setter pair
- errorFilterDefault ↔ ErrorFilter
-
if no individual ErrorFilter is set when creating a Command
this filter is used in case of an error
getter/setter pair
-
globalExceptionHandler
↔ (void Function(CommandError<
Object> error, StackTrace stackTrace)?) -
optional hander that will get called on any exception that happens inside
any Command of the app. Ideal for logging.
the debugName of the Command that was responsible for the error is inside
the error object.
getter/setter pair
- loggingHandler ↔ (void Function(String? commandName, CommandResult result)?)
-
optional handler that will get called on all
Command
executions if the Command has a set debugName.commandName
the debugName of the Commandgetter/setter pair - reportAllExceptions ↔ bool
-
overrides any ErrorFilter that is set for a Command and will call the global exception handler
for any error that occurs in any Command of the app.
Together with the
detailledStackTraces
this gives detailed information what's going on in the appgetter/setter pair - useChainCapture ↔ bool
-
experimental if enabled you will get a detailed stacktrace of the origin of the exception
inside the wrapped function.
getter/setter pair
Static Methods
-
createAsync<
TParam, TResult> (Future< TResult> func(TParam x), {required TResult initialValue, ValueListenable<bool> ? restriction, ExecuteInsteadHandler<TParam> ? ifRestrictedExecuteInstead, bool includeLastResultInCommandResults = false, ErrorFilter? errorFilter, bool notifyOnlyWhenValueChanges = false, String? debugName}) → Command<TParam, TResult> -
Creates a Command for an asynchronous handler function with parameter that returns a value
func
: handler functioninitialValue
sets the.value
of the Command.restriction
:ValueListenable<bool>
that can be used to enable/disable the command based on some other state change.true
means that the Command cannot be executed. If omitted the command can be executed always except it's already executingifRestrictedExecuteInstead
ifrestriction
is set for the command and its value istrue
this function will be called instead of the wrapped function. This is useful if you want to execute a different function when the command is restricted. For example you could show a dialog to let the user logg in if the restriction is because the user is not logged in. If you don't set this function, the command will just do nothing when it's restricted.includeLastResultInCommandResults
will include the value of the last successful execution in allCommandResult
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.errorFilter
: overrides the default set by errorFilterDefault. Iffalse
, Exceptions thrown by the wrapped function won't be caught but rethrown unless there is a listener on errors or results.notifyOnlyWhenValueChanges
: the default is that the command notifies it's listeners even if the value hasn't changed. If you set this totrue
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(), {required TResult initialValue, ValueListenable<bool> ? restriction, void ifRestrictedExecuteInstead()?, bool includeLastResultInCommandResults = false, ErrorFilter? errorFilter, 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 functioninitialValue
sets the.value
of the Command.restriction
:ValueListenable<bool>
that can be used to enable/disable the command based on some other state change.true
means that the Command cannot be executed. If omitted the command can be executed always except it's already executingifRestrictedExecuteInstead
ifrestriction
is set for the command and its value istrue
this function will be called instead of the wrapped function. This is useful if you want to execute a different function when the command is restricted. For example you could show a dialog to let the user logg in if the restriction is because the user is not logged in. If you don't set this function, the command will just do nothing when it's restricted.includeLastResultInCommandResults
will include the value of the last successful execution in allCommandResult
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.errorFilter
: overrides the default set by errorFilterDefault. Iffalse
, Exceptions thrown by the wrapped function won't be caught but rethrown unless there is a listener on errors or results.notifyOnlyWhenValueChanges
: the default is that the command notifies it's listeners even if the value hasn't changed. If you set this totrue
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, void ifRestrictedExecuteInstead()?, ErrorFilter? errorFilter, 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 Can't be used with anValueListenableBuilder
because it doesn't have a value, but you can register a handler to wait for the completion of the wrapped function.restriction
:ValueListenable<bool>
that can be used to enable/disable the command based on some other state change.true
means that the Command cannot be executed. If omitted the command can be executed always except it's already executingifRestrictedExecuteInstead
ifrestriction
is set for the command and its value istrue
this function will be called instead of the wrapped function. This is useful if you want to execute a different function when the command is restricted. For example you could show a dialog to let the user logg in if the restriction is because the user is not logged in. If you don't set this function, the command will just do nothing when it's restricted.errorFilter
: overrides the default set by errorFilterDefault. Iffalse
, Exceptions thrown by the wrapped function won't be caught but rethrown unless there is a listener on errors or results.notifyOnlyWhenValueChanges
: the default is that the command notifies it's listeners even if the value hasn't changed. If you set this totrue
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, ExecuteInsteadHandler<TParam> ? ifRestrictedExecuteInstead, ErrorFilter? errorFilter, 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 Can't be used with anValueListenableBuilder
because it doesn't have a value but you can register a handler to wait for the completion of the wrapped function.restriction
:ValueListenable<bool>
that can be used to enable/disable the command based on some other state change.true
means that the Command cannot be executed. If omitted the command can be executed always except it's already executingifRestrictedExecuteInstead
ifrestriction
is set for the command and its value istrue
this function will be called instead of the wrapped function. This is useful if you want to execute a different function when the command is restricted. For example you could show a dialog to let the user logg in if the restriction is because the user is not logged in. If you don't set this function, the command will just do nothing when it's restricted.errorFilter
: overrides the default set by errorFilterDefault. Iffalse
, Exceptions thrown by the wrapped function won't be caught but rethrown unless there is a listener on errors or results.notifyOnlyWhenValueChanges
: the default is that the command notifies it's listeners even if the value hasn't changed. If you set this totrue
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), {required TResult initialValue, ValueListenable< bool> ? restriction, ExecuteInsteadHandler<TParam> ? ifRestrictedExecuteInstead, bool includeLastResultInCommandResults = false, ErrorFilter? errorFilter, bool notifyOnlyWhenValueChanges = false, String? debugName}) → Command<TParam, TResult> -
Creates a Command for a synchronous handler function with parameter that returns a value
func
: handler functioninitialValue
sets the.value
of the Command.restriction
:ValueListenable<bool>
that can be used to enable/disable the command based on some other state change.true
means that the Command cannot be executed. If omitted the command can be executed always except it's already executingifRestrictedExecuteInstead
ifrestriction
is set for the command and its value istrue
this function will be called instead of the wrapped function. This is useful if you want to execute a different function when the command is restricted. For example you could show a dialog to let the user logg in if the restriction is because the user is not logged in. If you don't set this function, the command will just do nothing when it's restricted.includeLastResultInCommandResults
will include the value of the last successful execution in allCommandResult
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.errorFilter
: overrides the default set by errorFilterDefault. Iffalse
, Exceptions thrown by the wrapped function won't be caught but rethrown Iffalse
, Exceptions thrown by the wrapped function won't be caught but rethrown unless there is a listener on errors or results.notifyOnlyWhenValueChanges
: the default is that the command notifies it's listeners even if the value hasn't changed. If you set this totrue
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(), {required TResult initialValue, ValueListenable< bool> ? restriction, void ifRestrictedExecuteInstead()?, bool includeLastResultInCommandResults = false, ErrorFilter? errorFilter, 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 functioninitialValue
sets the.value
of the Command.restriction
:ValueListenable<bool>
that can be used to enable/disable the command based on some other state change.true
means that the Command cannot be executed. If omitted the command can be executed always except it's already executingifRestrictedExecuteInstead
ifrestriction
is set for the command and its value istrue
this function will be called instead of the wrapped function. This is useful if you want to execute a different function when the command is restricted. For example you could show a dialog to let the user logg in if the restriction is because the user is not logged in. If you don't set this function, the command will just do nothing when it's restricted.includeLastResultInCommandResults
will include the value of the last successful execution in allCommandResult
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.errorFilter
: overrides the default set by errorFilterDefault. Iffalse
, Exceptions thrown by the wrapped function won't be caught but rethrown unless there is a listener on errors or results.notifyOnlyWhenValueChanges
: the default is that the command notifies it's listeners even if the value hasn't changed. If you set this totrue
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, void ifRestrictedExecuteInstead()?, ErrorFilter? errorFilter, bool notifyOnlyWhenValueChanges = false, String? debugName}) → Command<void, void> - ////////////////////// Factory functions from here on //////////////////////
-
createSyncNoResult<
TParam> (void action(TParam x), {ValueListenable< bool> ? restriction, ExecuteInsteadHandler<TParam> ? ifRestrictedExecuteInstead, ErrorFilter? errorFilter, 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 functionrestriction
:ValueListenable<bool>
that can be used to enable/disable the command based on some other state change.true
means that the Command cannot be executed. If omitted the command can be executed always except it's already executingifRestrictedExecuteInstead
ifrestriction
is set for the command and its value istrue
this function will be called instead of the wrapped function. This is useful if you want to execute a different function when the command is restricted. For example you could show a dialog to let the user logg in if the restriction is because the user is not logged in. If you don't set this function, the command will just do nothing when it's restricted. 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 anValueListenableBuilder
because it doesn't have a value, but you can register a handler to wait for the completion of the wrapped function.errorFilter
: overrides the default set by errorFilterDefault. Iffalse
, Exceptions thrown by the wrapped function won't be caught but rethrown unless there is a listener on errors or results.notifyOnlyWhenValueChanges
: the default is that the command notifies it's listeners even if the value hasn't changed. If you set this totrue
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 -
createUndoable<
TParam, TResult, TUndoState> (Future< TResult> func(TParam, UndoStack<TUndoState> ), {required TResult initialValue, required UndoFn<TUndoState, TResult> undo, bool undoOnExecutionFailure = true, ValueListenable<bool> ? restriction, ExecuteInsteadHandler<TParam> ? ifRestrictedExecuteInstead, bool includeLastResultInCommandResults = false, ErrorFilter? errorFilter, 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 Can't be used with anValueListenableBuilder
because it doesn't have a value, but you can register a handler to wait for the completion of the wrapped function.undo
: function that undoes the action.initialValue
sets the.value
of the Command.undoOnExecutionFailure
: iftrue
the undo function will be executed automatically if the action fails.restriction
:ValueListenable<bool>
that can be used to enable/disable the command based on some other state change.true
means that the Command cannot be executed. If omitted the command can be executed always except it's already executingifRestrictedExecuteInstead
ifrestriction
is set for the command and its value istrue
this function will be called instead of the wrapped function. This is useful if you want to execute a different function when the command is restricted. For example you could show a dialog to let the user logg in if the restriction is because the user is not logged in. If you don't set this function, the command will just do nothing when it's restricted.errorFilter
: overrides the default set by errorFilterDefault. Iffalse
, Exceptions thrown by the wrapped function won't be caught but rethrown unless there is a listener on errors or results.notifyOnlyWhenValueChanges
: the default is that the command notifies it's listeners even if the value hasn't changed. If you set this totrue
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 -
createUndoableNoParam<
TResult, TUndoState> (Future< TResult> func(UndoStack<TUndoState> ), {required TResult initialValue, required UndoFn<TUndoState, TResult> undo, bool undoOnExecutionFailure = true, ValueListenable<bool> ? restriction, void ifRestrictedExecuteInstead()?, bool includeLastResultInCommandResults = false, ErrorFilter? errorFilter, bool notifyOnlyWhenValueChanges = false, String? debugName}) → Command<void, TResult> -
Creates a undoable Command for an asynchronous handler function with no parameter that returns a value
func
: handler function Can't be used with anValueListenableBuilder
because it doesn't have a value, but you can register a handler to wait for the completion of the wrapped function.undo
: function that undoes the action.initialValue
sets the.value
of the Command.undoOnExecutionFailure
: iftrue
the undo function will be executed automatically if the action fails.restriction
:ValueListenable<bool>
that can be used to enable/disable the command based on some other state change.true
means that the Command cannot be executed. If omitted the command can be executed always except it's already executingifRestrictedExecuteInstead
ifrestriction
is set for the command and its value istrue
this function will be called instead of the wrapped function. This is useful if you want to execute a different function when the command is restricted. For example you could show a dialog to let the user logg in if the restriction is because the user is not logged in. If you don't set this function, the command will just do nothing when it's restricted.errorFilter
: overrides the default set by errorFilterDefault. Iffalse
, Exceptions thrown by the wrapped function won't be caught but rethrown unless there is a listener on errors or results.notifyOnlyWhenValueChanges
: the default is that the command notifies it's listeners even if the value hasn't changed. If you set this totrue
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 -
createUndoableNoParamNoResult<
TUndoState> (Future action(UndoStack< TUndoState> ), {required UndoFn<TUndoState, void> undo, bool undoOnExecutionFailure = true, ValueListenable<bool> ? restriction, void ifRestrictedExecuteInstead()?, ErrorFilter? errorFilter = const ErrorHandlerLocal(), bool notifyOnlyWhenValueChanges = false, String? debugName}) → Command<void, void> -
Creates an undoable Command for an asynchronous handler function with no parameter and no return type
action
: handler function Can't be used with anValueListenableBuilder
because it doesn't have a value, but you can register a handler to wait for the completion of the wrapped function.undo
: function that undoes the action.undoOnExecutionFailure
: iftrue
the undo function will be executed automatically if the action fails.restriction
:ValueListenable<bool>
that can be used to enable/disable the command based on some other state change.true
means that the Command cannot be executed. If omitted the command can be executed always except it's already executingifRestrictedExecuteInstead
ifrestriction
is set for the command and its value istrue
this function will be called instead of the wrapped function. This is useful if you want to execute a different function when the command is restricted. For example you could show a dialog to let the user logg in if the restriction is because the user is not logged in. If you don't set this function, the command will just do nothing when it's restricted.errorFilter
: overrides the default set by errorFilterDefault. Iffalse
, Exceptions thrown by the wrapped function won't be caught but rethrown unless there is a listener on errors or results.notifyOnlyWhenValueChanges
: the default is that the command notifies it's listeners even if the value hasn't changed. If you set this totrue
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 -
createUndoableNoResult<
TParam, TUndoState> (Future action(TParam, UndoStack< TUndoState> ), {required UndoFn<TUndoState, void> undo, bool undoOnExecutionFailure = true, ValueListenable<bool> ? restriction, ExecuteInsteadHandler<TParam> ? ifRestrictedExecuteInstead, ErrorFilter? errorFilter, bool notifyOnlyWhenValueChanges = false, String? debugName}) → Command<TParam, void> -
Creates an undoable Command for an asynchronous handler function with one parameter and no return type
action
: handler function Can't be used with anValueListenableBuilder
because it doesn't have a value, but you can register a handler to wait for the completion of the wrapped function.undo
: function that undoes the action.undoOnExecutionFailure
: iftrue
the undo function will be executed automatically if the action fails.restriction
:ValueListenable<bool>
that can be used to enable/disable the command based on some other state change.true
means that the Command cannot be executed. If omitted the command can be executed always except it's already executingifRestrictedExecuteInstead
ifrestriction
is set for the command and its value istrue
this function will be called instead of the wrapped function. This is useful if you want to execute a different function when the command is restricted. For example you could show a dialog to let the user logg in if the restriction is because the user is not logged in. If you don't set this function, the command will just do nothing when it's restricted.errorFilter
: overrides the default set by errorFilterDefault. Iffalse
, Exceptions thrown by the wrapped function won't be caught but rethrown unless there is a listener on errors or results.notifyOnlyWhenValueChanges
: the default is that the command notifies it's listeners even if the value hasn't changed. If you set this totrue
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