elements.md

Elements

What are elements?

• The element tree is anchored in the WidgetsBinding and established via runApp / RenderObjectToWidgetAdapter.
• Widget instances are immutable representations of UI configuration data that are “inflated” into Element instances (via Element.inflateWidget). Elements therefore serve as widgets' mutable counterparts and are responsible for modeling the relationship between widgets (e.g., the widget tree), storing state and inherited relationships, and participating in the build process, etc.
• All elements are associated with a BuildOwner singleton. This instance is responsible for tracking dirty elements and, during WidgetsBinding.drawFrame, re-building the element tree as needed. This process triggers several lifecycle events (e.g., initState, didChangeDependencies, didUpdateWidget).
• Elements are assembled into a tree (via Element.mount and Element.unmount). Whereas these operations are permanent, elements may also be temporarily removed and restored (via Element.deactivate and Element.activate, respectively).
  • Elements transition through several lifecycle states (_ElementLifecycle) in response to the following methods: Element.mount (initial to active, Element.activate is only called when reactivating), Element.deactivate (active to inactive, can be reactivated via Element.activate), then finally Element.unmount (inactive to defunct).
  • Note that deactivating or unmounting an element is a recursive process, generally facilitated by the build owner's inactive elements list (BuildOwner._inactiveElements). All descendant elements are affected (via_InactiveElements._deactivateRecursively and_InactiveElements._unmount).
• Elements are attached (i.e., mounted) to the element tree when they're first created. They may then be updated (via Element.update) multiple times as they become dirty (e.g., due to widget changes or notifications). An element may also be deactivated; this removes any associated render objects from the render tree and adds the element to the build owner's list of inactive nodes. This list (_InactiveElements) automatically deactivates all nodes in the affected subtree and clears all dependencies (e.g., from InheritedElement).
  • Parents are generally responsible for deactivating their children (via Element.deactivateChild). Deactivation temporarily removes the element (and any associated render objects) from the element tree; unmounting makes this change permanent.
  • An element may be reactivated within the same frame (e.g., due to tree grafting), otherwise the element will be permanently unmounted by the build owner (via BuildOwner.finalizeTree which calls Element.unmount).
  • If the element is reactivated, the subtree will be restored and marked dirty, causing it to be rebuilt (re-adopting any render objects which were previously dropped).
• Element.updateChild is used to update a child element when its configuration (i.e., widget) changes. If the new widget isn't compatible with the old one (e.g., doesn't exist, has a different type, or has a different key), a fresh element is inflated (via Element.inflateWidget). Once an element is retrieved or inflated, the new configuration is applied via Element.update; this might alter an associated render object, notify dependents of a state change, or mutate the element itself.
  • When an element is re-inflated, it has no access to any existing children; that is, children associated with the old element aren't passed to the new element. Thus, all descendants need to be re-inflated, too (there are no old elements to synchronize).
  • Global keys are one exception: any children associated with a global key can be restored without being re-inflated.

What are the element building blocks?

• Elements are mainly broken down into RenderObjectElement and ComponentElement. RenderObjectElements are responsible for configuring render objects and keeping the render object tree and widget tree in sync. ComponentElements don't directly manage render objects but instead produce intermediate nodes via mechanisms like Widget.build. Both processes are driven by Element.performRebuild which is itself triggered by BuildOwner.buildScope. The latter is run as part of the build process every time the engine requests a frame.
• ProxyElement forms a third category of elements that wrap a subtree of elements (and are configured by ProxyWidget). These generally augment the subtree in some way (e.g., InheritedElement injects heritable state). Proxy elements use notifications to inform subscribers when its configuration changes (ProxyElement.update invokes ProxyElement.updated which, by default, calls ProxyElement.notifyClients). Subclasses manage subscribers in an implementation-specific way.
  • ParentDataElement updates the parent data of all closest descendant render objects (via ParentDataElement._applyParentData, which is called by ParentDataElement.notifyClients).
  • InheritedElement notifies a set of dependents whenever its configuration is changed (i.e., when InheritedElement.update is invoked).InheritedElement._dependants is implemented as a mapping since each dependent can provide an arbitrary object to use when determining whether an update is applicable. Dependents are notified by invoking Element.didChangeDependencies.

How is the render tree managed by RenderObjectElement?

