StateX<T extends StatefulWidget> class Get started StateX class Using FutureBuilder Using InheritedWidget Error handling Testing Event handling

An extension of Flutter's State class.

dartdoc:

Inheritance

• Object
• State<StatefulWidget>
• StateX

Implemented types

• StateXEventHandlers

Mixed-in types

• WidgetsBindingObserver
• WidgetsBindingInstanceMixin
• StateXControllersByTypeMixin
• AppStateMixin
• FutureBuilderStateMixin
• AsyncOps
• StateXEventHandlers
• StateXonErrorMixin
• InheritedWidgetStateMixin
• ErrorInErrorHandlerMixin
• MapOfStateXsMixin

Implementers

• AppStateX
• ControllersByIdMixin

Constructors

StateX.new({StateXController? controller, bool? runAsync, bool? useInherited, bool? printEvents, bool? debugPrintEvents})

With an optional StateXController parameter. Two indicators to use built-in FutureBuilder & InheritedWidget. printEvents deprecated. Use debugPrintEvents instead. debugPrintEvents will print events to console.

Properties

appCon → StateXController?

Returns 'the first' StateXController associated with this StateX object. Returns null if empty.

no setter, inherited

appStateX ↔ AppStateX<StatefulWidget>?

The App's State object

getter/setter pair, override-getter

builderOverridden → bool

A flag. Note if builder() function was overridden or not.

no setter, inherited

buildFOverridden → bool

A flag. If the buildF() function was overridden or not.

no setter, inherited

buildOverridden → bool

A flag. If the build() function was overridden or not.

no setter, inherited

caughtAsyncError → bool

A flag. An Async error was caught or not

no setter, inherited

context → BuildContext

The location in the tree where this widget builds.

no setter, inherited

controller → StateXController?

Provide the 'main' controller to this State object. If _controller == null, get the 'first assigned' controller if any.

no setter

controllerList → List<StateXController>

List the controllers.

no setter, inherited

dataObject ↔ Object?

This is of type Object allowing you to propagate any class object you wish down the widget tree.

getter/setter pair, inherited

deactivated → bool

State object's deactivated() was called.

no setter

debugPrintEvents ↔ bool

debugPrint the 'event handlers'

getter/setter pair, inherited

detachedAppLifecycle → bool

State object was in 'paused' state

no setter

disposed → bool

Flag indicating this State object is disposed. Will be garbage collected. property, mounted, is then set to false.

no setter

firstBuild → bool

State object's first build or will be its first build

no setter

firstCon → StateXController?

Returns 'the first' StateXController associated with this StateX object. Returns null if empty.

no setter, inherited

firstState → State<StatefulWidget>?

Return the first State object

no setter, inherited

hadSystemEvent → bool

State object experienced a system event

no setter

hasErrorInErrorHandler → bool

no setter, inherited

hashCode → int

The hash code for this object.

no setter, inherited

hiddenAppLifecycle → bool

All views of an application are hidden, either because the application is about to be paused (on iOS and Android), or because it has been minimized or placed on a desktop that is no longer visible (on non-web desktop), or is running in a window or tab that is no longer visible (on the web). State object was in a 'hidden' state

no setter

identifier → String

The unique identifier for this State object.

no setter, override

inactiveAppLifecycle → bool

Proven too unreliable to call deactivate. gp 25Jun2025 State object was in 'inactive' state

no setter

inDebugMode → bool

Determines if running in an IDE or in production. Returns true if the App is under in the Debugger and not production.

no setter, inherited

inFlutterTest → bool

Indicate if running under a 'Flutter Test' environment

no setter, inherited

initAsyncCalled → bool

Flag indicating initAsync() has been called

no setter, inherited

inWidgetsFlutterBinding → bool

Indicating app is running in the Flutter engine and not in the flutter_test framework with TestWidgetsFlutterBinding for example

no setter, inherited

isLastState → bool

This is the 'latest' State being viewed by the App.

no setter

lastCon → StateXController?

