state_extended 4.1.1

The State Class is extended with State object controllers and lifecycle events.

StateX

An Extension of the State class

This package expands the capabilities of Flutter's State class. This fundamental component of Flutter's state management had room for improvement. The capabilities of Flutter's State class now includes 'State Object Controllers' and the app's 'lifecycle events.'

StateX should not be confused with GetX, however, they do have their similarities. In particular, both involve 'controllers' that generally contain the 'business logic' involved in any given app. GetX has its GetxController class while StateX has its StateXController class.

Installing

I don't always like the version number suggested in the 'Installing' page. Instead, always go up to the 'major' semantic version number when installing my library packages. This means always entering a version number trailing with two zero, '.0.0'. This allows you to take in any 'minor' versions introducing new features as well as any 'patch' versions that involves bugfixes. Semantic version numbers are always in this format: major.minor.patch.

1. patch - I've made bugfixes
2. minor - I've introduced new features
3. major - I've essentially made a new app. It's broken backwards-compatibility and has a completely new user experience. You won't get this version until you increment the major number in the pubspec.yaml file.

And so, in this case, add this to your package's pubspec.yaml file instead:

dependencies:
  state_extended:^4.1.0

Documentation

Turn to this free Medium article for a full overview of the package plus examples:

Example Code

Further examples can be found in its Github repository: example app

//
import 'package:flutter/material.dart';

import 'package:state_extended/state_extended.dart';

void main() => runApp(const MaterialApp(home: MyApp(key: Key('MyApp'))));

/// README.md example app
class MyApp extends StatefulWidget {
  ///
  const MyApp({Key? key}) : super(key: key);

  /// This is the App's State object
  @override
  State createState() => _MyAppState();
}

class _MyAppState extends AppStateX<MyApp> {
  factory _MyAppState() => _this ??= _MyAppState._();
  _MyAppState._() : super(controller: Controller());
  static _MyAppState? _this;

  /// Supplies a widget to AppStateX's InheritedWidget.
  @override
  Widget buildIn(BuildContext context) => const MyHomePage();
}

/// The Home page
class MyHomePage extends StatefulWidget {
  ///
  const MyHomePage({
    Key? key,
    this.title = 'Flutter InheritedWidget Demo',
  }) : super(key: key);

  /// Title of the screen
  // Fields in a StatefulWidget should always be "final".
  final String title;

  @override
  State createState() => _MyHomePageState();
}

/// This is a subclass of the State class.
/// This subclass is linked to the App's lifecycle using [WidgetsBindingObserver]
class _MyHomePageState extends StateX<MyHomePage> {
  /// Let the 'business logic' run in a Controller
  _MyHomePageState() : super(Controller()) {
    /// Acquire a reference to the passed Controller.
    con = controller as Controller;
  }

  late Controller con;

  @override
  void initState() {
    /// Look inside the parent function and see it calls
    /// all it's Controllers if any.
    super.initState();

    /// Retrieve the 'app level' State object
    appState = rootState!;

    /// You're able to retrieve the Controller(s) from other State objects.
    final con = appState.controller;

    /// Another way to retrieve the 'app level' State object
    appState = con?.state!.startState as AppStateX;

    /// You can retrieve by type as well
    appState = stateByType<AppStateX>()!;
  }

  late AppStateX appState;

  @override
  Widget build(BuildContext context) => Scaffold(
    appBar: AppBar(title: Text(widget.title)),
    body: Center(
      child: Column(
        mainAxisAlignment: MainAxisAlignment.center,
        children: <Widget>[
          Text(
            'You have pushed the button this many times:',
            style: Theme.of(context).textTheme.bodyMedium,
          ),

          /// Linked to the built-in InheritedWidget.
          /// A Text widget to display the counter is in here.
          /// ONLY IS WIDGET is updated with every press of the button.
          const CounterWidget(),
        ],
      ),
    ),
    floatingActionButton: FloatingActionButton(
      key: const Key('+'),

      /// rebuilds only the Text widget containing the counter.
      onPressed: () => con.onPressed(),
      child: const Icon(Icons.add),
    ),
  );
}

