UserException class
Represents an error the user could fix, like wrong typed text, or missing internet connection. Methods dialogTitle and dialogContent return Strings you can show in an error dialog.
An UserException may have an optional cause, which is a more specific root cause of the error.
If the error has a "cause" which is another UserException or String, the dialog-title will be the present exception's msg, and the dialog-content will be the cause. Otherwise, the dialog-title will be an empty string, and the dialog-title will be the present exception's msg.
In other words, If the cause is an UserException or String, it may be used in the dialog. But if the cause is of a different type it's considered just internal information, and won't be shown to the user.
An UserException may also have an optional code, of type ExceptionCode. If there is a non-null code, the String returned by ExceptionCode.asText may be used instead of the msg. This facilitates translating error messages, since ExceptionCode.asText accepts a Locale.
You can define a special Matcher for your UserException, to use in your tests. Create a test lib with this code:
import 'package:matcher/matcher.dart';
const Matcher throwsUserException
= Throws(const TypeMatcher<UserException>());
Then use it in your tests:
expect(() => someFunction(), throwsUserException);
The UserException may be used with the UserExceptionDialog to display the exception to the user. In that case, you may also define callbacks onOk and onCancel.
- Implemented types
Constructors
- UserException(String? msg, {Object? cause, ExceptionCode? code, VoidCallback? onOk, VoidCallback? onCancel})
-
const
- UserException.debug(String? msg, {Object? cause, ExceptionCode? code, VoidCallback? onOk, VoidCallback? onCancel})
-
Adding
.debug
to the constructor will print the exception to the console. Use this for debugging purposes only. This constructor is marked as deprecated so that you don't forget to remove it.
Properties
- cause → Object?
-
The cause of the user-exception. Usually another error.
final
- code → ExceptionCode?
-
The error may have some code. This may be used for error message
translations, and also to simplify receiving errors from web-services,
cloud-functions etc.
final
- hashCode → int
-
The hash code for this object.
no setteroverride
- msg → String?
-
Some message shown to the user.
final
- onCancel → VoidCallback?
-
"Cancel" callback. If the exception has a cause, will return a merged callback.
no setter
- onOk → VoidCallback?
-
"OK" callback. If the exception has a cause, will return a merged callback.
no setter
- runtimeType → Type
-
A representation of the runtime type of the object.
no setterinherited
Methods
-
dialogContent(
[Locale? locale]) → String -
dialogTitle(
[Locale? locale]) → String -
hardCause(
) → Object? - Returns the first cause which, recursively, is NOT a UserException. If not found, returns null.
-
noSuchMethod(
Invocation invocation) → dynamic -
Invoked when a nonexistent method or property is accessed.
inherited
-
toString(
) → String -
A string representation of this object.
override
-
withoutHardCause(
) → UserException - Returns a deep copy of this exception, but stopping at, and not including, the first cause which is not a UserException.
Operators
-
operator ==(
Object other) → bool -
The equality operator.
override
Static Properties
- joinExceptionMainAndCause ↔ String Function(Locale? locale, String? mainMsg, String? causeMsg)
-
Return the string that join the main message and the reason message.
You can change this variable to inject another way to join them.
getter/setter pair