Returns 'the last' StateXController associated with this StateX object. Returns null if empty.

no setter, inherited

lastContext → BuildContext?

Returns the 'latest' context in the App.

no setter, inherited

lastState → State<StatefulWidget>?

Return the 'latest' State object

no setter, inherited

logStateXError ↔ bool

Flag whether to log error details or not

getter/setter pair, inherited

mounted → bool

Whether this State object is currently in a tree.

no setter, inherited

pausedAppLifecycle → bool

The application is not currently visible to the user, not responding to user input, and running in the background. (Called only in iOS, Android) State object was in 'paused' state

no setter

printEvents → bool

no setter, inherited

recErrorException → Object?

The Error or Exception

no setter, inherited

recErrorMsg → String

Simply display the exception.

no setter, inherited

recHasError → bool

Indicate if an exception had occurred.

no setter, inherited

recStackTrace → StackTrace?

The StackTrace

no setter, inherited

resumedAppLifecycle → bool

Proven too unreliable to call activate. gp 25Jun2025 State object was in 'resumed' state

no setter

rootCon → StateXController?

no setter, inherited

rootState → AppStateX<StatefulWidget>?

Returns the 'first' StateX object in the App

no setter, inherited

runtimeType → Type

A representation of the runtime type of the object.

no setter, inherited

snapshot → AsyncSnapshot<bool>?

Supply the AsyncSnapshot

no setter, inherited

useInherited → bool

A flag determining whether the built-in InheritedWidget is used or not.

no setter, inherited

usingCupertino → bool

Is the CupertinoApp being used?

no setter, inherited

widget → T

Access the StatefulWidget widget.

no setter, override

Methods

activate() → void

Called when this object is reinserted into the tree after having been removed via deactivate.

override

add(StateXController? controller) → String

Add a specific StateXController to this State object. Returns the StateXController's unique String identifier.

override

addAll(List<StateXController>? list) → List<String>

Add a list of 'Controllers' to be associated with this StatX object.

override

addList(List<StateXController>? list) → List<String>

override

build(BuildContext context) → Widget

Describes the part of the user interface represented by this widget.

inherited

builder(BuildContext context) → Widget

Use this function instead of the build() function

inherited

buildF(BuildContext context) → Widget

Called by build. Calls built-in InheritedWidget dartdoc: {@category StateX class}

inherited

catchAsyncError(Object error) → Future<bool>

Catch it if the initAsync() throws an error WITH GREAT POWER COMES GREAT RESPONSIBILITY Return true to ignore the error, false to continue the error handling

inherited

contains(StateXController con) → bool

Returns true if found.

inherited

containsType<T>() → bool

Returns true if found

inherited

controllerById(String? id) → StateXController?

Retrieve a StateXController by its a unique String identifier.

override

controllerByType<U extends StateXController>() → U?

Retrieve a StateXController by type.

override

deactivate() → void

Called with every StateX associated with this Controller Initialize any 'time-consuming' operations at the beginning. Implement any asynchronous operations needed done at start up. initAsync() has failed and a 'error' widget instead will be displayed. This takes in the snapshot.error details. The framework calls this method whenever it removes this State object from the tree.

override

debugFillProperties(DiagnosticPropertiesBuilder properties) → void

Add additional properties associated with the node.

inherited

dependOnInheritedWidget(BuildContext? context) → bool

Set the specified widget (through its context) as a dependent of the InheritedWidget

inherited

detachedAppLifecycleState() → void

Either be in the progress of attaching when the engine is first initializing or after the view being destroyed due to a Navigator pop. The application is still hosted on a flutter engine but is detached from any host views. Its firing will depending on the hosting operating system: https://github.com/flutter/flutter/issues/124945#issuecomment-1514159238

override

didChangeAccessibilityFeatures() → void

Called when the system changes the set of currently active accessibility features.

override

didChangeAppLifecycleState(AppLifecycleState state) → void

Called when the system puts the app in the background or returns the app to the foreground.