/// Demonstrating the InheritedWidget's ability to spontaneously rebuild
/// its dependent widgets.
class CounterWidget extends StatefulWidget {
  /// Pass along the State Object Controller to make this widget
  /// dependent on the App's InheritedWidget.
  const CounterWidget({super.key});

  @override
  State<StatefulWidget> createState() => _CounterState();
}

class _CounterState extends StateX<CounterWidget> {
  @override
  Widget buildF(BuildContext context) {
    /// Making this widget dependent will cause the build() function below
    /// to run again if and when the App's InheritedWidget calls its notifyClients() function.
    final con = Controller();
    con.dependOnInheritedWidget(context);
    return Text(
      '${con.count}',
      style: Theme.of(context).textTheme.headlineMedium,
    );
  }
}

/// Everything a State object can do, this Controller can do as well!
class Controller extends StateXController {
  /// Utilizing the Singleton pattern is a good programming practice
  factory Controller([StateX? state]) => _this ??= Controller._(state);
  Controller._(StateX? state)
      : _model = Model(),
        super(state);
  static Controller? _this;

  final Model _model;

  /// Note, the count comes from a separate class, _Model.
  int get count => _model.integer;

  /// The Controller deals with the event handling and business logic.
  void onPressed() {
    //
    _model.incrementCounter();
    // Call the InheritedWidget in AppStateX to rebuild its dependents.
    notifyClients();
  }

  /// Used for long asynchronous operations that need to be done
  /// before the app can be fully available to the user.
  /// e.g. Opening Databases, accessing Web servers, etc.
  @override
  Future<bool> initAsync() async {
    // Simply wait for 10 seconds at startup.
    /// In production, this is where databases are opened, logins attempted, etc.
    return Future.delayed(const Duration(seconds: 10), () {
      return true;
    });
  }

  /// Supply an 'error handler' routine if something goes wrong
  /// in initAsync() routine above.
  @override
  bool onAsyncError(FlutterErrorDetails details) => false;

  /// Like the State object, the Flutter framework will call this method exactly once.
  /// Only when the [StateX] object is first created.
  @override
  void initState() {
    super.initState();

    /// A State object can reference it's 'current' State object controller.
    var thisController = state?.controller;

    /// The same controller can be retrieved by its unique identifier if you know it.
    /// You then don't have to know the type or the type is private with a leading underscore.
    /// Note, it has to be a Controller explicitly added to the State object at some time.
    thisController = state?.controllerById(thisController?.identifier);

    assert(thisController == this,
    'Just demonstrating the means to retrieve a Controller.');

    /// You can retrieve a Controller's state object by its StatefulWidget
    /// Good if the state class type is unknown or private with a leading underscore.
    var stateObj = stateOf<MyHomePage>();

    /// Retrieve the 'app level' State object
    final appState = rootState;

    assert(appState is _MyAppState,
    "Every Controller has access to the 'first' State object.");

    /// The 'app level' State object has *all* the Stat objects running in the App
    /// at any one point of time.
    stateObj = appState?.stateByType<_MyHomePageState>();

    /// Retrieve the State object's controller.
    final appController = appState?.controller;

    /// You're able to retrieve the Controller(s) from other State objects.
    /// if you know their unique identifier.
    final con = appState?.controllerById(appController?.identifier);

    assert(appController == con, 'They should be the same object.');
  }

  /// The framework calls this method whenever it removes this [StateX] object
  /// from the tree.
  @override
  void deactivate() {
    super.deactivate();
  }

  /// Called when this object is reinserted into the tree after having been
  /// removed via [deactivate].
  @override
  void activate() {
    super.activate();
  }

  /// The framework calls this method when this [StateX] object will never
  /// build again.
  /// Note: THERE IS NO GUARANTEE THIS METHOD WILL RUN in the Framework.
  @override
  void dispose() {
    super.dispose();
  }

  /// Called when the corresponding [StatefulWidget] is recreated.
  @override
  void didUpdateWidget(StatefulWidget oldWidget) {
    /// The framework always calls build() after calling [didUpdateWidget], which
    /// means any calls to [setState] in [didUpdateWidget] are redundant.
    super.didUpdateWidget(oldWidget);
  }

