Introduction

We often talk about State Management but rather little about the notion of State Restoration.

This notion, often ignored, can be quite important in certain types of applications in order to provide comfort to users and avoid any frustration related to potentially having to restart what they had just done as a result of the application being put into background... by the receipt of a simple phone call, for example...

This article explains why to use, how it works and how to implement State Restoration.

Impact of backgrounding your application

Suppose you were finalizing an order as well as the form that had taken you 2 minutes to complete, you were about to press the "Send" button and you get a phone call.... Your app goes into the background during your phone call, and when you come back to your app, your shopping cart is empty, and so is your form.... Wow... the frustration.

It's important to know that when your application is put into the background, whether as a result of a user action or involuntarily, when receiving a phone call, for example, your application may be terminated by the operating system in order to free up resources. When this happens and your application returns to the foreground, it restarts from square zero.

What is State Restoration?

The State Restoration is a mechanism that allows you to ensure that certain data is automatically saved when the application is set to background and can be retrieved when the application is restarted.

By data we mean not only values but also parts of the user interface (Route, TextFields, Scrolling...) that help give users the impression that the application has never been killed.

To make this possible, your application must follow certain rules and thus be defined for this purpose from the beginning.

Let's see how to achieve this step by step.

Preliminary configuration for your tests

In order to be able to test the State Restoration during your developments, it's essential to make sure that your application will be killed by the OS as soon as you put it in the background.

Here's how to do it, depending on whether you're working on Android or iOS.

Android

On Android, whether on a real phone or a simulator, it's pretty straightforward.

1. Put the phone or simulator in Development mode.

   a. Open the application "Settings"

   b. Enter the "About phone / About emulated device"

   c. Then in the "Software information"

   d. Locate the "Build number" and press 7 times in a row.

   After the 7 presses, you'll see a message informing you that your phone has switched to "Development" mode. A new "Developer options" menu is added to the application "Settings"

2. Enter the "Developer options" menu

   a. Scroll to the end and locate the "Applications" group ("Apps")

   b. Enable the "Don't keep activities" option

iOS

For iOS, this requires more preparation at XCode level. Please refer to this guide for the iOS part: State Restoration on iOS.

I find it much easier to test State Restoration on Android than on iOS.

Therefore, I highly recommend that you use an Android phone or Android simulator when developing on a Mac and wish to test your State Restoration implementation.

How does it work in broad terms?

Before we get into the details of how, it's nevertheless interesting to understand the general mechanism of how it works.

1. Operation in 'foreground' mode.

At the end of a Frame (rendering), ALL data ^(*) related to the State Restoration that have been the subject of a modification, are serialized and sent to the Engine (flutter/restoration) which puts them in cache until the OS asks for them.

^(*) in fact these are the Buckets but we'll see all that in detail, later.

Serialization and sending to the Engine are synchronous operations.

It is therefore important to limit the update frequency, the quantity and the size of the data that are part of this operation in order not to create 'jank'.

2. When the Operating System terminates the application

When the application is running in the background and IF the Operating System decides to terminate the application in order to free up resources, the OS will ask the Engine to provide the latest version of the data to be saved. Once done it terminates the application.

It should be noted that the size of data that can be saved is limited to a few K-bytes ^(*)

^(*) despite extensive research, I have not been to find any precise limits

3. Restarting the application

On restart of an application that is designed for State Restoration ^(*), data is retrieved from the Engine in a synchronous manner. Rendering of the application can then begin.

^(*) we'll see how to prepare the application and when rendering actually starts later.

4. Rendering application components

During State Restoration, as components (Widgets...) are rendered, the data linked to them (we'll see how later) is retrieved and "applied", which has the objective and consequence, of reconstructing the arborescence of the Widgets and, in part (I'll explain later), the visual content.

At the end of this operation, the visual appearance of the application should have been restored and the user can continue to use the application "as if nothing had happened".

Hot Reload, Hot Restart, Cold Start

Simple remark before further down into the matter.

The notion of State Restoration does not apply during a Hot Reload, a Hot Restart or a Cold Start of the application.

In other words, any changes to the structure of your code relating to the notion of restoration are not "taken into account" during a Hot Reload. For your modifications to be taken into account, you'll need to stop and restart your application.

I repeat: on "Cold Start" of an application, the State Restoration does NOT apply.

The State Restoration only applies to applications that have been terminated by the OS, which is why I use the term "Restart".

It's quite confusing at first...

Now that the broad outlines have been defined, it's high time to see how to put all this together...

What are the "main components"?

Let's start by looking at the main components, involved in the State Restoration.

RestorationManager (the "coordinator")

The RestorationManager is the coordinator. It is unique in any Flutter application.

It is started as soon as the Bindings are initialized (see Flutter Internals). It handles all communications with the Engine with regard to State Restoration. It is also responsible for the management of the "data" to be sent to the Engine at the end of the next Frame Rendering.

RestorationScope (the "isolation")

Visualize a RestorationScope as a way to structure your application by self-contained restoration blocks, hence the suffix "~Scope".

A RestorationScope is a Widget that can itself contain other RestorationScope among its descendants. Each RestorationScope descendant is independent of its ancestors.

The RootRestorationScope

The very first in the hierarchy is the RootRestorationScope, as its name suggests and should normally be unique within an application.

It is generally positioned as early as possible in the Widgets tree, as soon as the notion of restoration can make sense. It is therefore quite common to find it (but not obligatory) around the runApp() as illustrated below:

void main(){
  runApp(
    const RootRestorationScope(
      restorationId: 'root',
      child: Application(),
    ),
  );
}

It is a special RestorationScope in that it is the one that prepares your application to support State Restoration.

Well, other things still need to be done but, thanks to the presence of a RootRestorationScope, the mechanism for recovering data saved at OS level is set up and the creation of the Root RestorationBucket is carried out.

The RestorationScope

As mentioned above, the RestorationScope is a Widget whose sole purpose is to define a new isolated "area" (or Scope) of restoration and allow retrieval of the main RestorationBucket related to this "area".

At its creation, a RestorationBucket is initialized and inserted into the Widgets tree, via a specialized InheritedWidget, called UnmanagedRestorationScope.

The identity of a RestorationScope is ESSENTIAL and is mentioned via its property: restorationId.

A RestorationScope whose identity is not mentioned (= null) disables the 'State Restoration' for its entire subtree.

This can be useful in some transitional cases, but in most cases you won't need to use this special feature.

Personal note:
It's a pity that the property that is used to define the behavior is called restorationId or restorationScopeId and not enabled as this would have made the explanations easier, as you'll see later.

Is the RootRestorationScope essential?

It depends.

You should know that when you use a MaterialApp or a CupertinoApp, a RootRestorationScope is automatically inserted.

So, if no data needs to be restored upstream, simply mentioning a restorationScopeId at MateriaApp/CupertinoApp level activates the State Restoration and so a prior RootRestorationScope is not necessary.

On the other hand, if you were to retrieve session data, such as: language, currency, theme to be able to initialize your MateriaApp/CupertinoApp, then, you need a RootRestorationScope upstream.

ULTRA important!

If you have a RootRestorationScope upstream, you MUST mention a restorationScopeId at the level of your MateriaApp/CupertinoApp, because, as mentioned earlier, an absence of an identity disables the State Restoration for the entire subtree!!!

The RestorationBucket (the "memory")

As its name suggests the RestorationBucket is a place where information is stored that is exchanged between your application and the OS as part of the State Restoration.

A RestorationBucket is nothing more than a class that:

