Element class abstract

An instantiation of a Widget at a particular location in the tree.

Widgets describe how to configure a subtree but the same widget can be used to configure multiple subtrees simultaneously because widgets are immutable. An Element represents the use of a widget to configure a specific location in the tree. Over time, the widget associated with a given element can change, for example, if the parent widget rebuilds and creates a new widget for this location.

Elements form a tree. Most elements have a unique child, but some widgets (e.g., subclasses of RenderObjectElement) can have multiple children.

Elements have the following lifecycle:

  • The framework creates an element by calling Widget.createElement on the widget that will be used as the element's initial configuration.
  • The framework calls mount to add the newly created element to the tree at a given slot in a given parent. The mount method is responsible for inflating any child widgets and calling attachRenderObject as necessary to attach any associated render objects to the render tree.
  • At this point, the element is considered "active" and might appear on screen.
  • At some point, the parent might decide to change the widget used to configure this element, for example because the parent rebuilt with new state. When this happens, the framework will call update with the new widget. The new widget will always have the same runtimeType and key as old widget. If the parent wishes to change the runtimeType or key of the widget at this location in the tree, it can do so by unmounting this element and inflating the new widget at this location.
  • At some point, an ancestor might decide to remove this element (or an intermediate ancestor) from the tree, which the ancestor does by calling deactivateChild on itself. Deactivating the intermediate ancestor will remove that element's render object from the render tree and add this element to the owner's list of inactive elements, causing the framework to call deactivate on this element.
  • At this point, the element is considered "inactive" and will not appear on screen. An element can remain in the inactive state only until the end of the current animation frame. At the end of the animation frame, any elements that are still inactive will be unmounted.
  • If the element gets reincorporated into the tree (e.g., because it or one of its ancestors has a global key that is reused), the framework will remove the element from the owner's list of inactive elements, call activate on the element, and reattach the element's render object to the render tree. (At this point, the element is again considered "active" and might appear on screen.)
  • If the element does not get reincorporated into the tree by the end of the current animation frame, the framework will call unmount on the element.
  • At this point, the element is considered "defunct" and will not be incorporated into the tree in the future.
Inheritance
Implemented types
Implementers

Constructors

Element(Widget widget)
Creates an element that uses the given widget as its configuration.

Properties

debugDoingBuild bool
Whether the widget is currently updating the widget or render tree.
no setterinherited
debugIsActive bool
Returns true if the Element is active.
no setter
debugIsDefunct bool
Returns true if the Element is defunct.
no setter
depth int
An integer that is guaranteed to be greater than the parent's, if any. The element at the root of the tree must have a depth greater than 0.
no setter
dirty bool
Returns true if the element has been marked as needing rebuilding.
no setter
hashCode int
The hash code for this object.
no setterinherited
mounted bool
Whether the Widget this context is associated with is currently mounted in the widget tree.
no setteroverride
owner BuildOwner?
The object that manages the lifecycle of this element.
no setteroverride
renderObject RenderObject?
The render object at (or below) this location in the tree.
no setter
renderObjectAttachingChild Element?
Returns the child of this Element that will insert a RenderObject into an ancestor of this Element to construct the render tree.
no setter
runtimeType Type
A representation of the runtime type of the object.
no setterinherited
size Size?
The size of the RenderBox returned by findRenderObject.
no setteroverride
slot Object?
Information set by parent to define where this child fits in its parent's child list.
no setter
widget Widget
The configuration for this element.
no setteroverride

Methods

