RestorationMixin<S extends StatefulWidget> mixin

Manages the restoration data for a State object of a StatefulWidget.

Restoration data can be serialized out and, at a later point in time, be used to restore the stateful members in the State object to the same values they had when the data was generated.

This mixin organizes the restoration data of a State object in RestorableProperty. All the information that the State object wants to get restored during state restoration need to be saved in a subclass of RestorableProperty. For example, to restore the count value in a counter app, that value should be stored in a member variable of type RestorableInt instead of a plain member variable of type int.

The mixin ensures that the current values of the RestorablePropertys are serialized as part of the restoration state. It is up to the State to ensure that the data stored in the properties is always up to date. When the widget is restored from previously generated restoration data, the values of the RestorablePropertys are automatically restored to the values that had when the restoration data was serialized out.

Within a State that uses this mixin, RestorablePropertys are usually instantiated to initialize member variables. Users of the mixin must override restoreState and register their previously instantiated RestorablePropertys in this method by calling registerForRestoration. The mixin calls this method for the first time right after State.initState. After registration, the values stored in the property have either been restored to their previous value or - if no restoration data for restoring is available - they are initialized with a property-specific default value. At the end of a State object's life cycle, all restorable properties must be disposed in State.dispose.

In addition to being invoked right after State.initState, restoreState is invoked again when new restoration data has been provided to the mixin. When this happens, the State object must re-register all properties with registerForRestoration again to restore them to their previous values as described by the new restoration data. All initialization logic that depends on the current value of a restorable property should be included in the restoreState method to ensure it re-executes when the properties are restored to a different value during the life time of the State object.

Internally, the mixin stores the restoration data from all registered properties in a RestorationBucket claimed from the surrounding RestorationScope using the State-provided restorationId. The restorationId must be unique in the surrounding RestorationScope. State restoration is disabled for the State object using this mixin if restorationId is null or when there is no surrounding RestorationScope. In that case, the values of the registered properties will not be restored during state restoration.

The RestorationBucket used to store the registered properties is available via the bucket getter. Interacting directly with the bucket is uncommon, but the State object may make this bucket available for its descendants to claim child buckets from. For that, the bucket is injected into the widget tree in State.build with the help of an UnmanagedRestorationScope.

The bucket getter returns null if state restoration is turned off. If state restoration is turned on or off during the lifetime of the widget (e.g. because restorationId changes from null to non-null) the value returned by the getter will also change from null to non-null or vice versa. The mixin calls didToggleBucket on itself to notify the State object about this change. Overriding this method is not necessary as long as the State object does not directly interact with the bucket.

Whenever the value returned by restorationId changes, didUpdateRestorationId must be called (unless the change already triggers a call to didUpdateWidget).

See also:

• RestorableProperty, which is the base class for all restoration properties managed by this mixin.
• RestorationManager, which describes how state restoration in Flutter works.
• RestorationScope, which creates a new namespace for restoration IDs in the widget tree.