• has a unique name for the same RestorationScope (we'll see later)
• stores information (the RestorableProperty) in the format as Map<Object?, Object?>, in other words, a series of pairs: key - value
• knew its position in the tree structure: parent - children

While nothing prevents you from doing so, in general, you don't directly manipulate RestorationBuckets but delegate this to the RestorationMixin.

The RestorableProperty (the "data")

Finally, here are the last elements, the RestorableProperty, that is, the data used by the State Restoration.

The following diagram lists the different types of data that are "restorable" and provided for as basic by Flutter. You should already know that nothing prevents you from creating your own types (we'll see how to do this later).

As you can see, a RestorableProperty is a ChangeNotifier. This is used by the RestorationMixin to know when a property has been changed and when it needs to be updated at the RestorableBucket level.

Must we systematically use a RestorableProperty to save/restore data?

No.

You can use any type of data without any problem nevertheless, there are 2 advantages to using RestorableProperty:

1. You use a mixin that takes care of all the complexity involved in managing RestorationBucket and when it's necessary to "save" or "retrieve" this data.
2. Thanks to the use of a RestorableProperty, it is much easier to identify which data is part of the process.

What are the basic supported data types?

The following table draws a parallel between data types and their equivalent restorable.

Other types of RestorableProperty exist, but you won't be using them very often. For the sake of completeness, here they are:

• RestorableRouteFuture
• RestorableCupertinoTabController
• RestorableTextEditingController

State Restoration in practice

Now that we know the State Restoration players, it's time to see how to use them together.

Simple case - l'application "counter"

To get started, let's start with the basic application: the "counter" and adapt its code so that it supports State Restoration.

import 'package:flutter/material.dart';

void main() {
  runApp(const RootRestorationScope(
    restorationId: 'root',
    child: MyApp(),
  ));
}

class MyApp extends StatelessWidget {
  const MyApp({super.key});

  @override
  Widget build(BuildContext context) {
    return MaterialApp(
      title: 'Restorable Counter',
      restorationScopeId: 'application',
      theme: ThemeData(
        colorScheme: ColorScheme.fromSeed(seedColor: Colors.deepPurple),
        useMaterial3: true,
      ),
      home: const MyHomePage(),
    );
  }
}

class MyHomePage extends StatefulWidget {
  const MyHomePage({super.key});

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

class _MyHomePageState extends State<MyHomePage>
    with RestorationMixin<MyHomePage> {
  final RestorableInt _counter = RestorableInt(0);

  void _incrementCounter() {
    setState(() {
      _counter.value++;
    });
  }

  @override
  Widget build(BuildContext context) {
    return Scaffold(
      appBar: AppBar(
        backgroundColor: Theme.of(context).colorScheme.inversePrimary,
        title: const Text('Restorable Demo'),
      ),
      body: Center(
        child: Column(
          mainAxisAlignment: MainAxisAlignment.center,
          children: <Widget>[
            const Text(
              'You have pushed the button this many times:',
            ),
            Text(
              '${_counter.value}',
              style: Theme.of(context).textTheme.headlineMedium,
            ),
          ],
        ),
      ),
      floatingActionButton: FloatingActionButton(
        onPressed: _incrementCounter,
        tooltip: 'Increment',
        child: const Icon(Icons.add),
      ),
    );
  }

  @override
  String? get restorationId => 'counter_page';

  @override
  void restoreState(RestorationBucket? oldBucket, bool initialRestore) {
    registerForRestoration(_counter, 'counter');
  }
}

Explanations:

• lines 4-5: We define the RootRestorationScope and give it a name (as I told you before, in this example we didn't need to insert one, but it's simply to make it more "visible" in terms of explanations)
• line 17: As we've seen, we also need to give a restoration name to a MaterialApp
• line 35: We include the RestorationMixin to help us
• line 36: Instead of using an int, we use its restorable version RestorableInt and initialize it to 0
• line 40: Incrementing takes place at its "value"
• line 59: We retrieve its value
• lines 73-74: We give a name to the RestorationBucket relative to our StatefulWidget that uses the state restoration.
• line 78: We inform the RestorationMixin that the RestorationInt is part of the properties to be saved/restored.

As you can see, it wasn't necessary to make a huge number of changes to make the code compatible.

What about Routes?

Any self-respecting application is not limited to a single "page" and the user will navigate through the application and open "pages" (= Route).

It is therefore also necessary to be able to save these Routes in order to restore them on restart.

Flutter has provided for this possibility and offers variations on the usual Navigator.of(context).xxx():

Of course, only methods relating to adding or modifying the list of routes are taken into consideration. Removing a route (pop) does not require the route to be saved, as it is no longer there.

So, if you want a page to be restored on startup, use the restorablexxx<T>(...) methods.

Here's an example:

class BasketPage extends StatefulWidget {
  const BasketPage({super.key});

  @override
  State<BasketPage> createState() => _BasketPageState();

  //
  // Static Routing
  //
  static Route<Object?> restorableRoute(BuildContext context, Object? arguments) {
    return BasketPage.route();
  }

  static Route<void> route() => MaterialPageRoute(
    settings: BasketPage.routeSettings,
    builder: (BuildContext context) => const BasketPage(),
  );

  static RouteSettings routeSettings = const RouteSettings(name: '/basket_page');
}

class _BasketPageState extends State<BasketPage> {
  ...
}

//
// Code to push the new Route
//
Navigator.of(context).restorablePush<void>(BasketPage.restorableRoute);

Creating a specific type

Suppose you want to store session data in a specific class instance. Since this isn't a basic supported type, how do you go about it?

To illustrate the case, let's look at the code and additional explanations will follow:

class ApplicationSession extends ChangeNotifier {
  String? _language;

  String? get language => _language;

  set language(String? value){
    if (value != _language){
      _language = value;
      notifyListeners();
    }
  }

  // -------------------------------
  // Serialization
  // -------------------------------
  Map<String, dynamic> toJson() => {
    "language": _language,
  };

  // -------------------------------
  // Deserialization
  // -------------------------------
  void loadFromJson(Map<String, dynamic> json) {
    _language = json["language"] as String?;
  }
}

class RestorableApplicationSession extends RestorableListenable<ApplicationSession> {
  // ---------------------------------------------------------------------
  // Called at cold start up of the application to define a default value
  // ---------------------------------------------------------------------
  @override
  ApplicationSession createDefaultValue() {
    // Let's simply return the default value
    return ApplicationSession();
  }

  // ------------------------------------------------------------------
  // Called when the application resumes so that we have to restore
  // the initial state
  // ------------------------------------------------------------------
  @override
  ApplicationSession fromPrimitives(Object? data) {
    final Map<String, dynamic> savedData = Map<String, dynamic>.from(data as Map<Object?, Object?>);

    // We set a new instance
    final ApplicationSession session = ApplicationSession();

    // and initialize it with the restored values
    session.loadFromJson(savedData);

    return session;
  }

  // ------------------------------------------------------------------
  // Called after EITHER createDefaultValue() OR fromPrimitives(...)
  // or at any time a new "value" has been provided by the RestorationMixin
  // Any previous "content" should be replaced by the new "value"
  // IMPORTANT -- If we override this method:
  //    As the internal ".value" is initialized by the RestorableListenable
  //    we absolutely need to invoke the super.initWithValue(value)
  // ------------------------------------------------------------------
  @override
  void initWithValue(ApplicationSession value) {
    super.initWithValue(value);
    // Do whatever you want to do with the instance
  }

  // ------------------------------------------------------------------
  // Called when we need to save the status to allow potential
  // restoration.  Also called after initialization is done.
  // ------------------------------------------------------------------
  @override
  Object? toPrimitives() {
    // Serialization
    return value.toJson();
  }

  // ------------------------------------------------------------------
  // Called when we need to dispose the instance
  // ------------------------------------------------------------------
  @override
  void dispose() {
    // Free up resource, if necessary
    super.dispose();
  }
}

The following table summarizes the life cycles of our RestorableApplicationSession:

The following code shows in an ultra-simplistic way how to use this new type:

void main(){
  runApp(
    const RootRestorationScope(
      restorationId: 'root',
      child: const Application(),
    ),
  );
}

class Application extends StatefulWidget {
  const Application({super.key});

  @override
  State<Application> createState() => _ApplicationState();
}

class _ApplicationState extends State<Application> with RestorationMixin {
  late RestorableApplicationSession restorableApplicationSession;

  // ------------------------------------------------------------------
  // Unique identifier of the RestorationBucket
  // ------------------------------------------------------------------
  @override
  String get restorationId => 'application';

  // ------------------------------------------------------------------
  // Initializes or restores the RestorableProperty used by this State
  // ------------------------------------------------------------------
  @override
  void restoreState(RestorationBucket? oldBucket, bool initialRestore) {

    // Let's initialize the type
    restorableApplicationSession = RestorableApplicationSession();

    // Tell the system that this instance is part of the State Restoration
    registerForRestoration(restorableApplicationSession, 'restoration_application_session');
  }

  ...
}

Nothing else is required in order to integrate this new data type into the restoration mechanism.

You've almost certainly noticed that I didn't instantiate the RestorableApplicationSession directly but used a "late" and that the initialization took place at the level of the restoreState(...) method. Why and is it necessary to do this?

To be able to understand exactly why I did it, we now need to take a look at the RestorationMixin and analyze how everything works.

How does the RestorationMixin work?

If you remember, a RestorationScope simply defines a restoration block isolated from the others. Nothing else.

To be able to save/retrieve data, you need to use RestorationBucket and this is where the RestorationMixin comes in.

The RestorationMixin is responsible for managing the RestorationBucket within the direct RestorationScope to which the StatefulWidget belongs.

1. restorationId

The RestorationMixin requests a UNIQUE restorationId (or a null value) for the RestorationScope direct to which the Widget belongs.

If the restorationId is not null, the RestorationMixin instantiates a RestorationBucket which will be identified by this restorationId.

Data related to THAT Widget and part of the backup/restoration will be saved in THAT bucket.

a. Importance of restorationId being unique

Why is it important for restorationId to be unique?

Simply because

There can NOT be 2 RestorationBuckets with the same name within a RestorationScope.

This uniqueness constraint is important. Therefore, if you have several instances of the same StatefulWidget within the same RestorationScope, you'll need to make sure you use a unique and constant name, as the restorationId will be used as an identifier when saving data, and reused to identify the "owner" of the data when restoring!!!

Tip for multi-instantiable StatefulWidget.

Add a property to your StatefulWidget to control their restorationId and avoid hardcoding the restorationId within the StatefulWidget.

Prefer this kind of signature in order to have better control over the restorationId.

class MyRestorableMultiInstantiableWidget extends StatefulWidget {
  const MyRestorableMultiInstantiableWidget({
    super.key,
    this.restorationId,
    ...
  });

  final String? restorationId;
  ...
}

If it should ever happen to you that it is not possible to know in advance whether 2 instances of Widgets carry the same restorationId within the same RestorationScope, nothing prevents you from creating a new area by inserting a RestorationScope, like this:

@override
Widget build(BuildContext context){
  return Column(
    children: [
      MyRestorableMultiInstantiableWidget(
        restorationId: 'myRestorationId',
      ),
      RestorationScope(
        restorationId: 'zone2',
        child: MyRestorableMultiInstantiableWidget(
          restorationId: 'myRestorationId',
        ),
      ),
    ],
  );
}

As you can see, thanks to having added a RestorationScope, we have created a segmentation that allows me to use the same restorationId.

b. restorationId as activation/deactivation flag

As mentioned above, the same property name "restorationId" is used for RestorationScope and RestorationBucket, which is a shame as it can lead to confusion.

As a reminder, a restorationId that is null is equivalent to disabling restoration.

For a RestorationScope, deactivation takes place at the tree structure started by the RestorationScope.

For a RestorationMixin, deactivation is limited to the StatefulWidget, only.

2. restoreState(...)

Among the methods added by the RestorationMixin, we'll find the restoreState(...) which is called just after the initState().

This is where you mention (and save) the list of RestorableProperty linked to the StatefulWidget instance.

Typical example of use:

@override
void restoreState(RestorationBucket? oldBucket, bool initialRestore) {
  // Let's initialize the type
  restorableApplicationSession = RestorableApplicationSession();

  // Tell the system that this instance is part of the State Restoration
  registerForRestoration(restorableApplicationSession, 'restoration_application_session');
}

It is important to remember that the "registerForRestoration" method is executed synchronously by the mixin and that it will be at the end of this execution that the content of the RestorableProperty will either be initialized or restored, as the case may be.

This explains why

It is generally considered good practice to instantiate all RestorableProperty at the restoreState(...) level in order to be able to manage their potential interdependencies but also other dependencies.

3. StatefulWidget - workflow change

Here's what the "start" workflow looks like for a StatefulWidget that makes use of State Restoration.

Of course, this considers the fact that you respect and call the super.initState() and super.didChangeDependencies() immediately as intended by the framework, that is:

@override
void initState(){
  super.initState();
  // Other initializations
}

@override
void didChangeDependencies(){
  super.didChangeDependencies();
  // Other initializations
}

4. The RestorationMixin is listening...

When you register a RestorableProperty via the registerForRestoration(...) method, the RestorationMixin will start "listening" for changes that might be applied to the RestorationProperty content. This explains why RestorableProperty are ChangeNotifier.

This also explains why:

• any new type of RestorableProperty must refer to a ChangeNotifier
• it's important that you call the dispose() for each RestorationProperty you instantiate.

So, why is it important to know that the mixin is listening?

This is thanks to the fact that the mixin reacts to changes in the contents of the RestorableProperty, that their "value" is saved.

Here's how...

In clear:

• When the content of a RestorableProperty is modified, it notifies all its listeners, including the RestorationMixin.
• The latter retrieves the new content and stores it at the RestorationBucket.
• This warns the RestorationManager that at the end of the next Frame Rendering, it will be necessary to send an update of the data to be restored to the Engine.

Frame Rending (the "trigger")

As we have just seen, saving the data (i.e., sending it to the Engine) is done at the end of the next Frame Rendering.

In 99.9% of cases, we don't need to worry about this however, there may be circumstances where we should modify a RestorableProperty outside of any layout refresh.

This is notably the case with the Scrollable where at the end of a scrolling activity the final scrolling position (offset) is determined between 2 frames, without having to plan a new one.

To cover this extremely rare case, the RestorationManager exposes a method for forcing this save and send to the Engine:

ServicesBinding.instance.restorationManager.flushData();

How to restore the complete layout

At the very beginning of this article, I told you that the size of data that can be saved was limited to a few K-bytes.

This means that you should limit yourself to essential data, and therefore not store all the information.

Suppose the user was in the middle of a product search displayed in an endless ListView. How can we make it look like the user is right back where he was?

Of course, we'll most certainly have saved his identifiers, his language, the search criteria, his scrolling position in the ListView and the key to the product for which he was looking at the details, but it's out of the question to have saved the list of products, their details, their photos, .... So how do you do it?

There's no one-size-fits-all solution, but here's a clue.

1. Identify complex restoration cases

When establishing the architecture of your application, it's important that you think about the case(s) where it would be complex to restore the user interface.

2. Restore mode or not?

How do you determine whether you're in "restore" mode or not?

As we'll see a little further on, from time to time it can be interesting to know whether you're in "restore" mode and to act accordingly.

The most obvious way is based on the existence of the restorationId. If this parameter is null, at least there's no room for doubt. On the other hand, its presence in itself means nothing.

The most obvious way is to check for the existence of a RestorableProperty in the RestorationBucket.

@override
void restoreState(RestorationBucket? oldBucket, bool initialRestore) {
  isRestoring = initialRestore && (bucket?.contains('oneOfMyRestorationId') ?? false);
  ...
}

Although this is the most common way of doing things, there are cases where the restoration of a Widget would be postponed (by, for example not passing the restorationId directly but later). In this case, the restorationState method will not be called. So how do you go about it?

A trick I use from time to time is a "flag" that I position directly at the Root RestorationBucket and remove when my StatefulWidget is laid out.

If I am in "restoration" mode, this means that I didn't have time to remove this flag because the dispose() method hadn't been called. So, if this flag is present at root RestorationBucket level, it means I am in restoration mode.

Here is how I happen to implement it:

class _MyStatefulPageState extends State<MyStatefulPage> with RestorationMixin {
  final String _restorationFlagName = "flag_my_stateful_page";

  bool isRestoring = false;
  RestorationBucket? rootRestorationBucket;

  @override
  void initState() {
    super.initState();
    _determineIfInRestorationMode();
  }

  /// ------------------------------------------------------------------
  /// This routine SYNCHRONOUSLY validates whether we are in Restoration
  /// mode or not, via the presence of a certain flag in the
  /// Root RestorationBucket
  /// ------------------------------------------------------------------
  void _determineIfInRestorationMode() {
    //
    // Prevents the first Frame rendering
    //
    RendererBinding.instance.deferFirstFrame();

    //
    // Retrieve the Root RestorationBucket, if any
    //
    ServicesBinding.instance.restorationManager.rootBucket.then((RestorationBucket? bucket) {
      //
      // Save the RestorationBucket for later re-use
      //
      rootRestorationBucket = bucket;

      //
      // Check if the flag is present
      //
      final bool? flagPresence = bucket?.read(_restorationFlagName);

      //
      // If yes, this means that we are in Restoration mode
      //
      isRestoring = flagPresence == true;

      //
      // Otherwise, let's create the flag
      //
      if (isRestoring == false) {
          bucket?.write(_restorationFlagName, true);
      }

      //
      // Now, we can allow the frame rendering
      //
      RendererBinding.instance.allowFirstFrame();
    });
  }

  @override
  void dispose() {
    //
    // If we dispose the page, we no longer need the flag
    //
    rootRestorationBucket?.remove(_restorationFlagName);
    super.dispose();
  }
}

I agree with you that this implementation is rather tricky... as it is imperative to know the mode at the level of the initState() and that I cannot wait for the didChangeDependencies() as the RestorationMixin will have already called the restoreState(...) (see above).

As the root RestorationBucket is an asynchronous function, and we know very well that restoring the root bucket has already taken place long ago, there is no risk at the level of the initState().

Since retrieving the root RestorationBucket is an asynchronous function, and we know for a fact that restoring the root bucket has already taken place at the time I am executing my code, in order to bypass this asynchronous call, I postpone the Frame Rendering during my verification, via the call to RendererBinding. instance.deferFirstFrame();.

As soon as I have my information, I re-enable the Frame Rendering via the call to RendererBinding.instance.allowFirstFrame();.

So, now I know what mode I am in, which allows me to make the "right" decisions about when to register RestorableProperties...

3. Registering RestorableProperty at the right time

Remember

The contents of RestorableProperties are restored at the time they are "registered" via the call to registerForRestoration(...).

Thus, if you restore them at the wrong time, you won't be able to do so (easily) later.

This is particularly the case with Scrollable whose position in a list would not be (re)set correctly because... your list would be empty at that moment. So how do you go about it?

Restore the RestorableProperty that give you the information you need to recompose complex data and POSTPONE the other RestorableProperty.

4. Recover "heavy"data

Once you've registered the RestorableProperty that lets you know the status of the data and NOT those that provide the display, you can start retrieving the 'heavy' data (for example, via calls to the server).

A good place to launch this function might be at the restoreState.

Here's an example:

@override
void restoreState(RestorationBucket? oldBucket, bool initialRestore) {
  restorableSearchCriteria = RestorableSearchCriteria();
  registerForRestoration(restorableSearchCriteria, 'restorable_search_criteria');

  //
  // Once we have the search criteria AND we are in restoration mode,
  // let's retrieve the items
  //
  if (isRestoring == true) {
    unawaited(_fetchItemsFromServer(oldBucket, initialRestore));
  } else {
    _restoreStateLayoutRelated(oldBucket, initialRestore)
  }
}

void _restoreStateLayoutRelated(RestorationBucket? oldBucket, bool initialRestore){
  //
  // Proceed with the other registration
  //
  registerForRestoration(restorableStatus, 'restorable_status');
}

/// -------------------------------------------------------
/// Restores the data from the server, then, once done,
/// registers the RestorableProperty linked to the layout
/// -------------------------------------------------------
Future<void> _fetchItemsFromServer(RestorationBucket? oldBucket, bool initialRestore) async {
  //
  // Fetch the items from server, for example
  //
  ...

  //
  // Once done, retrieve the _RestorableProperty_ responsible for the layout (if any)
  //
  _restoreStateLayoutRelated(oldBucket, initialRestore);

  //
  // Here, most probably, we will have to force a rebuild but also to tell that you are no
  // longer restoring
  //
  if (mounted){
    setState((){
      isRestoring = false;
    });
  }
}

5. Display lists only after everything has been retrieved

Since all Scrollables (ListView, GridView, SingleChildScrollView, ...) only save the scrollOffset, it becomes obvious that you can only display them once you've retrieved all the data so that repositioning is correct.

From then on, don't forget to use the isRestoring flag to make sure you only display these elements when the data is ready.

Before concluding

Before concluding, it's important to remember that Controllers, including AnimationController, are not saved at all.

More importantly...

Unfortunately, most plugins/packages don't support State Restoration!

I can't advise you enough to check which plugins/packages you're using if you want your application to fully support this notion of State Restoration.

Conclusion

Once again a long article and yet there would still be a lot to say especially about UnmanagedRestorationScope but you can perfectly use State Restoration without this additional knowledge...

I hope this article has served to demystify or simply introduce you to this important and so little-used notion, which is State Restoration.

Stay tuned for future articles and until then, happy coding!

Introduction

When I started up my journey into the fabulous world of Flutter beginning 2018, very little documentation could be found on Internet compared to what exists today. Despite the number of articles that have been written, very few talk about how Flutter actually works.

What are finally the Widgets, the Elements, the BuildContext ? Why is Flutter fast and why does it sometimes work differently than expected? What are the trees?

When you are writing an application, in 95% of the cases, you will only deal with Widgets to either display something or interact with the screen. But haven't you ever wondered how all this magic actually works? How does the system know when to update the screen and which parts need to be updated?

Part 1: The background

This first part of the article introduces some key concepts that will be then used to better understand the second part of this post.

Back to the device

For once, let's start from the end and let's get back to the basics.

When you look at your device, or more specifically at your application running on your device, you only see a screen.

In fact, all what you see is a series of pixels, which together compose a flat image (2 dimensions) and when you are touching the screen with your finger, the device only recognizes the position of your finger on the glass.

All the magic of the application (from a visual perspective) consists in having that flat image updated based on, most of the time, interactions with:

• the device screen (e.g. finger on the glass)
• the network (e.g. communication with a server)
• the time (e.g. animations)
• other external sensors

The rendering of the image on the screen is ensured by the hardware (display device), which at regular interval (usually 60 times per second), refreshes the display. This refresh frequency is also called "refresh rate" and is expressed in Hz (Hertz).

The display device receives the information to be displayed on the screen from the GPU (Graphics Processing Unit), which is a specialized electronic circuit, optimized and designed to rapidly generate an image from some data (polygons and textures). The number of times per second the GPU is able to generate the "image" (=frame buffer) to be displayed and to send it to the hardware is called the frame rate. This is measured with the fps unit (e.g. 60 frames per second or 60 fps).

You will maybe ask me why did I start this article with the notions of 2-dimension flat image rendered by the GPU/hardware and the physical glass sensor... and what is the relationship with the usual Flutter Widgets?

Simply because one of the main objectives of a Flutter application is to compose that 2-dimensional flat image and to make it possible to interact with it, I think it might be easier to understand how Flutter actually works if we look at it from that perspective.

...but also because in Flutter, believe it or not, almost everything is driven by the needs of having to refresh the screen... quickly and at the right moment !

Interface between the code and the physical device

One day or another, everyone interested in Flutter already saw the following picture which describes the Flutter high-level architecture.

When we are writing an Flutter application, using Dart, we remain at the level of the Flutter Framework (in green).

The Flutter Framework interacts with the Flutter Engine (in blue), via an abstraction layer, called Window. This abstraction layer exposes a series of APIs to communicate, indirectly, with the device.

This is also via this abstraction layer that the Flutter Engine notifies the Flutter Framework when, among others:

• an event of interest happens at the device level (orientation change, settings changes, memory issue, application running state...)
• some event happens at the glass level (= gesture)
• the platform channel sends some data
• but also and mainly, when the Flutter Engine is ready to render a new frame

Flutter Framework is driven by the Flutter Engine frame rendering

This statement is quite hard to believe, but it is the truth.

Except in some cases (see below), no Flutter Framework code is executed without having been triggered by the Flutter Engine frame rendering.

These exceptions are:

• Gesture (= an event on the glass)
• Platform messages (= messages that are emitted by the device, e.g. GPS)
• Device messages (= messages that refer to a variation to the device state, e.g. orientation, application sent to background, memory warnings, device settings...)
• Future or http responses

The Flutter Framework will not apply any visual changes without having been requested by the Flutter Engine frame rendering.

(between us, it is however possible to apply a visual change without having been invited by the Flutter Engine, but this is really not advised to do so)

But you will ask me, if some code related to the gesture is executed and causes a visual change to happen, or if I am using a timer to rythm some task, which leads to visual changes (such as an animation, for example), how does this work then?

If you want a visual change to happen, or if you want some code to be executed based on a timer, you need to tell the Flutter Engine that something needs to be rendered.

Usually, at next refresh, the Flutter Engine will then request the Flutter Framework to run some code and eventually provide the new scene to render.

Therefore, the big question is how does Flutter Engine orchestrate the whole application behavior, based on the rendering?

To give you a flavor of the internal mechanisms, have a look at the following animation...

Short explanation (further details will come later):

• Some external events (gesture, http responses, ...) or even futures, can launch some tasks which lead to having to update the rendering. A message is sent to the Flutter Engine to notify it ( = Schedule Frame)
• When the Flutter Engine is ready to proceed with the rendering update, it emits a Begin Frame request
• This Begin Frame request is intercepted by the Flutter Framework, which runs any task mainly related to Tickers (such as Animations, e.g.)
• These tasks could re-emit a request for a later frame rendering... (example: an animation is not complete and to move forward, it will need to receive another Begin frame at a later stage)
• Then, the Flutter Engine emits a Draw Frame.
• This Draw Frame is intercepted by the Flutter Framework, which will look for any tasks linked to updating the layout in terms of structure and size.
• Once all these tasks are done, it goes on with the tasks related to updating the layout in terms of painting.
• If there is something to be drawn on the screen, it then sends the new Scene to be rendered to the Flutter Engine which will update the screen.
• Then, the Flutter Framework executes all tasks to be run after the rendering is complete (= PostFrame callbacks) and any other sub-sequent other tasks not rendering related.
• ... and this flow starts again and again.

RenderView and RenderObject

Before going into the details related to the flow of actions, it is the right time to introduce the notion of Rendering Tree.

As previously said, everything eventually turns out to become a series of pixels to be displayed on the screen and the Flutter Framework converts the Widgets we are using to develop the application into visual parts which will be rendered on the screen.

These visual parts which are rendered on the screen correspond to objects, called RenderObjects, which are used to:

• define some area of the screen in terms of dimensions, position, geometry but also in terms of "rendered content"
• identify zones of the screen potentially impacted by the gestures (= finger)

The set of all the RenderObject forms a tree, called Render Tree. At the top of that tree (= root), we find a RenderView.

The RenderView represents the total output surface of the Render Tree and is itself a special version of a RenderObject.

Visually speaking we could represent all this as follows:

The relationship between Widgets and RenderObjects will be discussed later in this article.

It is now time to go a bit deeper...

First things first - initialization of the bindings

When you start a Flutter application, the system invokes the main() method which will eventually call the runApp(Widget app) method.

During that call to the runApp() method, Flutter Framework initializes the interfaces between the Flutter Framework and the Flutter Engine. These interfaces are called bindings.

The Bindings - Introduction

The bindings are meant to be some kind of glue between the Flutter Engine and the Flutter Framework. It is only through these bindings that data can be exchanged between the two Flutter parts (Engine and Framework).
(There is only one exception to this rule: the RenderView but we will see this later).

Each Binding is responsible for handling a set of specific tasks, actions, events, regrouped by domain of activities.

At time of writing this article, Flutter Framework counts 8 bindings.

Below, the 4 ones that will be discussed in this article:

• SchedulerBinding
• GestureBinding
• RendererBinding
• WidgetsBinding

For sake of completeness, the last 4 ones (which will not be addressed in this article):

• ServicesBinding: responsible for handling messages sent by the platform channel
• PaintingBinding: responsible for handling the image cache
• SemanticsBinding: reserved for later implementation of everything related to Semantics
• TestWidgetsFlutterBinding: used by widgets tests library

I could also mention the WidgetsFlutterBinding but the latter is not really a binding but rather some kind of "binding initializer".

The following diagram shows the interactions between the bindings I am going to cover a bit later in this article and the Flutter Engine.

Let's have a look at each of these "main" bindings.

SchedulerBinding

This binding has 2 main responsibilities:

• the first one is to tell the Flutter Engine: "Hey! next time you are not busy, wake me up so that I can work a bit and tell you either what to render or if I need you to call me again later...";
• the second one is to listen and react to such "wake up calls" (see later)

When does the SchedulerBinding request for a wake-up call?

• When a Ticker needs to tick
  For example, suppose you have an animation and you start it. An animation is cadenced by a Ticker, which at regular interval (= tick) is called to run a callback. To run such callback, we need to tell the Flutter Engine to wake up us at next refresh (= Begin Frame). This will invoke the ticker callback to perform its task. At the end of that task, if the ticker still needs to move forward, it will call the SchedulerBinding to schedule another frame.

• When a change applies to the layout
  When for example, you are responding to an event that leads to a visual change (e.g. updating the color of a part of the screen, scrolling, adding/removing something to/from the screen), we need to take the necessary steps to eventually render it on the screen. In this case, when such change happens, the Flutter Framework will invoke the SchedulerBinding to schedule another frame with the Flutter Engine. (we will see later how it actually works)

GestureBinding

This binding listens to interactions with the Engine in terms of "finger" (= gesture).

In particular, it is responsible for accepting data related to the finger and to determine which part(s) of the screen is/are impacted by the gestures. It then notifies this/these parts accordingly.

RendererBinding

This binding is the glue between the Flutter Engine and the Render Tree. It has 2 distinct responsibilities:

• the first one is to listen to events, emitted by the Engine, to inform about changes applied by the user via the device settings, which impact the visuals and/or the semantics
• the second one is to provide the Engine with the modifications to be applied to the display.

In order to provide the modifications to be rendered on the screen, this Binding is responsible for driving the PipelineOwner and initializing the RenderView.

The PipelineOwner is a kind of orchestrator that knows which RenderObject's need to do something in relation with the layout and coordinates these actions.

WidgetsBinding

This binding listens to changes applied by the user via the device settings, which impact the language (= locale) and the semantics.

Side note

At a later stage, I suppose that all events related to the Semantics will be migrated to the SemanticsBinding but at time of writing this article, this is not yet the case.

Besides this, the WidgetsBinding is the glue between the Widgets and the Flutter Engine. It has 2 distinct main responsibilities:

• the first main one is to drive the process in charge of handling the Widgets structure changes
• the second one is to trigger the rendering

The handling of the Widgets Structure changes is done via the BuildOwner.

The BuildOwner tracks which Widgets need rebuilding, and handles other tasks that apply to widget structures as a whole.

Part 2: from Widgets to pixels

Now that we have introduced the basics of the internal mechanics, it is time to talk about Widgets.

In all Flutter documentation, you will read that everything is Widgets.

Well, it is almost correct but in order to be a bit more precise, I would rather say:

From a Developer perspective, everything related to the User Interface in terms of layout and interaction, is done via Widgets.

Why this precision? Because a Widget allows a developer to define a part of the screen in terms of dimensions, content, layout and interaction BUT there is so much more. So what is a Widget, actually?

Immutable Configuration

When you read the Flutter source code, you will notice the following definition of the Widget class.

@immutable
abstract class Widget extends DiagnosticableTree {
  const Widget({ this.key });

  final Key? key;

  ...
}

What does this mean?

The annotation "@immutable" is very important and tells us that any variable in a Widget class has to be FINAL, in other words: "is defined and assigned ONCE FOR ALL". So, once instantiated, the Widget will no longer be able to adapt its inner variables.

A Widget is a kind of constant configuration since it is IMMUTABLE

The Widgets hierarchical structure

When you develop with Flutter, you define the structure of your screen(s), using Widgets... Something like:

Widget build(BuildContext context){
  return SafeArea(
      child: Scaffold(
          appBar: AppBar(
              title: Text('My title'),
          ),
          body: Container(
              child: Center(
                  child: Text('Centered Text'),
              ),
          ),
      ),
  );
}

This sample uses 7 Widgets, which together form a hierarchical structure. The very simplified structure, based on the code, is the following:

As you can see, this looks like a tree, where the SafeArea is the root of the tree.

The forest behind the tree

As a you already know, a Widget may itself be an aggregation of other Widgets. As an example, I could have written the previous code the following way:

Widget build(BuildContext context){
  return MyOwnWidget();
}

This assumes that the widget "MyOwnWidget" would itself render the SafeArea, Scaffold... but the most important with this example is that

a Widget maybe a leaf, a node in a tree, even a tree itself or why not a forest of trees...

The notion of Element in the tree

Why did I mention this?

As we will see later how, in order to be able to generate the pixels that compose the image to be rendered on the device, Flutter needs to know in details all the little parts that compose the screen and, to determine all the parts, it will request to inflate all the Widgets.

In order to illustrate this, consider the russian dolls principle: closed you only see 1 doll but the latter contains another one which in turn contains another one and so on...

When Flutter will have inflated all the widgets, part of the screen, it will be similar to obtaining all the different russian dolls, part of the whole.

The following diagram shows a part of the final Widget hierarchical structure that corresponds to the previous code. In yellow, I have highlighted the Widgets that were mentioned in the code so that you can spot them in the resulting partial widgets tree.

Important clarification

The wording "Widget tree" only exists for sake of making it easier to understand since programmers are using Widgets but, in Flutter there is NO Widget tree!

In fact, to be correct, we should rather say: "tree of Elements"

It is now time to introduce the notion of Element...

To each widget corresponds one element. Elements are linked to each other and form a tree. Therefore an element is a reference of something in the tree.

At first, think of an element as a node which has a parent and potentially a child. Linked together via the parent relationship, we obtain a tree structure.

As you can see in the picture above, the Element points to one Widget and may also point to a RenderObject.

Even better... the Element points to the Widget which created the element !

Let me recap...

• there is no Widgets tree but a tree of Elements
• Elements are created by the Widgets
• an Element references the Widget that created it
• Elements are linked together with the parent relationship
• Elements could have a child or children
• Elements could also point to a RenderObject

Elements define how parts of the visuals are linked to each other

In order to better visualize where the notion of element fits, let's consider the following visual representation:

As you can see the elements tree is the actual link between the Widgets and the RenderObjects.

But, why does the Widget create the Element?

3 main categories of Widgets

In Flutter, Widgets are split into 3 main categories, I personally call these categories:
(but this is only my way of categorizing them)

• the proxies

  The main role of these Widgets is to hold some piece of information which needs to be made available to the Widgets, part of the tree structure, rooted by the proxies. A typical example of such Widgets is the InheritedWidget or LayoutId.

  These Widgets do not directly take part of the User Interface but are used by others to fetch the information they can provide.

• the renderers

  These Widgets have a direct involvement with the layout of the screen as they define (or are used to infer) either:

  • the dimensions;
  • the position;

  • the layout, rendering.

    Typical examples are: Row, Column, Stack but also Padding, Align, Opacity, RawImage...

• the components.

  These are the other Widgets which are not directly providing the final information related to dimensions, positions, look but rather data (or hint) which will be used to obtain the final information. These Widgets are commonly named components.

  Examples are: RaisedButton, Scaffold, Text, GestureDetector, Container...

The following PDF lists most of the Widgets, regrouped by categories.

Why is that split important? Because depending on the Widget category, a corresponding Element type is associated...

The Element types

Here are the different element types:

As you can see in the picture above, Elements are split into 2 main types:

• ComponentElement

  These elements do not directly correspond to any visual rendering part.

• RenderObjectElement

  These elements correspond to a part of the rendered screen.

Great! Lots of information so far but how is everything linked together and why was it interesting to introduce all this?

How do Widgets and Elements work together?

In Flutter, the whole mechanics relies on invalidating either an element or a renderObject.

Invalidating an element can be done in different ways:

• by using setState, which invalidates the whole StatefulElement (notice that I am intentionally not saying StatefulWidget)
• via notifications, handled by other proxyElement (such as InheritedWidget, for example), which invalidates any element that depends on that proxyElement

The outcome of an invalidation is that the corresponding element(s) is/are referenced in a list of dirty elements.

Invalidating a renderObject means that no changes are applied to the structure of the elements but a modification at the level of a renderObject happens, such as

• changes to its dimensions, position, geometry...
• needs to be repainted, for example when you simply change the background color, the font style...

The outcome of such invalidation is that the corresponding renderObject is referenced in a list of renderObjects that need to be rebuilt or repainted.

Whatever the type of invalidation, when this happens, the SchedulerBinding (remember it?) is requested to ask the Flutter Engine to schedule a new frame.

It is when the Flutter Engine wakes up the SchedulerBinding that all the magics happens...

onDrawFrame()

Earlier in this article, we mentioned that the SchedulerBinding had 2 main responsibilities, one of which was to be ready to handle requests emitted by the Flutter Engine, related to frame rebuild. This is the perfect moment to focus on this now...

The partial sequence diagram below shows what happens when the SchedulerBinding receives a request onDrawFrame() from the Flutter Engine.

Step 1: the elements

The WidgetsBinding is invoked and the latter first considers the changes related to the elements.

As the BuildOwner is responsible for handling the elements tree, the WidgetsBinding invokes the buildScope method of the buildOwner.

This method iterates the list of invalidated elements (= dirty) and requests them to rebuild.

The main principles of this rebuild() method are:

1. request the element to rebuild() which leads to most of the time, invoking the build() method of the widget referenced by that element (= method Widget build(BuildContext context){...}). This build() method returns a new widget.
2. if the element has no child, the new widget is inflated (see just after), otherwise
3. the new widget is compared to the one referenced by the child of the element.
   • If they could be exchanged (=same widget type and key), the update is made, the child element is kept.
   • If they could not be exchanged, the child element is unmounted (~ discarded) and the new widget is inflated.
4. The inflating of the widget leads to creating a new element, which is mounted as new child of the element. (mounted = inserted into the elements tree)

The following animation tries to make this explanation a bit more visual.

Note on Widget inflating

When the widget is inflated, it is requested to create a new element of a certain type, defined by the widget category.

Therefore,

• an InheritedWidget will generate an InheritedElement
• a StatefulWidget will generate a StatefulElement
• a StatelessWidget will generate a StatelessElement
• an InheritedModel will generate an InheritedModelElement
• an InheritedNotifier will generate an InheritedNotifierElement
• a LeafRenderObjectWidget will generate a LeafRenderObjectElement
• a SingleChildRenderObjectWidget will generate a SingleChildRenderObjectElement
• a MultiChildRenderObjectWidget will generate a MultiChildRenderObjectElement
• a ParentDataWidget will generate a ParentDataElement

Each of these element types has a distinct behavior.

For example

• a StatefulElement will invoke the widget.createState() method at initialization, which will create the State and link it to the element
• a RenderObjectElement type will create a RenderObject when the element will be mounted, this renderObject will be added to the render tree and linked to the element.

Step 2: the renderObjects

Once all actions related to dirty elements have been completed, the elements tree is now stable and it is time to consider the rendering process.

As the RendererBinding is responsible for handling the rendering tree, the WidgetsBinding invokes the drawFrame method of the RendererBinding.

The partial diagram below shows the sequence of actions performed during a drawFrame() request.

During this step, the following activities are performed:

• each renderObject marked as dirty is requested to perform its layout (meaning calculating its dimensions and geometry)
• each renderObject marked as needs paint is repainted, using the renderObject's layer.
• the resulting scene is built and sent to the Flutter Engine so that the latter transmits it to the device screen.
• finally the Semantics is also updated and sent to the Flutter Engine

At the end of this flow of actions, the device screen is updated.

Part 3: Gesture handling

The gestures (= events related to the finger on the glass) is handled by the GestureBinding.

When the Flutter Engine sends information related to a gesture-related event, through the window.onPointerDataPacket API, the GestureBinding intercepts it, proceeds with some buffering and:

1. converts the coordinates emitted by the Flutter Engine to match the device pixel ratio, then
2. requests the renderView to provide a list of ALL RenderObjects which cover a part of screen containing the coordinates of the event
3. then iterates that list of renderObjects and dispatches the related event to each of them.
4. when a renderObject is waiting for this kind of event, it processes it.

From this explanation, we directly see how important renderObjects are...

Part 4: Animations

This last part of the article focuses on the notion of Animations and more specifically on the notion of Ticker.

When you initiate an animation, you generally use an AnimationController or any similar Widget or component.

In Flutter, everything which is related to animation refers to the notion of Ticker.

A Ticker does only one thing, when active: "it requests the SchedulerBinding to register a callback and ask the Flutter Engine to wake it up when next available".

When the Flutter Engine is ready, it then invokes the SchedulerBinding via a request: "onBeginFrame".

The SchedulerBinding intercepts this request then iterates the list of ticker callbacks and invokes each of them.

Each ticker tick is intercepted by any controller interested in this event to process it. If the animation is complete, the ticker is "disabled", otherwise, the ticker requests the SchedulerBinding to schedule another callback. And so on...

Global Picture

Now that we have seen how the Flutter internals work, here is the global picture:

BuildContext

Final word...

If you recall the diagram that shows the different element types, you most probably noticed the signature of the base Element:

abstract class Element extends DiagnosticableTree implements BuildContext {
  ...
}

Here is the famous BuildContext.

What is a BuildContext?

The BuildContext is an interface that defines a series of getters and methods that could be implemented by an element, in an harmonized manner.

In particular, the BuildContext is mainly used in the build() method of a StatelessWidget and StatefulWidget or in a StatefulWidget State object.

The BuildContext is nothing else but the Element itself which corresponds to

• the Widget being rebuilt (inside the build or builder methods)
• the StatefulWidget linked to the State where you are referencing the context variable.

This means that most developers are constantly handling elements even without knowing it.

How useful the BuildContext can be?

As the BuildContext corresponds to the element related to the widget but also to a location of the widget in the tree, this BuildContext is very useful to:

• obtain the reference of the RenderObject that corresponds to the widget (or if the widget is not a renderer, the descendant widget)
• obtain the size of the RenderObject
• visit the tree. This is actually used by all the Widgets which usually implement the of method (e.g. MediaQuery.of(context), Theme.of(context)...)

Just for the fun...

Now that we have understood that the BuildContext is the element, for the fun I wanted to show you another way of using it...

The following totally useless code makes possible for a StatelessWidget to update itself (as if it was a StatefulWidget but without using any setState()), by using the BuildContext ...

WARNING

Please do not use this code!

Its sole purpose is to demonstrate that a StatelessWidget is able to request to be rebuilt.

If you need to consider some state with a Widget, please use a StatefulWidget

void main() {
  runApp(MaterialApp(
    home: TestPage(),
  ));
}

class TestPage extends StatelessWidget {
  // final because a Widget is immutable (remember?)
  final bag = {"first": true};

  @override
  Widget build(BuildContext context) {
    return Scaffold(
      appBar: AppBar(title: const Text('Stateless ??')),
      body: Center(
        child: GestureDetector(
            child: Container(
              width: 50.0,
              height: 50.0,
              color: bag["first"]! ? Colors.red : Colors.blue,
            ),
            onTap: () {
              bag["first"] = !bag["first"]!;
              //
              // This is the trick
              //
              (context as Element).markNeedsBuild();
            }),
      ),
    );
  }
}

Between us, when you are invoking the setState() method, the latter ends up doing the very same thing: _element.markNeedsBuild().

Conclusions

Yet another long article, will you tell me.

I thought it could be interesting to know how Flutter has been architectured and to remind that everything has been designed to be efficient, scalable and open to future extensions.

Also, key concepts such as Widget, Element, BuildContext, RenderObject are not always obvious to apprehend.

I hope that this article might have been useful.

Stay tuned for new articles, soon. Meanwhile, let me wish you a happy coding.

Introduction

I recently received a couple of questions related to the notions of Future, async, await, Isolate and parallel processing.

Along with these questions, some people experienced troubles with the sequence order of the processing of their code.

I thought that it would be quite useful to take the opportunity of an article to cover these topics and remove any ambiguity, mainly around the notions of asynchronous and parallel processings.

Dart is a Single Threaded language

First things first, everyone needs to bear in mind that Dart is Single Thread and Flutter relies on Dart.

IMPORTANT

Dart executes one operation at a time, one after the other meaning that as long as one operation is executing, it cannot be interrupted by any other Dart code.

In other words, if you consider a purely synchronous method, the latter will be the only one to be executed until it is done.

void myBigLoop(){
  for (int i = 0; i < 1000000; i++){
    _doSomethingSynchronously();
  }
}

In the example above, the execution of the myBigLoop() method will never be interrupted until it completes. As a consequence, if this method takes some time, the application will be "blocked" during the whole method execution.

The Dart execution model

Behind the scene, how does Dart actually manage the sequence of operations to be executed?

In order to answer this question, we need to have a look at the Dart code sequencer, called the Event Loop.

When you start a Flutter (or any Dart) application, a new Thread process (in Dart language = "Isolate") is created and launched.This thread will be the only one that you will have to care for the entire application.

So, when this thread is created, Dart automatically

1. initializes 2 Queues, namely "MicroTask" and "Event" FIFO queues;
2. executes the main() method and, once this code execution is completed,
3. launches the Event Loop

During the whole life of the thread, a single internal and invisible process, called the "Event Loop", will drive the way your code will be executed and in which sequence order, depending on the content of both MicroTask and Event Queues.

The Event Loop corresponds to some kind of infinite loop, cadenced by an internal clock which, at each tick, if no other Dart code is being executed, does something like the following:

void eventLoop(){
  while (microTaskQueue.isNotEmpty){
    fetchFirstMicroTaskFromQueue();
    executeThisMicroTask();
    return;
  }

  if (eventQueue.isNotEmpty){
    fetchFirstEventFromQueue();
    executeThisEventRelatedCode();
  }
}

As we can see the MicroTask Queue has precedence over the Event Queue but what are those 2 queues used for?

MicroTask Queue

The MicroTask Queue is used for very short internal actions that need to be run asynchronously, right after something else completes and before giving the hand back to the Event Queue.

As an example of a MicroTask you could imagine having to dispose a resource, right after it has been closed. As the closure process could take some time to complete, you could write something like this:

MyResource myResource;

...

void closeAndRelease() {
  scheduleMicroTask(_dispose);
  _close();
}

void _close(){
  // The code to be run synchronously
  // to close the resource
  ...
}

void _dispose(){
  // The code which has to be run
  // right after the _close()
  // has completed
}

This is something that most of the time, you will not have to work with. As an example, the whole Flutter source code references the scheduleMicroTask() method only 7 times.

It is always preferable to consider using the Event Queue.

Event Queue

The Event Queue is used to reference operations that result from

• external events such as
  • I/O;
  • gesture;
  • drawing;
  • timers;
  • streams;
  • ...
• futures

In fact, each time an external event is triggered, the corresponding code to be executed is referenced into the Event Queue.

As soon as there is no longer any micro task to run, the Event Loop considers the first item in the Event Queue and will execute it.

It is very interesting to note that Futures are also handled via the Event Queue.

Futures

A Future corresponds to a task that runs asynchronously and completes (or fails) some point in time in the future.

When you instantiate a new Future:

• an instance of that Future is created and recorded in an internal array, managed by Dart;
• the code that needs to be executed by this Future is directly pushed into the Event Queue;
• the future instance is returned with a status (=incomplete);
• if any, the next synchronous code is executed (NOT the code of the Future)

The code referenced by the Future will be executed like any other Event, as soon as the Event Loop will pick it up from the Event loop.

When that code will be executed and will complete (or fail) its then() or catchError() will directly be executed.

In order to illustrate this, let's take the following example:

void main(){
  print('Before the Future');

    Future((){
      print('Running the Future');
    }).then((_){
      print('Future is complete');
    });

  print('After the Future');
}

If we run this code, the output will be the following:

Before the Future
After the Future
Running the Future
Future is complete

This is totally normal as the flow of execution is the following:

1. print('Before the Future')
2. add "(){print('Running the Future');}" to the Event Queue;
3. print('After the Future')
4. the Event Loop fetches the code (referenced in bullet 2) and runs it
5. when the code is executed, it looks for the then() statement and runs it

Something very important to keep in mind:

A Future is NOT executed in parallel but following the regular sequence of events, handled by the Event Loop

Async methods

When you are suffixing the declaration of a method with the async keyword, Dart knows that:

• the outcome of the method is a Future;
• it runs synchronously the code of that method up to the very first await keyword, then it pauses the execution of the remainder of that method;
• the next line of code will be run as soon as the Future, referenced by the await keyword, will have completed.

This is very important to understand this since many developers think that await pauses the execution if the whole flow until it completes but this is not the case. They forget how the Event Loop works...

To better illustrate this statement, let's take the following sample and let's try to figure out the outcome of its execution.

void main() async {
  methodA();

  await methodB();
  await methodC('main');

  methodD();
}

methodA(){
  print('A');
}

methodB() async {
  print('B start');

  await methodC('B');

  print('B end');
}

methodC(String from) async {

  print('C start from $from');

  Future((){ // <== This code will be executed some time in the future
    print('C running Future from $from');
  }).then((_){
    print('C end of Future from $from');
  });
  print('C end from $from');
}

methodD(){
  print('D');
}

The correct sequence is the following:

1. A
2. B start
3. C start from B
4. C end from B
5. B end
6. C start from main
7. C end from main
8. D
9. C running Future from B
10. C end of Future from B
11. C running Future from main
12. C end of Future from main

Now, let's consider that "methodC()" from the code above would correspond to a call to a server which might take uneven time to respond. I believe it is obvious to say that it might become very difficult to predict the exact flow of execution.

If your initial expectation from the sample code would have been to only execute methodD() at the end of everything, you should have written the code, as follows:

void main() async {
  methodA();
  await methodB();
  await methodC('main');
  methodD();
}

methodA(){
  print('A');
}

methodB() async {
  print('B start');
  await methodC('B');
  print('B end');
}

methodC(String from) async {
  print('C start from $from');

  await Future((){ // <== modification is here
    print('C running Future from $from');
  }).then((_){
    print('C end of Future from $from');
  });
  print('C end from $from');
}

methodD() {
  print('D');
}

This gives the following sequence:

1. A
2. B start
3. C start from B
4. C running Future from B
5. C end of Future from B
6. C end from B
7. B end
8. C start from main
9. C running Future from main
10. C end of Future from main
11. C end from main
12. D

The fact of adding a simple await at the level of the Future in methodC() changes the whole behavior.

Also very important to keep in mind:

An async method is NOT executed in parallel but following the regular sequence of events, handled by the Event Loop, too.

A last example I wanted to show you is the following.
What will be the output of running method1 and the one of method2? Will they be the same?

void method1() {
  List<String> myArray = <String>['a','b','c'];

  print('before loop');

  myArray.forEach((String value) async {
    await delayedPrint(value);
  });

  print('end of loop');
}

void method2() async {
  List<String> myArray = <String>['a','b','c'];

  print('before loop');

  for(int i=0; i<myArray.length; i++) {
    await delayedPrint(myArray[i]);
  }

  print('end of loop');
}

Future<void> delayedPrint(String value) async {
  await Future.delayed(Duration(seconds: 1));
  print('delayedPrint: $value');
}

Answer:

Did you see the difference and the reason why their behavior is not the same?

The solution resides in the fact that method1 uses a function forEach() to iterate the array. Each time it iterates, it invokes a new callback which is flagged as an async (thus a Future). It executes it until it gets to the await then it pushes the remainder of the code into the Event queue. As soon as the iteration is complete, it executes the next statement "print('end of loop')". Once done, the Event Loop will process the 3 callbacks.

As regard method2, everything runs inside the same code "block" and therefore runs (in this example), line after line.

As you can see, even in a code that looks like very simple, we still need to keep in mind how the Event Loop works...

Multi-Threading

Therefore, how could we run parallel codes in Flutter? Is this possible?

Yes, thanks to the notion of Isolates.

What is an Isolate?

An Isolate corresponds to the Dart version of the notion of Thread, as already explained earlier.

However, there is a major difference with the usual implementation of "Threads" and this is why they are named "Isolates".

"Isolates" in Flutter do not share memory. Interaction between different "Isolates" is made via "messages" in terms of communication.

Each Isolate has its own "Event Loop"

Each "Isolate" has its own "Event Loop" and Queues (MicroTask and Event). This means that the code runs inside in an Isolate, independently of another Isolate.

Thanks to this, we can obtain parallel processing.

How to launch an Isolate?

Depending on the needs you have to run an Isolate, you might need to consider different approaches.

1. Low-Level solution

This first solution does not use any package and fully relies on the low-level API, offered by Dart.

1.1. Step 1: creation and hand-shaking

As I said earlier, Isolates do not share any memory and communicate via messages, therefore, we need to find a way to establish this communication between the "caller" and the new isolate.

Each Isolate exposes a port which is used to convey a message to that Isolate. This port is called "SendPort" (I personally find the name is bit misleading since it is a port aimed at receiving/listening, but this is the official name).

This means that both "caller" and "new isolate" need to know the port of each other to be able to communicate. This hand-shaking process is shown here below:

//
// The port of the new isolate
// this port will be used to further
// send messages to that isolate
//
SendPort newIsolateSendPort;

//
// Instance of the new Isolate
//
Isolate newIsolate;

//
// Method that launches a new isolate
// and proceeds with the initial
// hand-shaking
//
void callerCreateIsolate() async {
  //
  // Local and temporary ReceivePort to retrieve
  // the new isolate's SendPort
  //
  ReceivePort receivePort = ReceivePort();

  //
  // Instantiate the new isolate
  //
  newIsolate = await Isolate.spawn(
    callbackFunction,
    receivePort.sendPort,
  );

  //
  // Retrieve the port to be used for further
  // communication
  //
  newIsolateSendPort = await receivePort.first;
}

//
// The entry point of the new isolate
//
static void callbackFunction(SendPort callerSendPort){
  //
  // Instantiate a SendPort to receive message
  // from the caller
  //
  ReceivePort newIsolateReceivePort = ReceivePort();

  //
  // Provide the caller with the reference of THIS isolate's SendPort
  //
  callerSendPort.send(newIsolateReceivePort.sendPort);

  //
  // Further processing
  //
}

CONSTRAINTS

The "entry point" of an isolate MUST be a top-level function or a STATIC method.

1.2. Step 2: submission of a Message to the Isolate

Now that we have the port to be used to send a message to the Isolate, let's see how to do it:

//
// Method that sends a message to the new isolate
// and receives an answer
//
// In this example, I consider that the communication
// operates with Strings (sent and received data)
//
Future<String> sendReceive(String messageToBeSent) async {
  //
  // We create a temporary port to receive the answer
  //
  ReceivePort port = ReceivePort();

  //
  // We send the message to the Isolate, and also
  // tell the isolate which port to use to provide
  // any answer
  //
  newIsolateSendPort.send(
    CrossIsolatesMessage<String>(
      sender: port.sendPort,
      message: messageToBeSent,
    )
  );

  //
  // Wait for the answer and return it
  //
  return port.first;
}

//
// Extension of the callback function to process incoming messages
//
static void callbackFunction(SendPort callerSendPort) {
  //
  // Instantiate a SendPort to receive message
  // from the caller
  //
  ReceivePort newIsolateReceivePort = ReceivePort();

  //
  // Provide the caller with the reference of THIS isolate's SendPort
  //
  callerSendPort.send(newIsolateReceivePort.sendPort);

  //
  // Isolate main routine that listens to incoming messages,
  // processes it and provides an answer
  //
  newIsolateReceivePort.listen((dynamic message){
    CrossIsolatesMessage incomingMessage = message as CrossIsolatesMessage;

    //
    // Process the message
    //
    String newMessage = "complemented string " + incomingMessage.message;

    //
    // Sends the outcome of the processing
    //
    incomingMessage.sender.send(newMessage);
  });
}

//
// Helper class
//
class CrossIsolatesMessage<T> {
  final SendPort sender;
  final T message;

  CrossIsolatesMessage({
    required this.sender,
    this.message,
  });
}

1.3. Step 3: destruction of the new Isolate

When you do no longer need the new Isolate instance, it is a good practice to release it, the following way:

//
// Routine to dispose an isolate
//
void dispose() {
    newIsolate?.kill(priority: Isolate.immediate);
    newIsolate = null;
}

1.4. Special note - Single-Listener Streams

You might have certainly noticed that we are using Streams to communicate between the "caller" and the new isolate. These Streams are of type: "Single-Listener" Streams.

2. One-shot computation

If you only need to run some piece of code to do some specific job and do not need to interact with that Isolate once the job is done, there exists a very convenient Helper, called compute.

This function:

• spawns an Isolate,
• runs a callback function on that isolate, passing it some data,
• returns the value, outcome the callback,
• and kills the Isolate at the end of the execution of the callback.

CONSTRAINTS

The "callback" function MUST be a top-level function and CANNOT be a closure or a method of a class (static or not).

3. IMPORTANT LIMITATION

At time of writing this article, it is important to note that

Platform-Channel communication ARE ONLY SUPPORTED by the main isolate. This main isolate corresponds to the one which is created when your application is launched.

In other words, Platform-Channel communication is not possible via instances of isolates you programmatically create...

There is however a work-around... Please refer to this link for a discussion on this topic.

When should I use Futures and Isolates?

Users will evaluate the quality of an application based on different factors, such as:

• features
• look
• user friendliness
• ...

Your application could meet all of these factors but if the user experiences lags in the course of some processing, it is most likely that this will go against you.

Therefore, here are some hints you should systematically take into consideration in your developments:

1. If pieces of codes MAY NOT be interrupted, use a normal synchronous process (one method or multiple methods that call each other);
2. If pieces of codes could run independently WITHOUT impacting the fluidity of the application, consider using the Event Loop via the use of Futures;
3. If heavy processing might take some time to complete and could potentially impact the fluidity of the application, consider using Isolates.

In other words, it is advisable to try to use as much as possible the notion of Futures (directly or indirectly via async methods) as the code of these Futures will be run as soon as the Event Loop has some time. This will give the user the feeling that things are being processed in parallel (while we now know it is not the case).

Another factor that could help you decide whether to use a Future or an Isolate is the average time it takes to run some code.

• If a method takes a couple of milliseconds => Future
• If a processing might take several hundreds of milliseconds => Isolate

Here are some good candidates for Isolates:

• JSON decoding

  decoding a JSON, result of an HttpRequest, might take some time => use compute

• encryption

  encryption might be very consuming => Isolate

• image processing

  processing an image (cropping, e.g.) does take some time to complete => Isolate

• load an image from the Web

  in this case, why not delegating this to an Isolate which will return the complete image, once fully loaded?

Conclusions

I think that understanding how the Event Loop works is essential.

It is also important to keep in mind that Flutter (Dart) is Single-Thread therefore, in order to please the users, developers must make sure that the application will run as smoothly as possible. Futures and Isolates are very powerful tools that can help you achieve this goal.

Stay tuned for new articles and meanwhile... I wish you a happy coding !

Introduction

Following the introduction to the notions of BLoC, Reactive Programming and Streams, I made some time ago, I though it might be interesting to share with you some patterns I regularly use and personally find very useful (at least to me). These patterns make me save a tremendous amount of time in my developments and also make my code much easier to read and debug.

The topics I am going to talk are:

• BLoC Provider and InheritedWidget

• Where to initialize a BLoC ?

• Event-State

  Allows to respond to State transition, based on Event.

• Form Validation

  Allows to control the behavior of a Form based on entries and validation(s).
  (The solution I explain also covers the comparison of the password and retyped password).

• Part Of

  Allows a Widget to adapt its behavior based on its presence in a list.

The complete source code is available on GitHub.

1. BLoC Provider and InheritedWidget

I take the opportunity of this article to introduce another version of my BlocProvider, which now relies on an InheritedWidget.

The advantage of using an InheritedWidget is that we gain in performance.

Let me explain...

1.1. Previous Implementation

My previous version of the BlocProvider was implemented as a regular StatefulWidget, as follows:

1.2. New Implementation

The new implementation relies on a StatefulWidget, combined with an InheritedWidget:

The advantage is this solution is performance.

Thanks to the use of an InheritedWidget, it may now call the context.getElementForInheritedWidgetOfExactType() function, which is a O(1), meaning that the retrieval of the ancestor is immediate.

This comes from the fact that all InheritedWidgets are memorized by the Framework.

1.3. How to use the new BlocProvider ?

Widget build(BuildContext context){
  return BlocProvider<MyBloc>{
      blocBuilder: () => myBloc,
      child: ...
  };
}

1.3.2. Retrieval of the BLoC

Widget build(BuildContext context){
  MyBloc? myBloc = BlocProvider.of<MyBloc>(context);
  ...
}

--

2. Where to initialize a BLoC

To answer this question, you need to figure out the scope of its use.

2.1. Available everywhere in the Application

Suppose that you have to deal with some mechanisms related to User Authentication/Profile, User Preferences, Shopping Basket... anything that would require a BLoC to be available from potentially any possible parts of an application (eg from different pages), there exists 2 ways of making this BLoC accessible.

2.1.1. Use of a Global Singleton

This solution relies on the use of a Global object, instantiated once for all, not part of any Widget tree.

To use this BLoC, you simply need to import the class and directly invoke its methods as follows:

import 'global_bloc.dart';

class MyWidget extends StatelessWidget {
    @override
    Widget build(BuildContext context){
        globalBloc.push('building MyWidget');
        return Container();
    }
}

This is an acceptable solution if you need to have a BLoC which is unique and needs to be accessible from anywhere inside the application.

• it is very easy to use;
• it does not depend on any BuildContext;
• no need to look for the BLoC via any BlocProvider and,
• in order to release its resources, simply make sure to implement the application as a StatefulWidget and invoke the globalBloc.dispose() inside the overridden dispose() method of the application Widget.

Many purists are against this solution. I don't know really why but... so let's look at another one...

2.1.2. Position it on top of everything

In Flutter, the ancestor of all pages must itself be the parent of the MaterialApp. This is due to the fact that a page (or Route) is wrapped in an OverlayEntry, child of a common Stack for all pages.

In other words, each page has a Buildcontext which is independent of any other page. This explains why, without using any tricks, it is impossible for 2 pages (Routes) to have anything in common.

Therefore, if you need a BLoC to be available anywhere in the application, you have to put it as the parent of the MaterialApp, as follows:

2.2. Available to a sub-tree

Most of the time, you might need to use a BLoC in some specific parts of the application.

As an example, we could think of a discussion thread where the BLoC will be used to

• interact with the Server to retrieve, add, update posts
• list the threads to be displayed in a certain page
• ...

For this example, you do not need this BLoC to be available to the whole application but to some Widgets, part of a tree.

A first solution could be to inject the BLoC as the root of the Widgets tree, as follows:

This way, all widgets will access the BLoC, via a call to the BlocProvider.of method.

2.3. Available to only one Widget

This relates to cases where a BLoC would only be used by only one Widget.

In this case, it is acceptable to instantiate the BLoC inside the Widget.

3. Event State

Sometimes, handling a series of activities which might be sequential or parallel, long or short, synchronous or asynchronous and which could also lead to various results, can become extremely hard to program. You might also require to update the display along with the progress or depending on the states.

This first use case is aimed at making it easier to handle such situation.

This solution is based on the following principle:

• an event is emitted;
• this event triggers some action which leads to one or several states;
• each of these states could in turn emit other events or lead to another state;
• these events would then trigger other action(s), based on the active state;
• and so on...

In order to illustrate this concept, let's take 2 common examples:

• Application initialization

  Suppose that you need to run a series of actions to initialize an application. Actions might be linked to interactions with a server (eg to load some data).
  During this initialization process, you might need to display a progress bar together with a series of images to make the user wait.

• Authentication

  At start up, an application might require a user to authenticate or to register.
  Once the user is authenticated, the user is redirected to the main page of the application. Then, if the user signs out, he is redirected to the authentication page.

In order to be able to handle all possible cases, sequence of events but also if we consider that events could be triggered anywhere in the application, this might become quite hard to manage.

This is where the BlocEventState, combined with a BlocEventStateBuilder, can help a lot...

3.1. BlocEventState

The idea behind the BlocEventState is to define a BLoC that:

• accepts Events as input;
• invokes an eventHandler when a new event is emitted;
• the eventHandler is reponsible for taking appropriate actions based on the event and emitting State(s) in response.

The following picture shows the idea:

Here is the source code of such class. Explanation will follow:

As you can see, this is an abstract class that needs to be extended, to define the behavior of the eventHandler method.

It exposes:

• a Sink (emitEvent) to push an Event;
• a Stream (state) to listen to emitted State(s).

At initialization time (see Constructor):

• an initialState needs to be provided;
• it creates a StreamSubscription to listen to incoming Events to
  • dispatch them to the eventHandler
  • to emit resulting state(s).

3.2. Specialized BlocEventState

The template to use to implement such BlocEventState is given here below. Right after, we will implement real ones.

Do not worry if this template does not compile... This is normal as we haven't defined the BlocState.notInitialized() yet... This will come in a few moment.

This template simply provides an initialState at initialization and overrides the eventHandler.

There is something very interesting to note, here. We use the asynchronous generator: async* and the yield statement.

Marking a function with the async* modifier, identifies the function as an asynchronous generator:

Each time the yield statement is called, it adds the result of the expression that follows the yield to the output Stream.

This is particularly useful if we need to emit a sequence of States, resulting from a series of actions (we will see later, in practice)

For additional details on asynchronous generators, please follow this link.

3.3. BlocEvent and BlocState

As you have noticed, we have defined a BlocEvent and BlocState abstract classes.

These classes need to be extended with the specialized events and states you want to emit.

3.4. BlocEventStateBuilder Widget

Last piece of this pattern is the BlocEventStateBuilder Widget which allows you to respond to the State(s), emitted by the BlocEventState.

Here is its source code:

This Widget is nothing else but a specialized StreamBuilder, which will invoke the builder input argument each time a new BlocState will be emitted.

Okay. Now that we have all the pieces, it is time to show what we can do with them...

3.5. Case 1: Application Initialization

This first example illustrates the case where you need your application to perform some tasks at start time.

A common use is a game which initially displays a splash screen (animated or not) while it gets some files from the server, checks if new updates are available, tries to connect to any game center... before displaying the actual main screen. In order not to give the feeling that the application does nothing, it might display a progress bar and show some pictures at regular interval, while it does all its initialization process.

The implementation I am going to show you is very simple. It will only display some competion percentages on the screen, but this can be very easily extended to your needs.

The first thing to do is to define the events and states...

3.5.1. ApplicationInitializationEvent

For this example, I will only consider 2 events:

• start: this event will trigger the initialization process;
• stop: the event could be used to force the initialization process to stop.

Here is the definition:

3.5.2. ApplicationInitializationState

This class will provide the information related to the initialization process.

For this example, I will consider:

• 2 flags:
  • isInitialized to indicate whether the initialization is complete
  • isInitializing to know whether we are in the middle of the initialization process
• the progress completion ratio

Here is its source code:

3.5.3. ApplicationInitializationBloc

This BLoC is responsible for the handling the initialization process based on events.

Here is the code:

Some explanation:

• when the event "ApplicationInitializationEventType.start" is received, it starts counting from 0 to 100 (step 10) and, for each of the values (0, 10, 20, ...) it emits (via the yield) a new state that tells that the initialization is running (isInitializing = true) and its progress value.
• when the event "ApplicationInitializationEventType.stop" is received, it considers that the initialization is complete.
• as you can see, I put some delay in the counter loop. This shows you how you could use any Future (e.g. case where you would need to contact the server)

3.5.4. Wrapping it all together

Now, the remaining part is to display the pseudo Splash screen that shows the counter...

Explanation:

• As the ApplicationInitializationBloc does not need to be used anywhere in the application, we can initialize it in a StatefulWidget;
• We directly emit the ApplicationInitializationEventType.start event to trigger the eventHandler
• Each time an ApplicationInitializationState is emitted, we update the text
• When the initialization is complete, we redirect the user to the Home page.

Trick

As we cannot directly redirect to the Home page, inside the builder, we use the WidgetsBinding.instance.addPostFrameCallback() method to request Flutter to execute a method as soon as the rendering is complete

3.6. Case 2: Application Authentication and Sign out

For this example, I will consider the following use-case:

• at start up, if the user is not authenticated, the Authentication/Registration page is automatically displayed;
• during the user authentication, a CircularProgressIndicator is displayed;
• once authenticated, the user is redirected to the Home page;
• anywhere in the application, the user has the possibility to log out;
• when the user logs out, the user is automatically redirected to the Authentication page.

Of course, it is very possible to handle all this programmatically but it is much easier to delegate all this to a BLoC.

The following diagram explains the solution I am going to explain:

An intermediate page, called "DecisionPage" will be responsible for the automatic redirection of the user to either the Authentication page or to the Home page, depending on the status of the user authentication. This DecisionPage is of course, never displayed and should not be considered as a page, as such.

The first thing to do is to define the events and states...

3.6.1. AuthenticationEvent

For this example, I will only consider 2 events:

• login: this event is emitted when the user correctly authenticates;
• logout: the event is emitted when the user logs out.

Here is the definition:

3.6.2. AuthenticationState

This class will provide the information related to the authentication process.

For this example, I will consider:

• 3 flags:
  • isAuthenticated to indicate whether the authentication is complete
  • isAuthenticating to know whether we are in the middle of the authentication process
  • hasFailed to indicate that the authentication failed
• the name of the user once authenticated

Here is its source code:

3.5.3. AuthenticationBloc

This BLoC is responsible for the handling the authentication process based on events.

Here is the code:

Some explanation:

• when the event "AuthenticationEventLogin" is received, it emits (via the yield) a new state that tells that the authentication is running (isAuthenticating = true).
• it then runs the authentication and, once done, emits another state that tells that the authentication is complete.
• when the event "AuthenticationEventLogout" is received, it emis a new state that tells that the user is no longer authenticated.

3.5.4. AuthenticationPage

As you are going to see, this page is very basic and does not do very much, for sake of explanation.

Here is the code. Explanation will follow:

Explanation:

• line #11: the page retrieves the reference to the AuthenticationBloc
• lines #24-70: it listens to emitted AuthenticationState:
  • if the authentication is in progress, it displays a CircularProgressIndicator that tells the user that something is going on and prevents the user from accessing to the page (lines #25-27)
  • if the authentication is successful, we do not need to display anything (lines #29-31).
  • if the user is not authenticated, it displays 2 buttons to simulate a successful authentication and a failure.
  • when we click on one of these buttons, we emit an AuthenticationEventLogin event, together with some parameters (which normally will be used by the authentication process)
  • if the authentication failed, we display an error message (lines #60-64)

That's it! Nothing else needs to be done... Easy isn't it?

Tip

As you may have noticed, I wrapped the page inside a WillPopScope.

The rationale is that I do not want the user to be able to use the Android 'Back' button as in this sample, the Authentication is a compulsory step which prevents the user from accessing any other part unless correctly authenticated.

3.5.5. DecisionPage

As said previously, I want the application to automate the redirection to the AuthenticationPage or to the HomePage, based on the authentication status.

Here is the code of this DecisionPage, explanation will follow:

Reminder

To explain this in details, we need to come back to the way Pages (=Route) are handled by Flutter. To handle Routes, we use a Navigator, which creates an Overlay.

This Overlay is a Stack of OverlayEntry, each of them containing a Page.

When we are pushing, popping, replacing a page, via the Navigator.of(context), the latter updates its Overlay (so the Stack), which is rebuilt.

When the Stack is rebuilt, each OverlayEntry (thus its content) is also rebuilt.

As a consequence, all pages that remain are rebuilt when we are doing an operation via the Navigator.of(context) !

• So, why did I implement this as a StatefulWidget?

  In order to be able to respond to any change of AuthenticationState, this "page" needs to remain present during the whole lifecycle of the application.

  This means that, based on the reminder here above, this page will be rebuilt each time an action is done by the Navigator.of(context).

  As a consequence, its BlocEventStateBuilder will also rebuild, invoking its own builder method.

  Because this builder is reponsible for redirecting the user to the page that corresponds to the AuthenticationState, if we redirect the user each time the page is rebuilt, it will continue redirecting forever since continously rebuilt.

  To prevent this from happening, we simply need to memorize the last AuthenticationState for which we took an action and only take another action when a different AuthenticationState is received.

• How does this work?

  As said, the BlocEventStateBuilder invokes its builder each time an AuthenticationState is emitted.

  Based on the state flags (isAuthenticated), we know to which page we need to redirect the user.

Trick

As we cannot directly redirect to another page from the builder, we use the WidgetsBinding.instance.addPostFrameCallback() method to request Flutter to execute a method as soon as the rendering is complete

Also, as we need to remove any existing page before redirecting the user, except this DecisionPage, which needs to remain in all circumstances, we use the Navigator.of(context).pushAndRemoveUntil(...) to achieve this.

3.5.8. Log out

To let the user logging out, you may now create a "LogOutButton" and put it anywhere in the application.

This button simply needs to emit a AuthenticationEventLogout() event, which will lead to the following automatic chain of actions:

1. it will be handled by the AuthenticationBloc
2. which in turn will emit an AuthentiationState (isAuthenticated = false)
3. which will be handled by the DecisionPage via the BlocEventStateBuilder
4. which will redirect the user to the AuthenticationPage

Here is the code of such button:

3.5.7. AuthenticationBloc

As the AuthenticationBloc needs to be available to any page of this application, we will also inject it as a parent of the MaterialApp, as follows:

4. Form Validation

Another interesting use of a BLoC is when you need to validate a Form and:

• validate the entry related to a TextField against some business rules;
• display validation error messages depending on rules;
• automate the accessibility of Widgets, based on business rules.

The example I am now going to take is a RegistrationForm which is made up of 3 TextFields (email, password, confirm password) and 1 ElevatedButton to launch the registration process.

The business rules I want to implement are:

• the email needs to be a valid email address. If not a message needs to be displayed.
• the password needs to be valid (must contain at least 8 characters, with 1 uppercase, 1 lowercase, 1 figure and 1 special character). If invalid a message needs to be displayed.
• the retype password needs to meet the same validation rule AND be the same as the password. If not the same, a message needs to be displayed.
• the register button may only be active when ALL rules are valid.

4.1. The RegistrationFormBloc

This BLoC is responsible for handling the validation business rules, as expressed here before.

Here is its source code:

Let me explain this in details...

• We first initialize 3 BehaviorSubject to handle the Streams of each TextField of the form.
• We expose 3 Function(String) which will be used to accept inputs from the TextFields.
• We expose 3 Stream<String> which will be used by the TextField to display an potential error message, resulting from their respective validation
• We expose 1 Stream<bool> which will be used by the ElevatedButton to enable/disable it based on the whole validation result.

Okay, it is now time to dive into deeper details...

As you may have noticed, the signature of this class is a bit special. Let's review it.

class RegistrationFormBloc extends Object
                           with EmailValidator, PasswordValidator
                           implements BlocBase {
  ...
}

The with keyword means that this class is using MIXINS ( = "a way of reusing some class code inside another class") and, to be able to use the with keyword, the class needs to extends the Object class. These mixins contain the code which validates the email and password, respectively.

For more details on Mixins I recommend you to read this great article from Romain Rastel.

4.1.1. Validator Mixins

I will only explain the EmailValidator since the PasswordValidator is very similar.

First, the code:

This class exposes a final function ("validateEmail") which is a StreamTransformer.

Reminder

A StreamTransformer is invoked as follows: stream.transform(StreamTransformer).

The StreamTransformer takes its input from the Stream that refers to it via the transform method. It then processes this input, and reinjects the transformed input into initial Stream.

In this code, the processing of the input consists in checking it against a regular expression. If the input matches the regular expression, we simply reinject the input into the stream, otherwise, we inject an error message into the stream.

4.1.2. Why using a stream.transform()?

As said here before, if the validation is successful, the StreamTransformer reinjects the input into the Stream. Why is it useful?

Here comes the explanation related to the Rx.combineLatest3()... This method will NOT emit any value until all Streams it refers to, have emitted at least one value.

Let's have a look at the following picture to illustrate what we want to achieve.

• if the user enters an email and the latter is validated, it will be emitted by the email stream which will be one input of the Rx.combineLatest3();
• if the email is not valid, an error will be added to the stream (and no value will go out the stream);
• the same applies to both password and retype password;
• when all these 3 validations will be successful (meaning that all these 3 streams will emit a value), the Rx.combineLatest3() will emit in turn a true thanks to the "(e, p, c) => true" (see line #35).

4.1.2. Validation of the 2 passwords

I saw many questions related to this comparison on Internet. Several solutions exist, let me explain 2 of them.

4.1.2.1. Basic solution - no error message

A first solution could be the following one:

This solution simply compares the 2 passwords as soon as they both have been validated and if they match, emits a value (= true).

As we will soon see, the Register button accessibility will depend on this registerValid stream.

If both passwords do not match, no value is emitted by that stream and the Register button remains inactive but the user will not receive any error message to help him understand why.

4.1.2.2. Solution with error message

Another solution consists in extending the processing of the confirmPassword stream as follows:

Once the retype password has been validated, it is emitted by the Stream and, using the doOnData, we can directly get this emitted value and compare it with the value of the password stream. If both do not match, we have now the possibility to send an error message.

4.2. The RegistrationForm

Let's now have a look at the RegistrationForm before explaining it:

Explanation:

• As the RegisterFormBloc is only meant to be used by this form, it is suitable to initialize it here.
• Each TextField are wrapped into a StreamBuilder<String> to be able to respond to any outcome of the validation process (see errorText: snapshot.error)
• Each time a modification is applied to the content of a TextField, we send the input to the BLoC for validation via the onChanged: _registrationFormBloc.onEmailChanged (case of email input)
• For the RegisterButton, the latter is also wrapped in a StreamBuilder<bool>.
  • If a value is emitted by the _registrationFormBloc.registerValid, the onPressed method will do something
  • If no value is emitted, the onPressed method will be assigned to null, which will deactivate the button.

That's it! No business rule is visible to the Form, which means that the rules could be changed without having to apply any modification to the form, which is excellent !

5. Part Of

Sometimes, it is interesting for a Widget to know whether it is part of a set to drive its behavior.

For this last use-case of this article, I will consider the following scenario:

• an application deals with items;
• a user could select items to put in his shopping basket;
• an item can be put in the shopping basket, only once;
• an item, present in the shopping basket, could be removed from the shopping basket;
• once removed, it is possible to put it back.

For this example, each item will display one button which will depend on the presence of the item in the shopping basket. If not part of the shopping basket, the button will allow the user to add it to the basket. If part of the shopping basket, the button will allow the user to remove it from the basket.

To better illustrate the "Part of" pattern, I will consider the following architecture:

• a Shopping Page will display the list of all possible items;
• each Item in the Shopping Page will display one button to add the item to the shopping basket or to remove it, depending on its presence in the basket;
• if an item in the Shopping Page is added to the basket, its button will automatically update to allow the user to remove it from the basket (and vice versa) without having to rebuild the Shopping Page
• another page, Shopping Basket, will list all items present in the basket;
• it will be possible to remove any item from the basket, from this page.

Side note

The name Part Of is a personal name I give. It is not an official name.

5.1. ShoppingBloc

As you can now imagine, we need to consider a BLoC dedicated to the handling of the list of all possible items, and the ones part of the Shopping Basket.

This BLoC could look like the following:

The only method which might require an explication is the _postActionOnBasket() method. Each time an item is added to or removed from the basket, we need to "refresh" the content of the _shoppingBasketController Stream so that all Widgets which are listening to changes to this Stream will be notified and be able to refresh/rebuild.

5.2. ShoppingPage

This page is very simple and only displays all the items.

Explanation:

• the AppBar displays a button that:
  • displays the number of items, present in the basket
  • redirects the user to the ShoppingBasket page when clicked
• the list of items is built using a GridView, wrapped in a StreamBuilder<List<ShoppingItem>>
• each item corresponds to a ShoppingItemWidget

5.3. ShoppingBasketPage

This page is very similar to the ShoppingPage except that the StreamBuilder is now listening to variations of the _shoppingBasket stream, exposed by the ShoppingBloc.

5.4. ShoppingItemWidget and ShoppingItemBloc

The Part Of pattern relies on the combination of these 2 elements:

• the ShoppingItemWidget is responsible for:
  • displaying the item and
  • the button to add or remove the item to/from the shopping basket
• the ShoppingItemBloc is responsible for telling the ShoppingItemWidget whether the latter is part or not of the shopping basket.

Let's see how they work together...

5.4.1. ShoppingItemBloc

The ShoppingItemBloc is instantiated by each ShoppingItemWidget, which gives it its "identity".

This BLoC listens to all variations of the ShoppingBasket stream and checks if the specific item identity is part of the basket.

If yes, it emits a boolean value (= true), which will be caught by the ShoppingItemWidget to know whether it is part of the basket or not.

Here is the code of the BLoC:

5.4.2. ShoppingItemWidget

This Widget is responsible for:

• creating an instance of the ShoppingItemBloc and passing its own identity to the BLoC
• listening to any variation of the ShoppingBasket content and transferring it to the BLoC
• listening to the ShoppingItemBloc to know whether it is part of the basket
• displaying the corresponding button (add/remove) depending on its presence in the basket
• responding to user action of the button
  • when the user clicks the add button, to add itself to the basket
  • when the user clicks the remove button, to remove itself from the basket.

Let's see how this works (explanation is given in the code).

5.5. How does all this work?

The following diagram shows how all pieces work together.

Conclusions

Another long article I wish I could make a bit shorter but I think it deserved some explanations.

As I said in the introduction, I personally use these "patterns" very frequently in my developments. This makes me save a tremendous amount of time and effort; my code is more readable and easier to debug.

In addition, it helps separating the business from the view.

There are most certainly other ways of doing this and even better ways but it simply works for me and that's all I wanted to share with you.

Stay tuned for new articles and, meanwhile, I wish you a happy coding.

Introduction

It took me quite a while to find a way to introduce the notions of Reactive Programming, BLoC and Streams.

As this is something that can make a drastic change to the way to architecture an application, I wanted a practical example that shows that:

• it is very possible not to use them but could sometime be much harder to code and less performant,
• the benefits of using them, but also
• the impacts of using them (positive and/or negative).

The practical example I made is a pseudo application which, in short, allows a user to view a list of movies from an online catalog, filter them by genre and release dates, mark/unmark them as favourites. Of course, everything is interactive, user actions can happen in different pages or inside a same one and have impacts on the visual aspects, real time.

This is an animation that shows this application.

As you landed into this page to get information about Reactive Programming, BLoC and Streams, I will first start with an introduction to them. Thereafter, I will show you how to implement and use them, in practice.

A complement of this article which gives some pratical use cases can be found following this link.

What is a Stream?

Introduction

In order to easily visualize the notion of Stream, simply consider a pipe with 2 ends, only one allowing to insert something into it. When you insert something into the pipe, it flows inside the pipe and goes out by the other end.

In Flutter,

• the pipe is called a Stream
• to control the Stream, we usually^(*) use a StreamController
• to insert something into the Stream, the StreamController exposes the "entrance", called a StreamSink, accessible via the sink property
• the way out of the Stream, is exposed by the StreamController via the stream property

^(*): I intentionally used the term "usually", since it is very possible not to use any StreamController. However, as you will read in this article, I will only make use of StreamControllers.

What can be conveyed by a Stream?

Everything and anything. From a value, an event, an object, a collection, a map, an error or even another Stream, any type of data may be conveyed by a Stream.

How do I know that something is conveyed by a Stream?

When you need to be notified that something is conveyed by a Stream, you simply need to listen to the stream property of the StreamController.

When you define a listener, you receive a StreamSubscription object. This is via that StreamSubscription object that you will be notified that something happens at the level of the Stream.

As soon as there is at least one active listener, the Stream starts generating events to notify the active StreamSubscription object(s) each time:

• some data goes out from the stream,
• when some error has been sent to the stream,
• when the stream is closed.

The StreamSubscription object also allows you to:

• stop listening,
• pause,
• resume.

Is a Stream only a simple pipe?

No, a Stream also allows to process the data that flows inside it before it goes out.

To control the processing of the data inside a Stream, we use a StreamTransformer, which is nothing but

• a function that "captures" the data that flows inside the Stream
• does something with the data
• the outcome of this transformation is also a Stream

You will directly understand from this statement that it is very possible to use several StreamTransformers in sequence.

A StreamTransformer may be used to do any type of processing, such as, e.g.:

• filtering: to filter the data based on any type of condition,
• regrouping: to regroup data,
• modification: to apply any type of modification to the data,
• inject data to other streams,
• buffering,
• processing: do any kind of action/operation based on the data,
• ...

Types of Streams

There are 2 types of Streams.

Single-subscription Streams

This type of Stream only allows a single listener during the whole lifetime of that Stream.

It is not possible to listen twice on such Stream, even after the first subscription has been canceled.

Broadcast Streams

This second type of Stream allows any number of listeners.

It is possible to add a listener to a Broadcast Stream at any moment. The new listener will receive the events, as of the moment it starts listening to the Stream.

Basic Examples

Any type of data

This very first example shows a "Single-subscription" Stream, which simply prints the data which is input. As you may see the type of data does not matter.

StreamTransformer

This second example shows a "Broadcast" Stream, which conveys integer values and only prints the even numbers. To do so, we apply a StreamTransformer that filters (line #14) the values and only let the even numbers go through.

RxDart

Nowadays, the introduction to the Streams would no longer be complete if I would not mention the RxDart Package.

The RxDart package is an implementation for Dart of the ReactiveX API, which extends the original Dart Streams API to comply with the ReactiveX standards.

As it was not originally defined by Google, it uses a different vocabulary. The following table gives you the correlation between Dart and RxDart.

RxDart as I just said, extends the original Dart Streams API and offers 3 main variations of the StreamController:

PublishSubject

The PublishSubject is a normal broadcast StreamController with one exception: stream returns an Subject rather than a Stream.

As you can see, PublishSubject sends to a listener only the events that are added to the Stream after the time of the subscription.

BehaviorSubject

The BehaviorSubject is also a broadcast StreamController which returns an Subject rather than a Stream.

The main difference with a PublishSubject is that the BehaviorSubject also sends the very last event that was emitted to the listener that just subscribed.

ReplaySubject

The ReplaySubject is also a broadcast StreamController which returns an Subject rather than a Stream.

A ReplaySubject, by default, sends all the events that were already emitted by the Stream to any new listener as the very first events.

Important note about the Resources

It is a very good practice to always release the resources which are no longer necessary.

This statement applies to:

• StreamSubscription - when you no longer need to listen to a stream, cancel the subscription;
• StreamController - when you no longer need a StreamController, close it;
• the same applies to RxDart Subjects, when you no longer need a BehaviourSubject, a PublishSubject..., close it.

How to build a Widget based on the data that goes out a Stream?

Flutter offers a very convenient StatefulWidget, called StreamBuilder.

A StreamBuilder listens to a Stream and, each time some data goes out that Stream, it automatically rebuilds, invoking its builder callback.

This is how to use the StreamBuilder:

StreamBuilder<T>(
  key: ...optional, the unique ID of this Widget...
  stream: ...the stream to listen to...
  initialData: ...any initial data, in case the stream would initially be empty...
  builder: (BuildContext context, AsyncSnapshot<T> snapshot){
      if (snapshot.hasData){
          return ...the Widget to be built based on snapshot.data
      }
      return ...the Widget to be built if no data is available
  },
)

The following example mimics the default "counter" application, but uses a Stream and no longer any setState.

Explanation and comments:

• Lines #24-30: we are listening to a the stream, and each time a new value goes out this stream, we update the Text with that value;
• Line #35: when we hit the FloatingActionButton, we increment the counter and send it to the Stream, via the sink; the fact of injecting a value in the stream causes the StreamBuilder that listens to it to rebuild and "refresh" the counter;
• We no longer need the notion of State, everything is taken on board via the Stream;
• This is a big improvement since the fact of calling the setState() method, forces the whole Widget (and any sub widgets) to rebuild. Here, ONLY the StreamBuilder is rebuilt (and of course its children widgets);
• The only reason why we are still using a StatefulWidget for the page, is simply because we need to release the StreamController, via the dispose method, line #15;

What is Reactive Programming?

Reactive programming is programming with asynchronous data streams.

In other words, everything from an event (e.g. tap), changes on a variable, messages, ... to build requests, everything that may change or happen will be conveyed, triggered by a data stream.

In clear, all this means that, with reactive programming, the application:

• becomes asynchronous,
• is architectured around the notion of Streams and listeners,
• when something happens somewhere (an event, a change of a variable ...) a notification is sent to a Stream,
• if "somebody" listens to that Stream, it will be notified and will take appropriate action(s), whatever its location in the application.

There is no longer any tight coupling between components.

In short, when a Widget sends something to a Stream, that Widget does no longer need to know:

• what is going to happen next,
• who might use this information (no one, one or several Widgets...)
• where this information might be used (nowhere, same screen, another one, several ones...),
• when this information might be used (almost directly, after several seconds, never...).

...that Widget does only care about its own business, that's all !!

At first glance, reading this, this may seem to lead to a "no-control" of the application but, as we will see, this is the contrary. It gives you:

• the opportunity to build parts of the application only responsible for specific activities,
• to easily mock some components' behavior to allow more complete tests coverage,
• to easily reuse components (somewhere else in the application or in another application),
• to redesign the application and be able to move components from one place to another without too much refactoring,
• ...

We will see the advantages shortly... but before I need to introduce the last topic: the BLoC Pattern.

The BLoC Pattern

The BLoC Pattern has been designed by Paolo Soares and Cong Hui, from Google and first presented during the DartConf 2018 (January 23-24, 2018). See the video on YouTube.

BLoC stands for Business Logic Component.

In short, the Business Logic needs to:

• be moved to one or several BLoC s,
• be removed as much as possible from the Presentation Layer. In other words, UI components should only worry about the UI things and not about the business,
• rely on exclusive use of Streams for both input (Sink) and output (stream),
• remain platform independent,
• remain environment independent.

In fact, the BLoC pattern was initially conceived to allow to reuse the very same code independently of the platform: web application, mobile application, back-end.

What does it actually mean?

The BLoC pattern makes use of the notions that we just discussed above: Streams.

• Widgets send events to the BLoC via Sinks,
• Widgets are notified by the BLoC via streams,
• the business logic which is implemented by the BLoC is none of their concern.

From this statement, we can directly see a huge benefit.

Thanks to the decoupling of the Business Logic from the UI:

• we may change the Business Logic at any time, with a minimal impact on the application,
• we may change the UI without any impact on the Business Logic,
• it is now much easier to test the Business Logic.

How to apply this BLoC Pattern to the Counter Application sample?

Applying the BLoC pattern to this Counter Application might seem to be an overkill but let me first show you...

I already hear you saying "wow... why all this? Is this all necessary?".

First, the separation of responsibilities

If you check the CounterPage (lines 21 - 45), there is absolutely not any business logic inside it.

This page is now only responsible for:

• displaying the counter, which is now only refreshed when necessary (even without the page having to know it)
• providing a button which when hit, requests an action to be performed on the counter

Also, the whole the Business Logic is centralized in one single class "IncrementBloc".

If now, you need to change the business logic, you simply need to update the method _handleLogic (lines 72-75). Maybe the new business logic will request to do very complex things... The CounterPage will never know about it and this is very good!

Second, testability

It is now much easier to test the business logic.

No need anymore to test the business logic via the user interface. Only the IncrementBloc class needs to be tested.

Third, freedom to organize the layout

Thanks to the use of Streams, you can now organize the layout independently of the business logic.

Any action could be launched from any place in the application: simply call to the .incrementCounter sink.

You may display the counter anywhere, in any page, simply listen to the .outCounter stream.

Fourth, reduction of the number of "build"s

The fact of not using setState() but StreamBuilder, drastically reduces the amount of "build"s to only the ones which are required.

From a performance perspective, this is a huge improvement.

There is only 1 constraint... accessibility of the BLoC

In order to have all this working, the BLoC needs to be accessible.

There exists several ways of making it accessible:

• via a global Singleton

  This way is very possible but not really recommended. Also as there is no class destructor in Dart, you will never be able to release the resources properly.

• as a local instance

  You may instantiate a local instance of a BLoC. Under some circumstances, this solution perfectly fits some needs. In this case, you should always consider initializing inside a StatefulWidget so that you can take profit of the dispose() method to free it up.

• provided by an ancestor

  The most common way of making it accessible is via an ancestor Widget, implemented as a StatefulWidget.

  The following code shows a sample of a generic BlocProvider.

Some explanations on this generic BlocProvider

First, how to use it as a provider?

If you have a look at the sample code "streams_4.dart", you will see the following lines of codes (lines #13-15)

home: BlocProvider<IncrementBloc>(
  bloc: IncrementBloc(),
  child: CounterPage(),
),

With these lines, we simply instantiate a new BlocProvider which will handle a IncrementBloc, and will render the CounterPage as a child.

From that moment on, any widget part of the sub-tree, starting at BlocProvider will be able to get access to the IncrementBloc, via the following line:

IncrementBloc bloc = BlocProvider.of<IncrementBloc>(context)!;

Could we have multiple BLoCs?

Of course and this is highly advisable. Recommendations are:

• (if there is any business logic) one BLoC on top of each page,
• why not an ApplicationBloc to handle the Application State?
• each "complex enough component" has a corresponding BLoC.

The following sample code shows an ApplicationBloc on top of the whole application, then the IncrementBloc on top of the CounterPage.

The sample also shows how to retrieve both blocs.

Why not using an InheritedWidget?

In most articles related to BLoC, you will see the implementation of the Provider as an InheritedWidget.

Of course, nothing prevents this type of implementation. However,

• an InheritedWidget does not provide any dispose method and, remember, it is a very good practice to always release the resources when they are no longer needed;
• of course, nothing would prevent you from wrapping the InheritedWidget inside another StatefulWidget, but then, what is the added value of using an InheritedWidget?
• finally, the use of an InheritedWidget often leads to side effects if not controlled (see Reminder on InheritedWidget, below).

These 3 bullets explain the choice I made to implement the generic BlocProvider as a StatefulWidget, so that I am able to release the resources, when this widget is disposed.

Flutter is not able to instantiate a generic type <T>

As unfortunately Flutter is not able to instantiate a generic type, we have to pass the instance of the BLoC to the BlocProvider. To enforce the implementation of the dispose() method in each BLoC, all BLoCs have to implement the BlocBase interface.

Reminder on InheritedWidget

When we are using an InheritedWidget and are invoking the context.inheritFromWidgetOfExactType(...) method to get the nearest widget of the given type, this method invocation automatically registers this "context" (= BuildContext) to the list of ones which will be rebuilt each time a change applies to the InheritedWidget subclass or to one of its ancestors.

Please note that, in order to be fully correct, the problem related to the InheritedWidget as I have just explained only occurs when we combine the InheritedWidget with a StatefulWidget. When you simply use an InheritedWidget without a State, the issue does not happen. But... I will come back on this remark in a next article.

The type of Widget (Stateful or Stateless) linked to the BuildContext, does not matter.

Personal note on BLoC

Third rule related to BLoC says: "rely on exclusive use of Streams for both input (Sink) and output (stream)".

My personal experience relativises this statement a little bit... Let me explain.

At first, the BLoC pattern was conceived to share the very same code across platforms (AngularDart, ...) and, in this perspective, that statement makes full sense.

However, if you only intend to develop a Flutter application, this is, based on my humble experience, a little bit overkill.

If we stick to the statement, no getter or setter are possible, only sinks and streams. The drawback is "all this is asynchronous".

Let's take 2 samples to illustrate the drawbacks:

• you need to retrieve some data from the BLoC in order to use this data as input of a page that should display these parameters right away (for example, think of a parameters page), if we had to rely on Streams, this makes the build of the page asynchronous (which is complex). Sample code to make it work via Streams could be like the following one... Ugly isn't it.

• at the BLoC level, you also need to convert a "fake" injection of some data to trigger the provision of the data you expect to receive via a stream. Sample code to make this work could be:

I don't know your opinion, but personally, if I don't have any constraints related to code porting/sharing, I find this too heavy and I would rather use regular getters/setters when needed and use the Streams/Sinks to keep the separation of responsibilities and broadcast the information where needed, which is awesome.

It is now time to see all this in practice...

As mentioned in the beginning of this article, I built a pseudo-application to show how to use all these notions. The full source code can be found on Github.

Please be indulgent since this code is far from being perfect and could be much better and/or better architectured but the only objective is simply to show you how all this works.

As the source code is documented a lot, I will only explain the main principles.

Source of the movie catalog

I am using the free TMDB API to fetch the list of all movies, as well as the posters, rating and descriptions.

In order to be able to run this sample application, you will need to register and obtain the API key (which is totally free), then put your API key in the file "/api/tmdb_api.dart", line #15.

Architecture of the application

This application uses:

• 3 main BLoCs:

  • ApplicationBloc (on top of everything), responsible for delivering the list of all movie genres;
  • FavoriteBloc (just underneath), responsible for handling the notion of "Favorites";
  • MovieCatalogBloc (on top of the 2 main pages), responsible for delivering the list of movies, based on filters;

• 6 pages:

  • HomePage: landing page that allows the navigation to the 3 sub-pages;
  • ListPage: page that lists the movies as a GridView, allows filtering, favorites selection, access to the Favorites and display of the Movie details in a sub-sequent page;
  • ListOnePage: similar to ListPage but the list of movies is displayed as a horizontal list and the details, underneath;
  • FavoritesPage: page that lists the favorites and allows the deselection of any favorites;
  • Filters: EndDrawer that allows the definition of filters: genres and min/max release dates. This page is called from ListPage or ListOnePage;
  • Details: page only invoked by ListPage to show the details of a movie but also to allow the selection/unselection of the movie as a favorite;

• 1 sub BLoC:

  • FavoriteMovieBloc, linked to a MovieCardWidget or MovieDetailsWidget to handle the selection/unselection of a movie as a favorite

• 5 main Widgets:

  • FavoriteButton: widget responsible for displaying the number of favorites, real-time, and redirecting to the FavoritesPage when pressed;
  • FavoriteWidget: widget responsible for displaying the details of one favorite movie and allow its unselection;
  • FiltersSummary: widget responsible for displaying the filters currently defined;
  • MovieCardWidget: widget responsible for displaying one single movie as a card, with the movie poster, rating and name, as well as a icon to indicate the selection of that particular movie as a favorite;
  • MovieDetailsWidget: widget responsible for displaying the details related to a particular movie and to allow its selection/unselection as a favorite.

Orchestration of the different BLoCs / Streams

The following diagram shows how the main 3 BLoCs are used:

• on the left side of a BLoC, which components invoke the Sink
• on the right side, which components listen to the stream

As an example, when the MovieDetailsWidget invokes the inAddFavorite Sink, 2 streams are triggered:

• outTotalFavorites stream forces a rebuild of FavoriteButton, and
• outFavorites stream
  • forces a rebuild of MovieDetailsWidget (the "favorite" icon)
  • forces a rebuild of_buildMovieCard (the "favorite" icon)
  • is used to build each MovieDetailsWidget

Observations

Most of the Widgets and Pages are StatelessWidgets, which means that:

• the setState() which forces to rebuild is almost never used. Exceptions are:

  • in the ListOnePage when a user clicks a MovieCard, to refresh the MovieDetailsWidget. This could also have been driven by a stream...
  • in the FiltersPage to allow the user to change the filters before accepting them, via Sink.

• the application does not use any InheritedWidget

• the application is almost 100% BLoCs/Streams driven which means that most of the Widgets are independent of each other and of their location in the application

  A practical example is the FavoriteButton which displays the number of selected favorites in a badge. The application counts 3 instances of this FavoriteButton, each of them, displayed in 3 different pages.

Display of the list of movies (explanation of the trick to display an infinite list)

To display the list of movies that meet the filters criteria, we use either a GridView.builder (ListPage) or a ListView.builder (ListOnePage) as an infinite scroll list.

Movies are fetched using the TMDB API in pages of 20 movies at a time.

As a reminder, both GridView.builder and ListView.builder take as input an itemCount which, if provided, tells the number of items to be displayed. The itemBuilder is called with index varying from 0 up to itemCount - 1.

As you will see in the code, I arbitrary provide the GridView.builder with an additional 30 more. The rationale is that in this example, we are manipulating a presumed infinite number of items (which is not totally true but who cares for this example). This will force the GridView.builder to request "up to 30 additional" items to be displayed.

Also, both GridView.builder and ListView.builder only call the itemBuilder when they consider that a certain item (index) has to be rendered in the viewport.

This MovieCatalogBloc.outMoviesList returns a List<MovieCard>, which is iterated in order to build each Movie Card. The very first time, this List<MovieCard> is empty but thanks to the itemCount: ...+30, we fool the system which will ask to render 30 non-existing items via the _buildMovieCard(...).

As you will see in the code, this routine makes a weird call to the Sink:

// Notify the MovieCatalogBloc that we are rendering the MovieCard[index]
movieBloc.inMovieIndex.add(index);

This call tells the MovieCatalogBloc that we want to render the MovieCard[index].

Then the _buildMovieCard(...) goes on validating that data related to the MovieCard[index] exists. If yes, the latter is rendered, otherwise a CircularProgressIndicator is displayed.

The call to MovieCatalogBloc.inMovieIndex.add(index) is listened by a StreamSubscription that translates the index to a certain pageIndex number (one page counts up to 20 movies). If the corresponding page has not yet been fetched from the TMDB API, a call to the API is made. Once the page has been fetched, the new list of all fetched movies is sent to the _moviesController. As that stream ( = movieBloc.outMoviesList) is listened by the GridView.builder, the latter requests to rebuild the corresponding MovieCard. As we now have the data, we may render it.

Credits and additional links

Images that describe the PublishSubject, BehaviorSubject and ReplaySubject were published by ReactiveX.

Some other interesting articles worth reading:

• Fundamentals of Dart Streams [Thomas Burkhart]
• rx_command package [Thomas Burkhart]
• Build reactive mobile apps in Flutter - companion article [Filip Hracek]
• Flutter with Streams and RxDart [Brian Egan]

Conclusion

Very long article but there is still much more to say about it as it is more than obvious to me that this is the way to go forward with the development of a Flutter application. It provides so much flexibility.

Stay tuned for new articles, soon. Happy coding.

Foreword

The notions of Widget, State and Context in Flutter are ones of the most important concepts that every Flutter developer needs to fully understand.

However, the documentation is huge and this concept is not always clearly explained.

I will explain these notions with my own words and shortcuts, knowing that this might risk to shock some purists, but the real objective of this article to try to clarify the following topics:

• difference of Stateful and Stateless widgets
• what is a Context
• what is a State and how to use it
• relationship between a context and its state object
• InheritedWidget and the way to propagate the information inside a Widgets tree
• notion of rebuild

Cet article est également disponible (en Anglais) sur Medium - Flutter Community.

Part 1: Concepts

Notion of Widget

In Flutter, almost everything is a Widget.

Think of a Widget as a visual component (or a component that interacts with the visual aspect of an application).

When you need to build anything that directly or indirectly is in relation with the layout, you are using Widgets.

Notion of Widgets tree

Widgets are organized in tree structure(s).

A widget that contains other widgets is called parent Widget (or Widget container). Widgets which are contained in a parent Widget are called children Widgets.

Let's illustrate this with the base application which is automatically generated by Flutter. Here is the simplified code, limited to the build method:

@override
Widget build(BuildContext){
  return 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:',
          ),
          Text(
            '$_counter',
            style: Theme.of(context).textTheme.display1,
          ),
        ],
      ),
    ),
    floatingActionButton: FloatingActionButton(
      onPressed: _incrementCounter,
      tooltip: 'Increment',
      child: const Icon(Icons.add),
    ),
  );
}

If we now consider this basic example, we obtain the following Widgets tree structure (limited the list of Widgets present in the code):

Notion of Context

Another important notion is the Context.

A context is nothing else but a reference to the location of a Widget within the tree structure of all the Widgets which are built.

In short, think of a context as the part of Widgets tree where the Widget is attached to this tree.

A context only belongs to one widget.

If a widget 'A' has children widgets, the context of widget 'A' will become the parent context of the direct children contexts.

Reading this, it is clear that contexts are chained and are composing a tree of contexts (parent-children relationship).

If we now try to illustrate the notion of Context in the previous diagram, we obtain (still as a very simplified view) where each color represents a context (except the MyApp one, which is different):

Context Visibility (Simplified statement):

Something is only visible within its own context or in the context of its parent(s) context.

From this statement we can derive that from a child context, it is easily possible to find an ancestor (= parent) Widget.

An example is, considering the Scaffold > Center > Column > Text: context.findAncestorWidgetOfExactType(Scaffold) => returns the first Scaffold by going up to tree structure from the Text context.

From a parent context, it is also possible to find a descendant (= child) Widget but it is not advised to do so (we will discuss this later).

Types of Widgets

Widgets are of 2 types:

Stateless Widget

Some of these visual components do not depend on anything else but their own configuration information, which is provided at time of building it by its direct parent.

In other words, these Widgets will not have to care about any variation, once created.

These Widgets are called Stateless Widgets.

Typical examples of such Widgets could be Text, Row, Column, Container... where during the building time, we simply pass some parameters to them.

Parameters might be anything from a decoration, dimensions, or even other widget(s). It does not matter. The only thing which is important is that this configuration, once applied, will not change before the next building process.

A stateless widget can only be drawn once when the Widget is loaded/built, which means that that Widget cannot be redrawn based on any events or user actions.

Stateless Widget lifecycle

Here is a typical structure of the code related to a Stateless Widget.

As you may see, we can pass some additional parameters to its constructor. However, bear in mind that these parameters will NOT change (mutate) at a later stage and have to be only used as is.

class MyStatelessWidget extends StatelessWidget {
  MyStatelessWidget({
    super.key,
    required this.parameter,
  });

  final parameter;

  @override
  Widget build(BuildContext context){
    return ...
  }
}

Even if there is another method that could be overridden (createElement), the latter is almost never overridden. The only one that needs to be overridden is build.

The lifecycle of such Stateless widget is straightforward:

• initialization
• rendering via build()

Stateful Widget

Some other Widgets will handle some inner data that will change during the Widget's lifetime. This data hence becomes dynamic.

The set of data held by this Widget and which may vary during the lifetime of this Widget is called a State.

These Widgets are called Stateful Widgets.

An example of such Widget might be a list of Checkboxes that the user can select or a Button which is disabled depending on a condition.

Notion of State

A State defines the "behavioural" part of a StatefulWidget instance.

It holds information aimed at interacting / interferring with the Widget in terms of:

• behaviour
• layout

Any changes which is applied to a State forces the Widget to rebuild.

Relation between a State and a Context

For Stateful widgets, a State is associated with a Context. This association is permanent and the State object will never change its context.

Even if the Widget Context can be moved around the tree structure, the State will remain associated with that context.

When a State is associated with a Context, the State is considered as mounted.

HYPER IMPORTANT:

As a State object is associated with a context, this means that the State object is NOT (directly) accessible through another context ! (we will further discuss this in a few moment).

Stateful Widget lifecycle

Now that the base concepts have been introduced, it is time to dive a bit deeper...

Here is a typical structure of the code related to a Stateful Widget.

As the main objective of this article is to explain the notion of State in terms of "variable" data, I will intentionally skip any explanation related to some Stateful Widget overridable methods, which do not specifically relate to this. These overridable methods are didUpdateWidget, deactivate, reassemble. These will be discussed in a next article.

class MyStatefulWidget extends StatefulWidget {
  MyStatefulWidget({
      super.key,
      required this.parameter,
  });

  final parameter;

  @override
  _MyStatefulWidgetState createState() => _MyStatefulWidgetState();
}

class _MyStatefulWidgetState extends State<MyStatefulWidget> {

  @override
  void initState(){
    super.initState();

    // Additional initialization of the State
  }

  @override
  void didChangeDependencies(){
    super.didChangeDependencies();

    // Additional code
  }

  @override
  void dispose(){
    // Additional disposal code

    super.dispose();
  }

  @override
  Widget build(BuildContext context){
    return ...
  }
}

The following diagram shows (a simplified version of) the sequence of actions/calls related to the creation of a Stateful Widget. At the right side of the diagram, you will notice the inner status of the State object during the flow. You will also see the moment when the context is associated with the state, and thus becomes available (mounted).

So let's explain it with some additional details:

initState()

The initState() method is the very first method (after the constructor) to be called once the State object has been created. This method is to be overridden when you need to perform additional initializations. Typical initializations are related to animations, controllers... If you override this method, you need to call the super.initState() method and normally at first place.

In this method, a context is available but you cannot really use it yet since the framework has not yet fully associated the state with it.

Once the initState() method is complete, the State object is now initialized and the context, available.

This method will not be invoked anymore during the lifetime of this State object.

didChangeDependencies()

The didChangeDependencies() method is the second method to be invoked.

At this stage, as the context is available, you may use it.

This method is usually overridden if your Widget is linked to an InheritedWidget and/or if you need to initialize some listeners (based on the context).

Note that if your widget is linked to an InheritedWidget, this method will be called each time this Widget will be rebuilt.

If you override this method, you should invoke the super.didChangeDependencies() at first place.

build()

The build(BuildContext context) method is called after the didChangeDependencies() (and didUpdateWidget).

This is the place where you build your widget (and potentially any sub-tree).

This method will be called each time your State object changes (or when an InheritedWidget needs to notify the "registered" widgets) !!

In order to force a rebuild, you may invoke setState((){...}) method.

dispose()

The dispose() method is called when the widget is discarded.

Override this method if you need to perform some cleanup (e.g. listeners), then invoke the super.dispose() right after.

Stateless or Stateful Widget?

This is a question that many developers need to ask themselves: do I need my Widget to be Stateless or Stateful?

In order to answer this question, ask yourself:

In the lifetime of my widget, do I need to consider a variable that will change and when changed, will force the widget to be rebuilt?

If the answer to the question is yes, then you need a Stateful widget, otherwise, you need a Stateless widget.

Some examples:

• a widget to display a list of checkboxes. To display the checkboxes, you need to consider an array of items. Each item is an object with a title and a status. If you click on a checkbox, the corresponding item.status is toggled;

  In this case, you need to use a Stateful widget to remember the status of the items to be able to redraw the checkboxes.

• a screen with a Form. The screen allows the user to fill the Widgets of the Form and send the form to the server.

  In this case, unless you need to validate the Form or do any other action before submitting it, a Stateless widget might be enough.

Stateful Widget is made of 2 parts

Remember the structure of a Stateful widget? There are 2 parts:

The Widget main definition

class MyStatefulWidget extends StatefulWidget {
  const MyStatefulWidget({
    super.key,
    required this.color,
  });

  final Color color;

  @override
  _MyStatefulWidgetState createState() => _MyStatefulWidgetState();
}

The first part "MyStatefulWidget" is normally the public part of the Widget. You instantiate this part when you want to add it to a widget tree. This part does not vary during the lifetime of the Widget but may accept parameters that could be used by its corresponding State instance.

Note that any variable, defined at the level of this first part of the Widget will normally NOT change during its lifetime.

The Widget State definition

class _MyStatefulWidgetState extends State<MyStatefulWidget> {
  ...
  @override
  Widget build(BuildContext context){
    ...
  }
}

The second part "_MyStatefulWidgetState" is the part which varies during the lifetime of the Widget and forces this specific instance of the Widget to rebuild each time a modification is applied. The '_' character in the beginning of the name makes the class private to the .dart file.

If you need to make a reference to this class outside the .dart file, do not use the '_' prefix.

The _MyStatefulWidgetState class can access any variable which is stored in the MyStatefulWidget, using widget.{name of the variable}. In this example: widget.color

Widget unique identity - Key

In Flutter, each Widget is uniquely identified. This unique identity is defined by the framework at build/rendering time.

This unique identity corresponds to the optional Key parameter. If omitted, Flutter will generate one for you.

In some circumstances, you might need to force this key, so that you can access a widget by its key.

To do so, you can use one of the following helpers: GlobalKey<T>, LocalKey, UniqueKey or ObjectKey.

The GlobalKey ensures that the key is unique across the whole application.

To force a unique identity of a Widget:

GlobalKey myKey = GlobalKey();
...
@override
Widget build(BuildContext context){
  return MyWidget(
    key: myKey
  );
}

Part 2: How to access the State?

As previously explained, a State is linked to one Context and a Context is linked to an instance of a Widget.

1. The Widget itself

In theory, the only one which is able to access a State is the Widget State itself.

In this case, there is no difficulty. The Widget State class accesses any of its variables.

2. A direct child Widget

Sometimes, a parent widget might need to get access to the State of one of its direct children to perform specific tasks.

In this case, to access these direct children State, you need to know them.

The easiest way to call somebody is via a name. In Flutter, each Widget has a unique identity, which is determined at build/rendering time by the framework. As shown earlier, you may force the identity of a Widget, using the key parameter.

...
GlobalKey<MyStatefulWidgetState> myWidgetStateKey = GlobalKey<MyStatefulWidgetState>();
...
@override
Widget build(BuildContext context){
  return MyStatefulWidget(
    key: myWidgetStateKey,
    color: Colors.blue,
  );
}

Once identified, a parent Widget might access the State of its child via:

myWidgetStateKey.currentState

Let's consider a basic example that opens the Drawer when the user hits a button. As the Drawer is a child Widget of the Scaffold it is not directly accessible to any other child of the body of the Scaffold (remember the notion of context and its hierarchy/tree structure ?). Therefore, the only way to access it, is via the ScaffoldState, which exposes a public method to open the Drawer.

class _MyScreenState extends State<MyScreen> {
  /// the unique identity of the Scaffold
  final GlobalKey<ScaffoldState> _scaffoldKey = GlobalKey<ScaffoldState>();

  @override
  Widget build(BuildContext context){
    return Scaffold(
      key: _scaffoldKey,
      appBar: AppBar(
        title: Text("My Screen"),
      ),
      drawer: Drawer(),
      body: Center(
        RaiseButton(
          child: Text("Hit me"),
          onPressed: (){
            _scaffoldKey.currentState?.openDrawer();
          }
        ),
      ),
    );
  }
}

3. Ancestor Widget

Suppose that you have a Widget that belongs to a sub-tree of another Widget as shown in the following diagram.

3 conditions need to be met to make this possible:

1. the "Widget with State" (in red) needs to expose its State

In order to expose its State, the Widget needs to record it at time of creation, as follows:

class MyExposingWidget extends StatefulWidget {

  late MyExposingWidgetState myState;

  @override
  MyExposingWidgetState createState(){
    myState = MyExposingWidgetState();
    return myState;
  }
}

2. the "Widget State" needs to expose some getters/setters

In order to let a "stranger" to set/get a property of the State, the Widget State needs to authorize the access, through:

• public property (not recommended)
• getter / setter

Example:

class MyExposingWidgetState extends State<MyExposingWidget>{
  Color _color;

  Color get color => _color;
  ...
}

3. the "Widget interested in getting the State" (in blue) needs to get a reference to the State

class MyChildWidget extends StatelessWidget {
  @override
  Widget build(BuildContext context){
    final MyExposingWidget? widget = context.findAncestorWidgetOfExactType(MyExposingWidget);
    final MyExposingWidgetState? state = widget?.myState;

    return Container(
      color: state == null ? Colors.blue : state.color,
    );
  }
}

This solution is easy to implement but how does the child widget know when it needs to rebuild?

With this solution, it does not. It will have to wait for a rebuild to happen to refresh its content, which is not very convenient.

The next section tackles the notion of Inherited Widget which gives a solution to this problem.

InheritedWidget

In short and with simple words, the InheritedWidget allows to efficiently propagate (and share) information down a tree of widgets.

The InheritedWidget is a special Widget, that you put in the Widgets tree as a parent of another sub-tree. All widgets part of that sub-tree will have to ability to interact with the data which is exposed by that InheritedWidget.

Basics

In order to explain it, let's consider the following piece of code:

class MyInheritedWidget extends InheritedWidget {
  MyInheritedWidget({
    Key? key,
    required Widget child,
    this.data,
  }): super(key: key, child: child);

  final data;

  static MyInheritedWidget? of(BuildContext context) {
    return context.dependOnInheritedWidgetOfExactType<MyInheritedWidget>();
  }

  @override
  bool updateShouldNotify(MyInheritedWidget oldWidget) => data != oldWidget.data;
}

This code defines a Widget, named "MyInheritedWidget", aimed at "sharing" some data across all widgets, part of the child sub-tree.

As mentioned earlier, an InheritedWidget needs to be positioned at the top of a widgets tree in order to be able to propagate/share some data, this explains the required Widget child which is passed to the InheritedWidget base constructor.

The static MyInheritedWidget of(BuildContext context) method, allows all the children widgets to get the instance of the closest MyInheritedWidget which encloses the context (see later).

Finally the updateShouldNotify overridden method is used to tell the InheritedWidget whether notifications will have to be passed to all the children widgets (that registered/subscribed) if a modification be applied to the data (see later).

Therefore, we need to put it at a tree node level as follows:

class MyParentWidget... {
  ...
  @override
  Widget build(BuildContext context){
    return MyInheritedWidget(
      data: counter,
      child: Row(
        children: <Widget>[
          ...
        ],
      ),
    );
  }
}

How does a child get access to the data of the InheritedWidget?

At time of building a child, the latter will get a reference to the InheritedWidget, as follows:

class MyChildWidget... {
  ...

  @override
  Widget build(BuildContext context){
    final MyInheritedWidget? inheritedWidget = MyInheritedWidget.of(context);

    ///
    /// From this moment, the widget can use the data, exposed by the MyInheritedWidget
    /// by calling:  inheritedWidget.data
    ///
    return Container(
      color: inheritedWidget?.data.color,
    );
  }
}

How to make interactions between Widgets?

Consider the following diagram that shows a widgets tree structure.

In order to illustrate a type of interaction, let's suppose the following:

• 'Widget A' is a button that adds an item to the shopping cart;
• 'Widget B' is a Text that displays the number of items in the shopping cart;
• 'Widget C' is next to Widget B and is a Text with any text inside;
• We want the 'Widget B' to automatically display the right number of items in the shopping cart, as soon as the 'Widget A' is pressed but we do not want 'Widget C' to be rebuilt

The InheritedWidget is just the right Widget to use for that!

Example by the code

Let's first write the code and explanations will follow:

class Item {
    Item(this.reference);

    String reference;
  }

  class _MyInherited extends InheritedWidget {
    const _MyInherited({
      Key? key,
      required Widget child,
      required this.data,
    }) : super(key: key, child: child);

    final MyInheritedWidgetState data;

    @override
    bool updateShouldNotify(_MyInherited oldWidget) => true;
  }

  class MyInheritedWidget extends StatefulWidget {
    const MyInheritedWidget({
      super.key,
      required this.child,
    });

    final Widget child;

    @override
    MyInheritedWidgetState createState() => MyInheritedWidgetState();

    static MyInheritedWidgetState? of(BuildContext context) {
      return (context.dependOnInheritedWidgetOfExactType<_MyInherited>())
          ?.data;
    }
  }

  class MyInheritedWidgetState extends State<MyInheritedWidget> {
    // List of Items
    final List<Item> _items = <Item>[];

    // Getter (number of items)
    int get itemsCount => _items.length;

    // Helper method to add an Item
    void addItem(String reference) {
      if (mounted) {
        setState(() {
          _items.add(Item(reference));
        });
      }
    }

    @override
    Widget build(BuildContext context) {
      return _MyInherited(
        data: this,
        child: widget.child,
      );
    }
  }

  class MyTree extends StatefulWidget {
    const MyTree({super.key});

    @override
    _MyTreeState createState() => _MyTreeState();
  }

  class _MyTreeState extends State<MyTree> {
    @override
    Widget build(BuildContext context) {
      return MyInheritedWidget(
        child: Scaffold(
          appBar: AppBar(
            title: const Text('Title'),
          ),
          body: Column(
            children: <Widget>[
              const WidgetA(),
              Row(
                children: const <Widget>[
                  Icon(Icons.shopping_cart),
                  WidgetB(),
                  WidgetC(),
                ],
              ),
            ],
          ),
        ),
      );
    }
  }

  class WidgetA extends StatelessWidget {
    const WidgetA({super.key});

    @override
    Widget build(BuildContext context) {
      final MyInheritedWidgetState? state = MyInheritedWidget.of(context);
      return ElevatedButton(
        child: const Text('Add Item'),
        onPressed: () {
          state?.addItem('new item');
        },
      );
    }
  }

  class WidgetB extends StatelessWidget {
    const WidgetB({super.key});

    @override
    Widget build(BuildContext context) {
      final MyInheritedWidgetState? state = MyInheritedWidget.of(context);
      return Text('\${state?.itemsCount}');
    }
  }

  class WidgetC extends StatelessWidget {
    const WidgetC({super.key});

    @override
    Widget build(BuildContext context) {
      return const Text("I am Widget C");
    }
  }

Explanations

In this very basic example,

• _MyInherited is an InheritedWidget that is recreated each time we add an Item via a click on the button of 'Widget A'
• MyInheritedWidget is a Widget with a State that contains the list of Items. This State is accessible via the static MyInheritedWidgetState of(BuildContext context)
• MyInheritedWidgetState exposes one getter (itemsCount) and one method (addItem) so that they will be usable by the widgets, part of the child widgets tree
• Each time we add an Item to the State, the MyInheritedWidgetState rebuilds
• MyTree class simply builds a widgets tree, having the MyInheritedWidget as parent of the tree
• WidgetA is a simple ElevatedButton which, when pressed, invokes the addItem method from the closest MyInheritedWidget
• WidgetB is a simple Text which displays the number of items, present at the level of the closest MyInheritedWidget

How does all this work?

Registration of a Widget for later notifications

When a child Widget invokes the MyInheritedWidget.of(context), it makes a call to the following method of MyInheritedWidget, passing its own context.

static MyInheritedWidgetState? of(BuildContext context) {
  return (context.dependOnInheritedWidgetOfExactType<_MyInherited>())
         ?.data;
}

Internally, on top of simply returning the instance of MyInheritedWidgetState, it also subscribes the consumer widget to the changes notifications.

Behind the scene, the simple call to this static method actually does 2 things:

• the consumer widget is automatically added to the list of subscribers that will be rebuilt when a modification is applied to the InheritedWidget (here _MyInherited)
• the data referenced in the _MyInherited widget (aka MyInheritedWidgetState) is returned to the consumer

Flow

Since both 'Widget A' and 'Widget B' have subscribed with the InheritedWidget so that if a modification is applied to the _MyInherited, the flow of operations is the following (simplified version) when the ElevatedButton of Widget A is clicked:

1. A call is made to the addItem method of MyInheritedWidgetState
2. MyInheritedWidgetState.addItem method adds a new Item to the List<Item>
3. setState() is invoked in order to rebuild the MyInheritedWidget
4. A new instance of _MyInherited is created with the new content of the List<Item>
5. _MyInherited records the new State which is passed in argument (data)
6. As an InheritedWidget, it checks whether there is a need to notify the consumers (answer is true)
7. It iterates the whole list of consumers (here Widget A and Widget B) and requests them to rebuild
8. As Wiget C is not a consumer, it is not rebuilt.

So it works !

However, both Widget A and Widget B are rebuilt while it is useless to rebuild Widget A since nothing changed for it. How to prevent this from happening?

Prevent some Widgets from rebuilding while still accessing the Inherited Widget

The reason why Widget A was also rebuilt comes from the way it accesses the MyInheritedWidgetState.

As we saw earlier, the fact of invoking the context.inheritFromWidgetOfExactType() method automatically subscribed the Widget to the list of consumers.

The solution to prevent this automatic subscription while still allowing the Widget A access the MyInheritedWidgetState is to change the static method of MyInheritedWidget as follows:

static MyInheritedWidgetState of(BuildContext context, [bool rebuild = true]){
  return (rebuild
    ? context.dependOnInheritedWidgetOfExactType<_MyInherited>()
    : context.findAncestorWidgetOfExactType<_MyInherited>())
  ?.data;
}

By adding a boolean extra parameter...

• If the rebuild parameter is true (by default), we use the normal approach (and the Widget will be added to the list of subscribers)
• If the rebuild parameter is false, we still get access to the data but without using the internal implementation of the InheritedWidget

So, to complete the solution, we also need to slightly update the code of Widget A as follows (we add the false extra parameter):

class WidgetA extends StatelessWidget {
  @override
  Widget build(BuildContext context) {
    final MyInheritedWidgetState? state = MyInheritedWidget.of(context, false);
    return Container(
      child: ElevatedButton(
        child: cont Text("Add Item"),
        onPressed: () {
          state?.addItem("new item");
        },
      ),
    );
  }
}

There it is, Widget A is no longer rebuilt when we press it.

Special note for Routes, Dialogs...

Routes, Dialogs contexts are tied to the Application.

This means that even if inside a Screen A you request to display another Screen B (on top of the current, for example), there is no easy way from any of the 2 screens to relate their own contexts.

The only way for Screen B to know anything about the context of Screen A is to obtain it from Screen A as parameter of Navigator.of(context).push(....)

Conclusions

There is still so much to say on these topics... especially on InheritedWidget.

In a next article I will introduce the notion of Notifiers / Listeners which is also very interesting to use in the context of State and the way of conveying data.

So, stay tuned and happy coding.

Didier,