override

didChangeDependencies() → void

This method is also called immediately after initState. Otherwise called only if this State object's Widget is a dependency of InheritedWidget. When a InheritedWidget's build() function is called the dependent widget's build() function is also called but not before their didChangeDependencies() function. Subclasses rarely use this method.

override

didChangeLocales(List<Locale>? locales) → void

Called when the system tells the app that the user's locale has changed. For example, if the user changes the system language settings.

override

didChangeMetrics() → void

Called when the application's dimensions change. For example, when a phone is rotated.

override

didChangePlatformBrightness() → void

Called when the platform brightness changes.

override

didChangeTextScaleFactor() → void

Called when the platform's text scale factor changes.

override

didChangeViewFocus(ViewFocusEvent event) → void

Called whenever the PlatformDispatcher receives a notification that the focus state on a view has changed.

inherited

didHaveMemoryPressure() → void

Called when the system is running low on memory.

override

didPop() → void

Called when this route has been popped off.

override

didPopNext() → void

The top route has been popped off, and this route shows up.

override

didPopRoute() → Future<bool>

Called when the system tells the app to pop the current route. For example, on Android, this is called when the user presses the back button. Observers are notified in registration order until one returns true. If none return true, the application quits.

override

didPush() → void

Called when this route has been pushed.

override

didPushNext() → void

New route has been pushed, and this route is no longer visible.

override

didPushRoute(String route) → Future<bool>

Called when the host tells the app to push a new route onto the navigator.

override

didPushRouteInformation(RouteInformation routeInformation) → Future<bool>

Called when the host tells the application to push a new RouteInformation and a restoration state onto the router.

override

didRequestAppExit() → Future<AppExitResponse>

Called when a request is received from the system to exit the application.

override

didUpdateController({StateXController? oldCon, StateXController? newCon}) → bool

Update the 'first' controller if necessary Place in the didUpdateWidget function in the special case the StatefulWidget supplies the controller: e.g. didUpdateController(oldWidget.controller, widget.controller);

didUpdateWidget(covariant T oldWidget) → void

Override this method to respond when its StatefulWidget is re-created. The framework always calls build after calling didUpdateWidget, which means any calls to setState in didUpdateWidget are redundant.

override

dispose() → void

The framework calls this method when this StateX object will never build again and will be disposed of with garbage collection.

override

forEach(void func(StateXController con), {bool? reversed}) → bool

To externally 'process' through the controllers. Invokes func on each StateXController possessed by this StateX object. With an option to process in reversed chronological order

inherited

forEachState(void func(State<StatefulWidget> state), {bool? reversed, State<StatefulWidget>? remove}) → bool

To externally 'process' through the State objects. Invokes func on each StateX possessed by this StateX object. With an option to process in reversed chronological order

inherited

forEachStateX(void func(StateX<StatefulWidget> state), {bool? reversed, State<StatefulWidget>? remove}) → bool

To externally 'process' through the StateX objects. Invokes func on each StateX possessed by this StateX object. With an option to process in reversed chronological order

inherited

handleCancelBackGesture() → void

Called when a predictive back gesture is canceled, indicating that no navigation should occur.

override

handleCommitBackGesture() → void

Called when a predictive back gesture is finished successfully, indicating that the current route should be popped.

override

handleStartBackGesture(PredictiveBackEvent backEvent) → bool

Called at the start of a predictive back gesture. If an observer returns true then that observer, and only that observer, will be notified of subsequent events in this same gesture (for example handleUpdateBackGestureProgress, etc.).

override

handleUpdateBackGestureProgress(PredictiveBackEvent backEvent) → void

Called when a predictive back gesture moves.

override

hiddenAppLifecycleState() → void

All views of an application are hidden, either because the application is about to be paused (on iOS and Android), or because it has been minimized or placed on a desktop that is no longer visible (on non-web desktop), or is running in a window or tab that is no longer visible (on the web).

inherited

inactiveAppLifecycleState() → void

