RestorationMixin<S extends StatefulWidget> mixin Null safety

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).

link
This example demonstrates how to make a simple counter app restorable by using the RestorationMixin and a RestorableInt.
To create a local project with this code sample, run:
flutter create --sample=widgets.RestorationMixin.1 mysample

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.
Superclass Constraints
Mixin Applications
Annotations

Properties

restorationId → String?
The restoration ID used for the RestorationBucket in which the mixin will store the restoration data of all registered properties.
protected">@protectedread-only
bucket → RestorationBucket?
The RestorationBucket used for the restoration data of the RestorablePropertys registered to this mixin.
read-only
restorePending → bool
Whether restoreState will be called at the beginning of the next build phase.
read-only
widget → S
The current configuration.
read-onlyinherited
context → BuildContext
The location in the tree where this widget builds.
read-onlyinherited
mounted → bool
Whether this State object is currently in a tree.
read-onlyinherited
hashCode → int
The hash code for this object.
read-onlyinherited
runtimeType → Type
A representation of the runtime type of the object.
read-onlyinherited

Methods

activate() → void
Called when this object is reinserted into the tree after having been removed via deactivate.
mustCallSuper">@mustCallSuperprotected">@protectedinherited
build(BuildContext context) → Widget
Describes the part of the user interface represented by this widget.
protected">@protectedinherited
deactivate() → void
Called when this object is removed from the tree.
mustCallSuper">@mustCallSuperprotected">@protectedinherited
debugFillProperties(DiagnosticPropertiesBuilder properties) → void
Add additional properties associated with the node.
inherited
didChangeDependencies() → void
Called when a dependency of this State object changes.
override
didToggleBucket(RestorationBucket? oldBucket) → void
Called when bucket switches between null and non-null values.
mustCallSuper">@mustCallSuperprotected">@protected
didUpdateRestorationId() → void
Must be called when the value returned by restorationId changes.
protected">@protected
didUpdateWidget(covariant S oldWidget) → void
Called whenever the widget configuration changes.
override
dispose() → void
Called when this object is removed from the tree permanently.
override
initState() → void
Called when this object is inserted into the tree.
mustCallSuper">@mustCallSuperprotected">@protectedinherited
noSuchMethod(Invocation invocation) → dynamic
Invoked when a non-existent method or property is accessed.
inherited
reassemble() → void
Called whenever the application is reassembled during debugging, for example during hot reload.
mustCallSuper">@mustCallSuperprotected">@protectedinherited
registerForRestoration(RestorableProperty<Object?> property, String restorationId) → void
Registers a RestorableProperty for state restoration.
protected">@protected
restoreState(RestorationBucket? oldBucket, bool initialRestore) → void
Called to initialize or restore the RestorablePropertys used by the State object.
mustCallSuper">@mustCallSuperprotected">@protected
setState(VoidCallback fn) → void
Notify the framework that the internal state of this object has changed.
protected">@protectedinherited
toDiagnosticsNode({String? name, DiagnosticsTreeStyle? style}) → DiagnosticsNode
Returns a debug representation of the object that is used by debugging tools and by DiagnosticsNode.toStringDeep.
inherited
toString({DiagnosticLevel minLevel = DiagnosticLevel.info}) → String
A string representation of this object.
inherited
toStringShort() → String
A brief description of this object, usually just the runtimeType and the hashCode.
inherited
unregisterFromRestoration(RestorableProperty<Object?> property) → void
Unregisters a RestorableProperty from state restoration.
protected">@protected

Operators

operator ==(Object other) → bool
The equality operator.
inherited