  /// Called when this [StateX] object is first created immediately after [initState].
  /// Otherwise called only if this [State] object's Widget
  /// is a dependency of [InheritedWidget].
  @override
  void didChangeDependencies() {
    return super.didChangeDependencies();
  }

  /// Called whenever the application is reassembled during debugging, for
  /// example during hot reload.
  @override
  void reassemble() {
    return super.reassemble();
  }

  /// 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.
  /// This method exposes the `popRoute` notification from
  // ignore: comment_references
  /// [SystemChannels.navigation].
  @override
  Future<bool> didPopRoute() async {
    return super.didPopRoute();
  }

  /// Called when the host tells the app to push a new route onto the
  /// navigator.
  /// This method exposes the `pushRoute` notification from
  // ignore: comment_references
  /// [SystemChannels.navigation].
  @override
  Future<bool> didPushRoute(String route) async {
    return super.didPushRoute(route);
  }

  /// Called when the host tells the application to push a new
  /// [RouteInformation] and a restoration state onto the router.
  /// This method exposes the `popRoute` notification from
  // ignore: comment_references
  /// [SystemChannels.navigation].
  ///
  /// The default implementation is to call the [didPushRoute] directly with the
  /// [RouteInformation.location].
  @override
  Future<bool> didPushRouteInformation(RouteInformation routeInformation) {
    return super.didPushRouteInformation(routeInformation);
  }

  /// Called when the application's dimensions change. For example,
  /// when a phone is rotated.
  @override
  void didChangeMetrics() {
    super.didChangeMetrics();
  }

  /// Called when the platform's text scale factor changes.
  @override
  void didChangeTextScaleFactor() {
    super.didChangeTextScaleFactor();
  }

  /// Brightness changed.
  @override
  void didChangePlatformBrightness() {
    super.didChangePlatformBrightness();
  }

  /// Called when the system tells the app that the user's locale has changed.
  @override
  void didChangeLocale(Locale locale) {
    didChangeLocale(locale);
  }

  /// Called when the system puts the app in the background or returns the app to the foreground.
  @override
  void didChangeAppLifecycleState(AppLifecycleState state) {
    /// Passing these possible values:
    /// AppLifecycleState.inactive (may be paused at any time)
    /// AppLifecycleState.paused (may enter the suspending state at any time)
    /// AppLifecycleState.detach
    /// AppLifecycleState.resumed
    super.didChangeAppLifecycleState(state);
  }

  /// The application is in an inactive state and is not receiving user input.
  ///
  /// On iOS, this state corresponds to an app or the Flutter host view running
  /// in the foreground inactive state. Apps transition to this state when in
  /// a phone call, responding to a TouchID request, when entering the app
  /// switcher or the control center, or when the UIViewController hosting the
  /// Flutter app is transitioning.
  ///
  /// On Android, this corresponds to an app or the Flutter host view running
  /// in the foreground inactive state.  Apps transition to this state when
  /// another activity is focused, such as a split-screen app, a phone call,
  /// a picture-in-picture app, a system dialog, or another window.
  ///
  /// Apps in this state should assume that they may be [pausedLifecycleState] at any time.
  @override
  void inactiveLifecycleState() {
    super.inactiveLifecycleState();
  }

  /// The application is not currently visible to the user, not responding to
  /// user input, and running in the background.
  @override
  void pausedLifecycleState() {
    super.pausedLifecycleState();
  }

  /// Either be in the progress of attaching when the engine is first initializing
  /// or after the view being destroyed due to a Navigator pop.
  @override
  void detachedLifecycleState() {
    super.detachedLifecycleState();
  }

  /// The application is visible and responding to user input.
  @override
  void resumedLifecycleState() {
    super.resumedLifecycleState();
  }

  /// Called when the system is running low on memory.
  @override
  void didHaveMemoryPressure() {
    super.didHaveMemoryPressure();
  }

  /// Called when the system changes the set of active accessibility features.
  @override
  void didChangeAccessibilityFeatures() {
    super.didChangeAccessibilityFeatures();
  }
}

/// This example has a separate class that contains the data.
class Model {
  /// the public API for this class. Describes you're dealing with an integer.
  int get integer => _integer;
  int _integer = 0;

  /// The business logic involves incrementing an integer.
  int incrementCounter() => ++_integer;
}