The application is in an inactive state and is not receiving user input.

inherited

initAsync() → Future<bool>

Asynchronous operations must complete successfully.

override

initAsyncState(covariant State<StatefulWidget> state) → Future<bool>

Called with every StateX associated with this Controller Initialize any 'time-consuming' operations at the beginning. Implement any asynchronous operations needed done at start up.

inherited

initState() → void

The framework will call this method exactly once. Only when the StateX object is first created.

override

listControllers(List<String?>? ids) → List<StateXController?>

Returns the list of 'Controllers' but you must know their keys.

inherited

listStates(List<String> keys) → List<State<StatefulWidget>>

Returns a List of StateX objects using unique String identifiers.

inherited

logErrorDetails(FlutterErrorDetails details, {bool? force}) → void

Logs 'every' error as the error count is reset. force - Forces the log despite flag setting of logStateXError

inherited

noSuchMethod(Invocation invocation) → dynamic

Invoked when a nonexistent method or property is accessed.

inherited

notifyClients() → bool

In harmony with Flutter's own API there's also a notifyClients() function Rebuild the InheritedWidget of the 'closes' InheritedStateX object if any.

inherited

ofState<T extends State<StatefulWidget>>() → T?

Consistent with the equivalent in the StateXController class

inherited

onAsyncError(FlutterErrorDetails details) → void

initAsync() has failed and a 'error' widget instead will be displayed. This takes in the snapshot.error details.

inherited

onError(FlutterErrorDetails details) → void

Offer an error handler

inherited

onSplashScreen(BuildContext context) → Widget?

Supply a 'splash screen' while the FutureBuilder is processing.

inherited

pausedAppLifecycleState() → void

The application is not currently visible to the user, not responding to user input, and running in the background.

inherited

reassemble() → void

During development, if a hot reload occurs, the reassemble method is called. This provides an opportunity to reinitialize any data that was prepared in the initState method.

override

recordErrorInHandler([Object? error, StackTrace? stack]) → Object?

inherited

recordException([Object? error, StackTrace? stack]) → Object?

Return the 'last' error if any.

inherited

remove(StateXController? controller) → bool

Remove a specific StateXController to this State object. Returns the StateXController's unique String identifier.

override

removeByKey(String? id) → bool

Remove a specific 'StateXController' by its unique 'key' identifier.

inherited

resumedAppLifecycleState() → void

The application is visible and responding to user input.

inherited

runInitAsync() → bool

Calls initAsync() all the time if returns true. Conditional calls initAsync() creating a Future with every rebuild

override

setBuilder(WidgetBuilder? builder) → Widget

Called when the State's InheritedWidget is called again This 'widget builder' will be called again.

inherited

setState(VoidCallback fn) → void

Allows 'external' routines to call this function.

override

stateById(String? id) → State<StatefulWidget>?

Returns a State object using a unique String identifier.

inherited

stateByType<T extends State<StatefulWidget>>() → T?

Retrieve the State object by type Returns null if not found

inherited

statesById(List<String> ids) → Map<String, State<StatefulWidget>>

Returns a Map of StateView objects using unique String identifiers.

inherited

stateSet(WidgetBuilder? builder) → Widget

inherited

statesList({bool? reversed, State<StatefulWidget>? remove}) → List<State<StatefulWidget>>

Return a List of available StateX objects

inherited

toDiagnosticsNode({String? name, DiagnosticsTreeStyle? style}) → DiagnosticsNode

Returns a debug representation of the object that is used by debugging tools and by DiagnosticsNode.toStringDeep.

inherited

toString({DiagnosticLevel minLevel = DiagnosticLevel.info}) → String

A string representation of this object.

inherited

toStringShort() → String

A brief description of this object, usually just the runtimeType and the hashCode.

inherited

updateShouldNotify(covariant InheritedWidget oldWidget) → bool

Determine if its dependencies should be updated.

override

Operators

operator ==(Object other) → bool

The equality operator.

inherited