• Render object elements are responsible for managing an associated render object. RenderObjectElement.update applies updates to this render object to match a new configuration (i.e., widget).
  • The render object is created (via RenderObjectWidget.createRenderObject) when its element is first mounted. The render object is retained throughout the life of the element, even when the element is deactivated (and the render object is detached).
    • A new render object is created if an element is inflated and mounted (e.g., because a new widget couldn't update the old one); at this point, the old render object is destroyed. A slot token is used during this process so the render object can attach and detach itself from the render tree (which can vary from the element tree).
  • The render object is attached to the render tree when its element is first mounted (via RenderObjectElement.attachRenderObject). If the element is later deactivated (due to tree grafting), it will be re-attached when the graft is completed (via RenderObjectElement.inflateWidget, which includes special logic for handling grafting by global key).
  • The render object is updated (via RenderObjectWidget.updateRenderObject) when its element is updated (via Element.update) or rebuilt (via Element.rebuild).
  • The render object is detached from its parent (via RenderObjectElement.detachRenderObject) when the element is deactivated. This is generally managed by the parent (via Element.deactivateChild) and occurs when children are explicitly removed or reparented due to tree grafting. Deactivating a child calls Element.detachRenderObject which recursively processes descendants until reaching the nearest render object element boundary. RenderObjectElement overrides this method to detach its render object, cutting off the recursive walk.
• Render objects may have children. However, there may be several intermediate nodes (i.e., component elements) between its RenderObjectElement and the elements associated with its children. That is, the element tree typically has many more nodes than the render tree.
  • Slot tokens are passed down the element tree so that these RenderObjectElement nodes can interact with their render object's parent (viaRenderObjectElement.insertChildRenderObject, RenderObjectElement.moveChildRenderObject, RenderObjectElement.removeChildRenderObject). Tokens are interpreted in an implementation-specific manner by the ancestor RenderObjectElement to distinguish render object children.
• Elements generally use their widget's children as the source of truth (e.g., MultiChildRenderObjectWidget.children). When the element is first mounted, each child is inflated and stored in an internal list (e.g., MultiChildRenderObjectElement._children); this list is later used when updating the element.
• Elements can be grafted from one part of the tree to another within a single frame. Such elements are “forgotten” by their parents (via RenderObjectElement.forgetChild) so that they are excluding from iteration and updating. The old parent removes the child when the element is added to its new parent (this happens during inflation, since grafting requires that the widget tree be updated, too).
• Elements are responsible for updating any children. To avoid unnecessarily inflation (and potential loss of state), the new and old child lists are synchronized using a linear reconciliation scheme optimized for empty lists, matched lists, and lists with one mismatched region:

1. The leading elements and widgets are matched by key and updated.
2. The trailing elements and widgets are matched by key with updates queued (update order is significant).
3. A mismatched region is identified in the old and new lists.
4. Old elements are indexed by key.
5. Old elements without a key are updated with null (deleted).
6. The index is consulted for each new, mismatched widget.
7. New widgets with keys in the index update together (re-use).
8. New widgets without matches are updated with null (inflated).
9. Remaining elements in the index are updated with null (deleted).

What are the render object element building blocks?

• LeafRenderObjectElement, SingleChildRenderObjectElement, and MultiChildRenderObjectElement provide support for common use cases and correspond to the similarly named widget helpers (LeafRenderObjectWidget, SingleChildRenderObjectWidget, MultiChildRenderObjectWidget)
  • The multi-child and single-child variants pair with ContainerRenderObjectMixin and RenderObjectWithChildMixin in the render tree.
• These use the previous child (or null) as the slot identifier; this is convenient since ContainerRenderObjectMixin manages children using a linked list.

How are elements managed by ComponentElement?

• ComponentElement composes other elements. Rather than managing a render object itself, it produces descendant elements that manage their own render objects through building.
• Building is an alternative to storing a static list of children. Components build a single child dynamically whenever they become dirty.
• This process is driven by Element.rebuild which is invoked by the build owner when an element is marked dirty (via BuildOwner.scheduleBuildFor). Component elements also rebuild when they're first mounted (via ComponentElement._firstBuild) and when their widget changes (via ComponentElement.update). For StatefulElement, a rebuild may be scheduled spontaneously via State.setState. In all cases, lifecycle methods are invoked in response to changes to the element tree (for example, StatefulElement.update will invoke State.didUpdateWidget).
• The actual implementation is supplied by Element.performRebuild. Component elements overrideElement.performRebuild to invoke ComponentElement.build whereas render object elements update their render object via RenderObjectWidget.updateRenderObject.
• ComponentElement.build provides a hook for producing intermediate nodes in the element tree. StatelessElement.build invokes the widget’s build method, whereas StatefulElement.build invokes the state’s build method. ProxyElement simply returns its widget's child.
• Note that if a component element rebuilds, the child element and the newly built widget will still be synchronized (via Element.updateChild). If the widget is compatible with the existing element, it'll be updated instead of re-inflated. This allows existing render objects to be mutated instead of being recreated. Depending on the mutation, this might involve any combination of layout, painting, and compositing.
• Reassembly (e.g., Element.reassemble) marks the element as being dirty; most subclasses do not override this behavior. This causes the element tree to be rebuilt during the next frame. Render object elements update their render objects in response to Element.performRebuild and therefore also benefit from hot reload.

How does building work?

• Only widgets associated with ComponentElement (e.g., StatelessWidget, StatefulWidget, ProxyWidget) participate in the build process; RenderObjectWidget subclasses, generally associated with RenderObjectElements, do not; these simply update their render object when building. ComponentElement instances only have a single child, typically that returned by their widget’s build method (ProxyElement returns the child attached to its widget)..
• When the element tree is first anchored to the render tree (via RenderObjectToWidgetAdapter.attachToRenderTree), the RenderObjectToWidgetElement (a RootRenderObjectElement) assigns a BuildOwner for the element tree. The BuildOwner is responsible for tracking dirty elements (BuildOwner.scheduleBuildFor), establishing build scopes wherein elements can be rebuilt / descendant elements can be marked dirty (BuildOwner.buildScope / BuildOwner.scheduleBuildFor), and unmounting inactive elements at the end of a frame (BuildOwner.finalizeTree). It also maintains a reference to the root FocusManager and triggers reassembly after a hot reload.
• When a ComponentElement is mounted (e.g., after being inflated), an initial build is performed immediately (via ComponentElement._firstBuild, which calls ComponentElement.rebuild).
• Later, elements can be marked dirty using Element.markNeedsBuild. This is invoked any time the UI might need to be updated implicitly (or explicitly, in response to State.setState). This method adds the element to the dirty list and, via BuildOwner.onBuildScheduled, schedules a frame via SchedulerBinding.ensureVisualUpdate. The actual build will take place when the next frame is processed.
  • Some operations trigger a rebuild directly (i.e., without marking the tree dirty first). These include ProxyElement.update, StatelessElement.update, StatefulElement.update, and ComponentElement.mount. In these cases, the intention is to update the element tree immediately.
  • Other operations schedule a build to occur during the next frame. These include State.setState, Element.reassemble, Element.didChangeDependencies, StatefulElement.activate, etc.
  • Proxy elements use notifications to indicate when underlying data has changed. In the case of InheritedElement, each dependent's Element.didChangeDependencies is invoked which, by default, marks that element as being dirty. This causes the descendant to rebuild when any of its dependencies change.
• Once per frame, BuildOwner.buildScope will walk the element tree in depth-first order, only considering those nodes that have been marked dirty. By locking the tree and iterating in depth first order, any nodes that become dirty while rebuilding must necessarily be lower in the tree; this is because building is a unidirectional process -- a child cannot mark its parent as being dirty. Thus, it is not possible for build cycles to be introduced and it is not possible for elements that have been marked clean to become dirty again.
• As the build progresses, ComponentElement.performRebuild delegates to the ComponentElement.build method to produce a new child widget for each dirty element. Next, Element.updateChild is invoked to efficiently reuse or recreate an element for the child. Crucially, if the child’s widget hasn’t changed, the build is immediately cut off. Note that if the child widget did change and Element.update is needed, that child will itself be marked dirty, and the build will continue down the tree.
• Each Element maintains a map of all InheritedElement ancestors at its location. Thus, accessing dependencies from the build process is a constant time operation.
• If Element.updateChild invokes Element.deactivateChild because a child is removed or moved to another part of the tree, BuildOwner.finalizeTree will unmount the element if it isn’t reintegrated by the end of the frame.

How does element inheritance work?

• InheritedElement provides an efficient mechanism for publishing heritable state to a subset of the element tree. This mechanism depends on support provided by Element itself.
• All elements maintain a set of dependencies (Element._dependencies, e.g., elements higher in the tree that fill a dependency) and a mapping of all InheritedElement instances between this element and the root (Element._inheritedWidgets). The dependencies set is mainly tracked for debugging purposes .
• The map of inherited elements serves as an optimization to avoid repeatedly walking the tree. Each dependency is uniquely identified by its instantiated type; multiple dependencies sharing a type shadow one another (in this case, shadowed dependencies may still be be retrieved by walking the tree).
  • This mapping is maintained by Element._updateInheritance. By default, elements copy the mapping from their parents. However, InheritedElement instances override this method to insert themselves into the mapping (the mapping is always copied so that different branches of the tree are independent).
  • This mapping is built on the fly (via Element._updateInheritance) when elements are first mounted (via Element.mount) or are reactivated (via Element.activate). The mapping is cleared when elements are deactivated (via Element.deactivate); the element is removed from each of its dependency's dependent lists (InheritedElement._dependents). As a result, it's usually not necessary to manually walk an element's ancestors.
• Inherited relationships are established via Element.dependOnInherited (Element.inheritFromElement is a simple wrapper). In general, the inherited ancestor should be available in Element._inheritedWidgets. This process causes the inherited element to add the dependent element to its list of dependencies (via InheritedElement.updateDependencies).
  • When an element is reactivating (e.g., after grafting), it is notified of dependency changes if it had existing or unsatisfied dependencies (e.g., a dependency was added but a corresponding InheritedElement wasn't found in Element._inheritedWidgets).
• Elements are notified when their dependencies change via Element.didChangeDependencies. By default, this method marks the element as being dirty.