UserException class
The UserException is an immutable class representing an error the user could fix, like wrong typed text, or missing internet connection.
Async Redux will automatically capture UserExceptions to show them in
dialogs created with UserExceptionDialog
or other UI you define in your
widget tree (see the explanation in the docs).
An UserException may have a message or an error code (if you provide both, the message will be ignored), as well as an optional reason, which is a more specific text that explains why the exception happened. For example:
throw UserException('Invalid email', reason: 'Must have at least 5 characters.');
Method titleAndContent returns the title and content used in the error dialog. If the exception has both a message an a reason, the title will be the message, and its content will be the reason. Otherwise, the title will be empty, and the content will be the message.
Alternatively, if you provide a numeric code instead of a message. In this case, the message of the exception will be the one associated with the code (see translateCode and codeTranslations) for more details.
The following methods and fields are available only in the async_redux
package
(for Flutter), and are not available for Dart-only code:
-
Method
addCallbacks
is used to addonOk
andonCancel
callbacks to the UserException. TheonOk
callback will be called when the user taps OK in the error dialog. TheonCancel
callback will be called when the user taps CANCEL in the error dialog. If the exception already had callbacks, the new callbacks will be merged with the old ones, and the old callbacks will be called before the new ones. -
Field
onOk
is a callback to be called when the user presses the "Ok" button in the error dialog. -
Field
onCancel
is a callback to be called when the user presses the "Cancel" button in the error dialog. -
Method
addCause
adds the givencause
to the UserException. Note the addedcause
won't replace the original cause, but will be added to it. If the addedcause
is anull
, it will return the current exception, unchanged. If the addedcause
is a String, the addReason method will be used to return the new exception. If the addedcause
is a UserException, the mergedWith method will be used to return the new exception. If the addedcause
is any other type, including any other error types, it will be set as the propertyhardCause
of the exception. The hard cause is meant to be some error which caused the UserException, but that is not a UserException itself. For example, ifint.parse('a')
throws aFormatException
, thenthrow UserException('Invalid number').addCause(FormatException('Invalid input'))
. will set theFormatException
as the hard cause. -
Field
hardCause
the hard cause of the exception, if any, that may have been set by the methodaddCause
. -
Method
addProps
adds key-value pair properties to the UserException. If the exception already had properties, the newprops
will be merged with the old ones. -
Field
props
is the properties added to the exception, if any. They are an immutable-map of key-value pairs, of typeIMap<String, dynamic>
. To read the properties, use the[]
operator, like this:exception.props['key']
. If the key does not exist, it will returnnull
.
Usage:
UserException(message, code: code, reason: reason)
.addCallbacks(onOk: onOk, onCancel: onCancel)
.addCause(cause)
.withProps(props);
Example:
throw UserException('Invalid number')
.addCause(FormatException('Invalid input'))
.addProps({'number': 42}))
.addCallbacks(onOk: () => print('OK'), onCancel: () => print('CANCEL'));
You can define a special Matcher
for your UserException, to use in your
tests. Create an test util file with this code:
import 'package:matcher/matcher.dart';
const Matcher throwsUserException = Throws(const TypeMatcher<UserException>());
Then use it in your tests:
expect(() => someFunction(), throwsUserException);
- Implemented types
- Implementers
- Available Extensions
Constructors
- UserException(String? message, {int? code, String? reason, bool ifOpenDialog = true, String? errorText})
-
Creates a UserException, given a message message of type String,
a reason of type String or UserException, and an optional numeric code.
All fields are optional, but usually at least the message or code is provided.
const
Properties
- code → int?
-
Optionally, instead of message we may provide a numeric code.
This code may have an associated message which is set in the client.
final
- errorText → String?
-
Some text to be displayed in the UI element that is responsible for the error.
For example, a text field could show this text in its
errorText
property. When building your widgets, you can get the errorText from the failed action:String errorText = context.exceptionFor(MyAction)?.errorText
.final - hashCode → int
-
The hash code for this object.
no setteroverride
- ifOpenDialog → bool
-
If
true
, the UserExceptionDialog will show in the dialog or similar UI. Iffalse
you can still show the error in a different way, usually showing errorText in the UI element that is responsible for the error.final - message → String?
-
Some message shown to the user.
final
- noDialog → UserException
-
no setter
- reason → String?
-
Another text which is the reason of the user-exception.
final
- runtimeType → Type
-
A representation of the runtime type of the object.
no setterinherited
Methods
-
addReason(
String? reason) → UserException -
Returns a new UserException, copied from the current one, but adding the given
reason
. Note the addedreason
won't replace the original reason, but will be added to it. -
mergedWith(
UserException? anotherUserException) → UserException -
Returns a new UserException, by merging the current one with the given
anotherUserException
. This simply means the givenanotherUserException
will be used as part of the reason of the current one. -
noSuchMethod(
Invocation invocation) → dynamic -
Invoked when a nonexistent method or property is accessed.
inherited
-
titleAndContent(
) → (String, String) - Based on the message, code and reason, returns the title and content to be used in some UI to show the exception the user. The UI is usually a dialog or toast.
-
toString(
) → String -
A string representation of this object.
override
-
withDialog(
bool ifOpenDialog) → UserException - Defines if this exception should open a dialog or not. If not, it will be shown in a different way, usually showing errorText somewhere in the UI.
-
withErrorText(
String? newErrorText) → UserException -
Adds (or replaces, if it already exists) the given
newErrorText
. If thenewErrorText
isnull
or empty, it will remove the errorText.
Operators
-
operator ==(
Object other) → bool -
The equality operator.
override
Static Properties
-
codeTranslations
↔ Translations<
dynamic, Map< ?StringLocale, StringTranslated> , Map<dynamic, StringTranslated> , dynamic> -
If you use error codes, you may provide their respective text messages here,
by providing a
Translations
object from thei18n_extension
package. You can only provide messages in English, or in multiple other languages.getter/setter pair - defaultJoinString ↔ String Function()
-
The default text to join the reasons in a string.
You can change this variable to inject another way to join them.
getter/setter pair
- joinCauses ↔ String Function(String? first, String? second)
-
Joins the given strings, such as the second is the reason for the first.
Will return a message such as "first\n\nReason: second".
You can change this variable to inject another way to join them.
getter/setter pair
- translateCode ↔ String Function(int?)
-
The translateCode method is called to convert error codes into text messages.
If you are using use the
i18n_extension
, you may provide codeTranslations. If you are NOT using thei18n_extension
, you can instead modify the translateCode method to return a string from the code in any way you want.getter/setter pair
Static Methods
-
setLocale(
String? localeStr) → void - Use this to set the locale used by method titleAndContent to translate the text "Reason:" used to explain the chain of reasons in the UserException.