The logic and internal state for a StatefulWidget.

State is information that (1) can be read synchronously when the widget is built and (2) might change during the lifetime of the widget. It is the responsibility of the widget implementer to ensure that the State is promptly notified when such state changes, using State.setState.

State objects are created by the framework by calling the StatefulWidget.createState method when inflating a StatefulWidget to insert it into the tree. Because a given StatefulWidget instance can be inflated multiple times (e.g., the widget is incorporated into the tree in multiple places at once), there might be more than one State object associated with a given StatefulWidget instance. Similarly, if a StatefulWidget is removed from the tree and later inserted in to the tree again, the framework will call StatefulWidget.createState again to create a fresh State object, simplifying the lifecycle of State objects.

State objects have the following lifecycle:

• The framework creates a State object by calling StatefulWidget.createState.
• The newly created State object is associated with a BuildContext. This association is permanent: the State object will never change its BuildContext. However, the BuildContext itself can be moved around the tree along with its subtree. At this point, the State object is considered mounted.
• The framework calls initState. Subclasses of State should override initState to perform one-time initialization that depends on the BuildContext or the widget, which are available as the context and widget properties, respectively, when the initState method is called.
• The framework calls didChangeDependencies. Subclasses of State should override didChangeDependencies to perform initialization involving InheritedWidgets. If BuildContext.dependOnInheritedWidgetOfExactType is called, the didChangeDependencies method will be called again if the inherited widgets subsequently change or if the widget moves in the tree.
• At this point, the State object is fully initialized and the framework might call its build method any number of times to obtain a description of the user interface for this subtree. State objects can spontaneously request to rebuild their subtree by calling their setState method, which indicates that some of their internal state has changed in a way that might impact the user interface in this subtree.
• During this time, a parent widget might rebuild and request that this location in the tree update to display a new widget with the same runtimeType and Widget.key. When this happens, the framework will update the widget property to refer to the new widget and then call the didUpdateWidget method with the previous widget as an argument. State objects should override didUpdateWidget to respond to changes in their associated widget (e.g., to start implicit animations). The framework always calls build after calling didUpdateWidget, which means any calls to setState in didUpdateWidget are redundant. (See also the discussion at Element.rebuild.)
• During development, if a hot reload occurs (whether initiated from the command line flutter tool by pressing r, or from an IDE), the reassemble method is called. This provides an opportunity to reinitialize any data that was prepared in the initState method.
• If the subtree containing the State object is removed from the tree (e.g., because the parent built a widget with a different runtimeType or Widget.key), the framework calls the deactivate method. Subclasses should override this method to clean up any links between this object and other elements in the tree (e.g. if you have provided an ancestor with a pointer to a descendant's RenderObject).
• At this point, the framework might reinsert this subtree into another part of the tree. If that happens, the framework will ensure that it calls build to give the State object a chance to adapt to its new location in the tree. If the framework does reinsert this subtree, it will do so before the end of the animation frame in which the subtree was removed from the tree. For this reason, State objects can defer releasing most resources until the framework calls their dispose method.
• If the framework does not reinsert this subtree by the end of the current animation frame, the framework will call dispose, which indicates that this State object will never build again. Subclasses should override this method to release any resources retained by this object (e.g., stop any active animations).
• After the framework calls dispose, the State object is considered unmounted and the mounted property is false. It is an error to call setState at this point. This stage of the lifecycle is terminal: there is no way to remount a State object that has been disposed.

See also:

• StatefulWidget, where the current configuration of a State is hosted, and whose documentation has sample code for State.
• StatelessWidget, for widgets that always build the same way given a particular configuration and ambient state.
• InheritedWidget, for widgets that introduce ambient state that can be read by descendant widgets.
• Widget, for an overview of widgets in general.

Mixed-in types

• Diagnosticable

Implementers

• AnimatedGridState
• AnimatedListState
• AutofillGroupState
• AutomaticKeepAliveClientMixin
• DrawerControllerState
• EditableTextState
• FormFieldState
• FormState
• ImplicitlyAnimatedWidgetState
• MaterialStateMixin
• NavigatorState
• NestedScrollViewState
• OverlayState
• PaginatedDataTableState
• PopupMenuButtonState
• PopupMenuItemState
• RawGestureDetectorState
• RawScrollbarState
• RawTooltipState
• RefreshIndicatorState
• ReorderableListState
• RestorationMixin
• ScaffoldMessengerState
• ScaffoldState
• ScrollableState
• ScrollNotificationObserverState
• SegmentedButtonState
• SelectableRegionState
• SelectionAreaState
• SingleTickerProviderStateMixin
• SliverAnimatedGridState
• SliverAnimatedListState
• SliverReorderableListState
• TickerProviderStateMixin
• TooltipState
• TwoDimensionalScrollableState
• UndoHistoryState

Annotations

• @optionalTypeArgs

Constructors

State()

Properties

context → BuildContext

The location in the tree where this widget builds.

no setter

hashCode → int

The hash code for this object.

no setterinherited

mounted → bool

Whether this State object is currently in a tree.

no setter

runtimeType → Type

A representation of the runtime type of the object.

no setterinherited

widget → T

The current configuration.

no setter

Methods

activate() → void

Called when this object is reinserted into the tree after having been removed via deactivate.

build(BuildContext context) → Widget

Describes the part of the user interface represented by this widget.

deactivate() → void

Called when this object is removed from the tree.

debugFillProperties(DiagnosticPropertiesBuilder properties) → void

Add additional properties associated with the node.

override

didChangeDependencies() → void

Called when a dependency of this State object changes.

didUpdateWidget(covariant T oldWidget) → void

Called whenever the widget configuration changes.

dispose() → void

Called when this object is removed from the tree permanently.

initState() → void

Called when this object is inserted into the tree.

noSuchMethod(Invocation invocation) → dynamic

Invoked when a nonexistent method or property is accessed.

inherited

reassemble() → void

Called whenever the application is reassembled during debugging, for example during hot reload.

setState(VoidCallback fn) → void

Notify the framework that the internal state of this object has changed.

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

Operators

operator ==(Object other) → bool

The equality operator.

inherited