BindingBase class Null safety

Base class for mixins that provide singleton services.

The Flutter engine (dart:ui) exposes some low-level services, but these are typically not suitable for direct use, for example because they only provide a single callback which an application may wish to multiplex to allow multiple listeners.

Bindings provide the glue between these low-level APIs and the higher-level framework APIs. They bind the two together, whence the name.

Implementing a binding mixin

A library would typically create a new binding mixin to expose a feature in dart:ui. This is rare in general, but it is something that an alternative framework would do, e.g. if a framework were to replace the widgets library with an alternative API but still wished to leverage the services and foundation libraries.

To create a binding mixin, declare a mixin on the BindingBase class and whatever other bindings the concrete binding must implement for this binding mixin to be useful.

The mixin is guaranteed to only be constructed once in the lifetime of the app; this is handled by initInstances.

A binding mixin must at a minimum implement the following features:

• The initInstances method, which must call super.initInstances and set an _instance static field to this.
• An instance static getter, which must return that field using checkInstance.

In addition, it should implement whatever singleton features the library needs.

As a general rule, the less can be placed in the binding, the better. Prefer having APIs that takes objects rather than having them refer to global singletons. Bindings are best limited to exposing features that literally only exist once, for example, the APIs in dart:ui.

mixin FooBinding on BindingBase, BarBinding {
  @override
  void initInstances() {
    super.initInstances();
    _instance = this;
    // ...binding initialization...
  }

  static FooBinding get instance => BindingBase.checkInstance(_instance);
  static FooBinding? _instance;

  // ...binding features...
}

Implementing a binding class

The top-most layer used to write the application (e.g. the Flutter widgets library) will have a concrete class that inherits from BindingBase and uses all the various BindingBase mixins (such as ServicesBinding). The widgets library in Flutter introduces a binding called WidgetsFlutterBinding.

A binding class should mix in the relevant bindings from each layer that it wishes to expose, and should have an ensureInitialized method that constructs the class if that layer's mixin's _instance field is null. This allows the binding to be overriden by developers who have more specific needs, while still allowing other code to call ensureInitialized when a binding is needed.

class FooLibraryBinding extends BindingBase with BarBinding, FooBinding {
  static FooBinding ensureInitialized() {
    if (FooBinding._instance == null) {
      FooLibraryBinding();
    }
    return FooBinding.instance;
  }
}