- Widgets provide an immutable description of the user interface. Though widgets themselves are immutable, they may be freely replaced, removed, or rearranged (note that updating a widget's child typically requires the parent widget to be replaced, too). Creating and destroying widgets is efficient since widgets are lightweight, immutable instances that are, ideally, compile-time constants.
- The immutable widget tree is used to create and configure (i.e., inflate) a mutable element tree which manages a separate render tree; this final tree is responsible for layout, painting, gestures, and compositing. The element tree is efficiently synchronized with widget changes, reusing and mutating elements where possible (that is, though a widget may be replaced with a different instance, provided the two instances have the same runtime type and key, the original element will be updated and not recreated). Modifying the element tree typically updates the render tree which, in turns, changes what appears on the screen.
- The main widget types are
StatelessWidget. Widgets that export data to one or more descendant widgets (via notifications or another mechanism) utilize
ProxyWidgetor one of its subclasses (e.g.,
- In general, widgets either directly or indirectly configure render objects by modifying the element tree. Most widgets created by application developers (via
StatelessWidget) delegate to a constellation of descendant widgets, typically via a build method (e.g.,
StatelessWidget.build). Others (e.g.,
RenderObjectWidget) manage a render object directly (creating it and updating it via
- Certain widgets wrap an explicit child widget via
ProxyWidget, introducing heritable state (e.g.,
InheritedModel) or configuring auxiliary data (e.g.,
ProxyWidgetnotifies clients (via
ProxyElement.notifyClients) in response to widget changes (via
ProxyElement.updated, called by
ParentDataWidgetupdates the nearest descendant render objects' parent data (via
ParentDataElement._applyParentData, which calls
RenderObjectElement._updateParentData); this process is triggered any time the corresponding widget is updated.
- There are also bespoke widget subclasses that support less common types of configuration. For instance,
Widgetto capture a preferred size allowing subclasses (e.g.,
PreferredSize) to express sizing information to their containers (e.g.,
MultiChildRenderObjectWidgetprovide storage for render object widgets with zero or more children without constraining how the underlying render object is created or updated. These widgets correspond to
MultiChildRenderObjectElement, respectively, which manage the underlying child model in the element and render trees.
- Anonymous widgets can be created using
StatelessWidgetis a trivial subclass of
Widgetthat defines a
StatelessWidget.buildmethod and configures a
ComponentElementsubclass that invokes
StatelessWidget.buildin response to
StatelessElement.build(e.g., delegates building to its widget).
StatefulWidgetis associated with
ComponentElementthat is almost identical to
StatelessElement. The key difference is that the
StatefulElementretains a reference to the
Stateof the corresponding
StatefulWidget, invoking methods on that instance rather than the widget itself. For instance, when
StatefulElement.updateis invoked, the
Stateinstance is notified via
StatefulElementcreates the associated
Stateinstance when it is constructed (i.e., in
StatefulWidget.createElement). Then, when the
StatefulElementis built for the first time (via
StatefulElement._firstBuild, called by
State.initStateis invoked. Crucially,
Stateinstance and the
StatefulWidgetreference the same element.
Stateis associated with the underlying
StatefulElement, if the widget changes, provided that
StatefulElement.updateChildis able to reuse the same element (because the widget’s runtime type and key both match),
Statewill be preserved. Otherwise, the
Statewill be recreated.
- Flutter doesn't have the ability to compare trees. That is, only an element's immediate children are considered when matching widgets and elements (via
- When increasing the tree depth (i.e., inserting an intermediate node), the existing parent will be configured with a child corresponding to the intermediate widget. In most cases, this widget will not correspond to a previous child (i.e.,
Widget.canUpdatewill return false). Thus, the new element will be freshly inflated. Since the intermediate node is the new owner of its parent's children, each of those children will also be inflated (the intermediate node doesn't have access to the existing elements). This will proceed down the entire subtree.
- When decreasing the tree depth, the parent will once again be assigned new children which likely won't sync with old children. Thus, the new children will need to be inflated, cascading down the entire subtree.
- Adding a
GlobalKeyto the previous child can mitigate this issue since
Element.updateChildis able to reuse elements that are stored in the
GlobalKeyregistry (allowing that subtree to simply be reinserted instead of rebuilt).
- Notification support is not built directly into the widget abstraction, but layered on top of it.
Notificationis an abstract class that searches up the element tree, visiting each widget subclass of
Notification.visitAncestor, which performs this walk).
- The notification invokes
NotificationListener._dispatchon each suitable widget, comparing the notification's static type with the callback's type parameter. If there's a match (i.e., the notification is a subtype of the callback's type parameter), the listener is invoked.
- If the listener returns true, the walk terminates. Otherwise, the notification continues to bubble up the tree.