Widgets

What are the widget building blocks?

• 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 RenderObjectWidget, StatefulWidget, and StatelessWidget. Widgets that export data to one or more descendant widgets (via notifications or another mechanism) utilize ProxyWidget or one of its subclasses (e.g., InheritedWidget or ParentDataWidget).

• In general, widgets either directly or indirectly configure render objects by modifying the element tree. Most widgets created by application developers (via StatefulWidget and 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 RenderObjectWidget.createRenderObject and RenderObjectWidget.updateRenderObject, respectively).

• Certain widgets wrap an explicit child widget viaProxyWidget, introducing heritable state (e.g.,InheritedWidget, InheritedModel) or configuring auxiliary data (e.g.,ParentDataWidget).

  • ProxyWidget notifies clients (via ProxyElement.notifyClients) in response to widget changes (via ProxyElement.updated, called by ProxyElement.update).

  • ParentDataWidget updates 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,PreferredSizeWidget extends Widget to capture a preferred size allowing subclasses (e.g., AppBar, TabBar, PreferredSize ) to express sizing information to their containers (e.g., Scaffold).

• LeafRenderObjectWidget, SingleChildRenderObjectWidget, and MultiChildRenderObjectWidget provide storage for render object widgets with zero or more children without constraining how the underlying render object is created or updated. These widgets correspond toLeafRenderObjectElement, SingleChildRenderObjectElement, and MultiChildRenderObjectElement, respectively, which manage the underlying child model in the element and render trees.

• Anonymous widgets can be created using Builder and StatefulBuilder.

How do stateless widgets work?

• StatelessWidget is a trivial subclass of Widget that defines a StatelessWidget.build method and configures a StatelessElement.

• StatelessElement is a ComponentElement subclass that invokes StatelessWidget.build in response to StatelessElement.build (e.g., delegates building to its widget).

How do stateful widgets work?

• StatefulWidget is associated with StatefulElement, a ComponentElement that is almost identical to StatelessElement. The key difference is that the StatefulElement retains a reference to the State of the corresponding StatefulWidget, invoking methods on that instance rather than the widget itself. For instance, when StatefulElement.update is invoked, the State instance is notified via State.didUpdateWidget.

• StatefulElement creates the associated State instance when it is constructed (i.e., in StatefulWidget.createElement). Then, when the StatefulElement is built for the first time (via StatefulElement._firstBuild, called by StatefulElement.mount), State.initState is invoked. Crucially, State instance and the StatefulWidget reference the same element.

• Since State is associated with the underlying StatefulElement, if the widget changes, provided that StatefulElement.updateChild is able to reuse the same element (because the widget’s runtime type and key both match), State will be preserved. Otherwise, the State will be recreated.

Why is changing tree depth expensive?

• 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 RenderObjectElement.updateChildren).

• 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.canUpdate will 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 GlobalKey to the previous child can mitigate this issue since Element.updateChild is able to reuse elements that are stored in the GlobalKey registry (allowing that subtree to simply be reinserted instead of rebuilt).

How do notifications work?

• Notification support is not built directly into the widget abstraction, but layered on top of it.

• Notification is an abstract class that searches up the element tree, visiting each widget subclass of NotificationListener (Notification.dispatch calls Notification.visitAncestor, which performs this walk).

  • The notification invokes NotificationListener._dispatch on 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.