activate() → void
Transition from the "inactive" to the "active" lifecycle state.
attachNotificationTree() → void
Called in Element.mount and Element.activate to register this element in the notification tree.
attachRenderObject(Object? newSlot) → void
Add renderObject to the render tree at the location specified by newSlot.
deactivate() → void
Transition from the "active" to the "inactive" lifecycle state.
deactivateChild(Element child) → void
Move the given element to the list of inactive elements and detach its render object from the render tree.
debugDeactivated() → void
Called, in debug mode, after children have been deactivated (see deactivate).
debugDescribeChildren() List<DiagnosticsNode>
Returns a list of DiagnosticsNode objects describing this node's children.
override
debugExpectsRenderObjectForSlot(Object? slot) bool
Whether the child in the provided slot (or one of its descendants) must insert a RenderObject into its ancestor RenderObjectElement by calling RenderObjectElement.insertRenderObjectChild on it.
debugFillProperties(DiagnosticPropertiesBuilder properties) → void
Add additional properties associated with the node.
override
debugGetCreatorChain(int limit) String
Returns a description of what caused this element to be created.
debugGetDiagnosticChain() List<Element>
Returns the parent chain from this element back to the root of the tree.
debugVisitOnstageChildren(ElementVisitor visitor) → void
Calls the argument for each child considered onstage.
dependOnInheritedElement(InheritedElement ancestor, {Object? aspect}) InheritedWidget
Registers this build context with ancestor such that when ancestor's widget changes this build context is rebuilt.
override
dependOnInheritedWidgetOfExactType<T extends InheritedWidget>({Object? aspect}) → T?
Returns the nearest widget of the given type T and creates a dependency on it, or null if no appropriate widget is found.
override
describeElement(String name, {DiagnosticsTreeStyle style = DiagnosticsTreeStyle.errorProperty}) DiagnosticsNode
Returns a description of the Element associated with the current build context.
override
describeMissingAncestor({required Type expectedAncestorType}) List<DiagnosticsNode>
Adds a description of a specific type of widget missing from the current build context's ancestry tree.
override
describeOwnershipChain(String name) DiagnosticsNode
Adds a description of the ownership chain from a specific Element to the error report.
override
describeWidget(String name, {DiagnosticsTreeStyle style = DiagnosticsTreeStyle.errorProperty}) DiagnosticsNode
Returns a description of the Widget associated with the current build context.
override
detachRenderObject() → void
Remove renderObject from the render tree.
didChangeDependencies() → void
Called when a dependency of this element changes.
dispatchNotification(Notification notification) → void
Start bubbling this notification at the given build context.
override
doesDependOnInheritedElement(InheritedElement ancestor) bool
Returns true if dependOnInheritedElement was previously called with ancestor.
findAncestorRenderObjectOfType<T extends RenderObject>() → T?
Returns the RenderObject object of the nearest ancestor RenderObjectWidget widget that is an instance of the given type T.
override
findAncestorStateOfType<T extends State<StatefulWidget>>() → T?
Returns the State object of the nearest ancestor StatefulWidget widget that is an instance of the given type T.
override
findAncestorWidgetOfExactType<T extends Widget>() → T?
Returns the nearest ancestor widget of the given type T, which must be the type of a concrete Widget subclass.
override
findRenderObject() RenderObject?
The current RenderObject for the widget. If the widget is a RenderObjectWidget, this is the render object that the widget created for itself. Otherwise, it is the render object of the first descendant RenderObjectWidget.
override
findRootAncestorStateOfType<T extends State<StatefulWidget>>() → T?
Returns the State object of the furthest ancestor StatefulWidget widget that is an instance of the given type T.
override
forgetChild(Element child) → void
Remove the given child from the element's child list, in preparation for the child being reused elsewhere in the element tree.
getElementForInheritedWidgetOfExactType<T extends InheritedWidget>() InheritedElement?
Obtains the element corresponding to the nearest widget of the given type T, which must be the type of a concrete InheritedWidget subclass.
override
getInheritedWidgetOfExactType<T extends InheritedWidget>() → T?
Returns the nearest widget of the given InheritedWidget subclass T or null if an appropriate ancestor is not found.
override
inflateWidget(Widget newWidget, Object? newSlot) Element
Create an element for the given widget and add it as a child of this element in the given slot.
markNeedsBuild() → void
Marks the element as dirty and adds it to the global list of widgets to rebuild in the next frame.
mount(Element? parent, Object? newSlot) → void
Add this element to the tree in the given slot of the given parent.
noSuchMethod(Invocation invocation) → dynamic
Invoked when a nonexistent method or property is accessed.
inherited
performRebuild() → void
Cause the widget to update itself.
reassemble() → void
Called whenever the application is reassembled during debugging, for example during hot reload.
rebuild({bool force = false}) → void
Cause the widget to update itself. In debug builds, also verify various invariants.
toDiagnosticsNode({String? name, DiagnosticsTreeStyle? style}) DiagnosticsNode
Returns a debug representation of the object that is used by debugging tools and by DiagnosticsNode.toStringDeep.
override
toString({DiagnosticLevel minLevel = DiagnosticLevel.info}) String
A string representation of this object.
inherited
toStringDeep({String prefixLineOne = '', String? prefixOtherLines, DiagnosticLevel minLevel = DiagnosticLevel.debug}) String
Returns a string representation of this node and its descendants.
inherited
toStringShallow({String joiner = ', ', DiagnosticLevel minLevel = DiagnosticLevel.debug}) String
Returns a one-line detailed description of the object.
inherited
toStringShort() String
A short, textual description of this element.
override
unmount() → void
Transition from the "inactive" to the "defunct" lifecycle state.
update(covariant Widget newWidget) → void
Change the widget used to configure this element.
updateChild(Element? child, Widget? newWidget, Object? newSlot) Element?
Update the given child with the given new configuration.
updateChildren(List<Element> oldChildren, List<Widget> newWidgets, {Set<Element>? forgottenChildren, List<Object?>? slots}) List<Element>
Updates the children of this element to use new widgets.
updateSlot(Object? newSlot) → void
Called by updateSlotForChild when the framework needs to change the slot that this Element occupies in its ancestor.
updateSlotForChild(Element child, Object? newSlot) → void
Change the slot that the given child occupies in its parent.
visitAncestorElements(ConditionalElementVisitor visitor) → void
Walks the ancestor chain, starting with the parent of this build context's widget, invoking the argument for each ancestor.
override
visitChildElements(ElementVisitor visitor) → void
Wrapper around visitChildren for BuildContext.
override
visitChildren(ElementVisitor visitor) → void
Calls the argument for each child. Must be overridden by subclasses that support having children.

Operators

operator ==(Object other) bool
Compare two widgets for equality.
override

Static Methods

describeElements(String name, Iterable<Element> elements) DiagnosticsNode
Returns a list of Elements from the current build context to the error report.