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, 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 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.
Implements
  • BuildContext

Constructors

Element(Widget widget)

Creates an element that uses the given widget as its configuration.

Properties

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.

read-only
dirty → bool

Returns true if the element has been marked as needing rebuilding.

read-only
owner → BuildOwner

The object that manages the lifecycle of this element.

read-only
renderObject → RenderObject

The render object at (or below) this location in the tree.

read-only
size → Size

read-only
slot → dynamic

Information set by parent to define where this child fits in its parent's child list.

read-only
widget → Widget

The configuration for this element.

read-only
hashCode → int

Get a hash code for this object.

read-only, inherited
runtimeType → Type

A representation of the runtime type of the object.

read-only, inherited

Operators

operator ==(other) → bool

The equality operator.

inherited

Methods

activate() → void

Transition from the "inactive" to the "active" lifecycle state.

ancestorInheritedElementForWidgetOfExactType(Type targetType) → InheritedElement

Obtains the element corresponding to the nearest widget of the given type, which must be the type of a concrete InheritedWidget subclass.

ancestorRenderObjectOfType(TypeMatcher matcher) → RenderObject

Returns the RenderObject object of the nearest ancestor RenderObjectWidget widget that matches the given TypeMatcher.

ancestorStateOfType(TypeMatcher matcher) → State

Returns the State object of the nearest ancestor StatefulWidget widget that matches the given TypeMatcher.

ancestorWidgetOfExactType(Type targetType) → Widget

Returns the nearest ancestor widget of the given type, which must be the type of a concrete Widget subclass.

attachRenderObject(newSlot) → void

Add renderObject to the render tree at the location specified by slot.

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).

debugFillDescription(List<String> description) → void

Add additional information to the given description for use by toString.

debugGetCreatorChain(int limit) → String

Returns a description of what caused this element to be created.

dependenciesChanged() → void

Called when a dependency of this element changes.

detachRenderObject() → void

Remove renderObject from the render tree.

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.

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.

inflateWidget(Widget newWidget, newSlot) → Element

Create an element for the given widget and add it as a child of this element in the given slot.

inheritFromWidgetOfExactType(Type targetType) → InheritedWidget

Obtains the nearest widget of the given type, which must be the type of a concrete InheritedWidget subclass, and registers this build context with that widget such that when that widget changes (or a new widget of that type is introduced, or the widget goes away), this build context is rebuilt so that it can obtain new values from that widget.

mount(Element parent, newSlot) → void

Add this element to the tree in the given slot of the given parent.

toString() → String

Returns a string representation of this object.

toStringDeep([String prefixLineOne = '', String prefixOtherLines = '' ]) → String

A detailed, textual description of this element, includings its children.

toStringShort() → String

A short, textual description of this element.

unmount() → void

Transition from the "inactive" to the "defunct" lifecycle state.

update(Widget newWidget) → void

Change the widget used to configure this element.

updateChild(Element child, Widget newWidget, newSlot) → Element

Update the given child with the given new configuration.

updateSlotForChild(Element child, newSlot) → void

Change the slot that the given child occupies in its parent.

visitAncestorElements(bool visitor(Element element)) → void

Walks the ancestor chain, starting with the parent of this build context's widget, invoking the argument for each ancestor. The callback is given a reference to the ancestor widget's corresponding Element object. The walk stops when it reaches the root widget or when the callback returns false. The callback must not return null.

visitChildElements(ElementVisitor visitor) → void

Wrapper around visitChildren for BuildContext.

visitChildren(ElementVisitor visitor) → void

Calls the argument for each child. Must be overridden by subclasses that support having children.

visitChildrenForSemantics(ElementVisitor visitor) → void

Calls the argument for each child that is relevant for semantics. By default, defers to visitChildren. Classes like Offstage override this to hide their children.

noSuchMethod(Invocation invocation) → dynamic

Invoked when a non-existent method or property is accessed.

inherited