runApp kicks off binding initialization by invoking the
RenderingFlutterBinding.ensureInitialized static method. This calls each binding’s
initInstances method, allowing each to initialize in turn.
This flow is built using mixin chaining: each of the concrete bindings (e.g.,
BaseBinding, the superclass constraint shared by all binding mixins (e.g.,
GestureBinding). Consequently, common methods (like
BaseBinding.initInstances) can be chained together via super invocations. These calls are linearized from left-to-right, starting with the superclass and proceeding sequentially through the mixins; this strict order allows later bindings to depend on earlier ones.
RendererBinding.initInstances creates the
RenderView, passing an initial
ViewConfiguration (describing the size and density of the render surface). It then prepares the first frame (via
RenderView.prepareInitialFrame); this schedules the initial layout and initial paint (via
RenderView.scheduleInitialPaint; the latter creates the root layer, a
TransformLayer). This marks the
RenderView as dirty for layout and painting but does not actually schedule a frame.
This is important since users may wish to begin interacting with the framework (by initializing bindings via
BaseBinding.ensureInitialized) before starting up the app (via
runApp). For instance, a plugin may need to block on a backend service before it can be used.
RendererBinding installs a persistent frame callback to actually draw the frame (
WidgetsBinding overrides the method invoked by this callback to add the build phase). Note that nothing will invoke this callback until the
Window.onDrawFrame handler is installed. This will only happen once a frame has actually been scheduled.
WidgetsBinding.scheduleAttachRootWidget asynchronously creates a
RenderObjectWidget that inserts its child (i.e., the app’s root widget) into the provided container (i.e., the
This asynchronicity is necessary to avoid scheduling two builds back-to-back; while this isn’t strictly invalid, it is inefficient and may trigger asserts in the framework.
If the initial build weren’t asynchronous, it would be possible for intervening events to re-dirty the tree before the warm up frame is scheduled. This would result in a second build (without an intervening layout pass, etc.) when rendering the warm-up frame. By ensuring that the initial build is scheduled asynchronously, there will be no render tree to dirty until the platform is initialized.
For example, the engine may report user settings changes during initialization (via the
_updateUserSettingsData hook). This invokes callbacks on the window (e.g.,
Window.onTextScaleFactorChanged), which are forwarded to all
WidgetsBindingObservers (e.g., via
RendererBinding.handleTextScaleFactorChanged). As an observer,
WidgetsApp reacts to the settings data by requesting a rebuild.
It then invokes
RenderObjectToWidgetAdapter.attachToRenderTree to bootstrap and mount an element to serve as the root of the element hierarchy (
RenderObjectToWidgetElement, i.e., the element corresponding to the adapter). If the element already exists, which will only happen if
runApp is called again, its associated widget is updated (
RenderObjectToWidgetElement._newWidget) and marked as needing to be built.
RenderObjectToWidgetElement.updateChild is invoked when this element is mounted or rebuilt, inflating or updating the child widget (i.e., the app’s root widget) accordingly. Once a descendant
RenderObjectWidget is inflated, the corresponding render object (which must be a
RenderBox) will be inserted into the
RenderObjectToWidgetElement.insertChildRenderObject). The resulting render tree is managed in the usual way going forward.
A reference to this element is stored in
WidgetsBinding.renderViewElement, serving as the root of the element tree. As a
RootRenderObjectElement, this element establishes the
BuildOwner for its descendants.
Finally, after scheduling the first frame (via
SchedulerBinding.instance.ensureVisualUpdate, which will lazily install the frame callbacks),
SchedulerBinding.scheduleWarmUpFrame, manually pumping the rendering pipeline. This gives the initial frame extra time to render as it’s likely the most expensive.
SchedulerBinding.ensureFrameCallbacksRegistered lazily installs frame callbacks as part of
SchedulerBinding.scheduleFrame. Frames are typically scheduled in response to
PipelineOwner.requestVisualUpdate (due to UI needing painting, layout, or a rebuild). Once configured, these callbacks (
Window.onDrawFrame) are invoked once per frame by the engine, running transient and persistent processes, respectively. The latter is generally responsible for ticking animations whereas the former runs the actual building and rendering pipeline.
Once a frame is scheduled and callbacks are registered (via
SchedulerBinding.ensureFrameCallbacksRegistered), the engine begins requesting frames automatically. The frame callbacks invoke handlers in response to these requests. In particular,
SchedulerBinding.drawFrame processes persistent frame callbacks which are used to implement Flutter’s rendering pipeline.
RendererBinding.drawFrame to add the build process to this pipeline.
The rendering pipeline builds widgets, performs layout, updates compositing bits, paints layers, and finally composites everything into a scene which it uploads to the engine (via
RenderView.compositeFrame). Semantics are also updated by this process.
RenderView.compositeFrame retains a reference to the root layer (a
TransformLayer) which it recursively composites using
Layer.buildScene. This iterates through all layers that
needsAddToScene. If true, the layer is freshly composited into the scene. If false, previous invocations of
addToScene will have stored an
Layer.engineLayer, which refers to a retained rendering of the layer subtree. A reference to this retained layer is added to the scene via
SceneBuilder.addRetained. Once the
Scene is built, it is uploaded to the engine via
The framework primarily interacts via the
Window class, a dart interface with hooks into and out of the engine.
The majority of the framework’s flows are driven by frame callbacks invoked by the engine. Other entry points into the framework include gesture handling, platform messaging, and device messaging.
Each binding serves as the singleton root of a subsystem within the framework; in several cases, bindings are layered to augment more fundamental bindings (i.e.,
WidgetsBinding adds support for building to
RendererBinding). All direct framework/engine interaction is managed via the bindings, with the sole exception of the
RenderView, which uploads frames to the engine.
GestureBinding facilitates gesture handling across the framework, maintaining the gesture arena and pointer routing table.
ServicesBinding facilitates message passing between the framework and platform.
SchedulerBinding manages a variety of callbacks (transient, persistent, post-frame, and non-rendering tasks), tracking lifecycle states and scheduler phases. It is also responsible for explicitly scheduling frames when visual updates are needed.
PaintingBinding owns the image cache which manages memory allocated to graphical assets used by the application. It also performs shader warm up to avoid stuttering during drawing (via
PaintingBinding.initInstances). This ensures that the corresponding shaders are compiled at a predictable time.
SemanticsBinding which is intended to manage the semantics and accessibility subsystems (at the moment, this binding mainly tracks accessibility changes emitted by the engine via
RendererBinding implements the rendering pipeline. Additionally, it retains the root of the render tree (i.e., the
RenderView) as well as the
PipelineOwner, an instance that tracks when layout, painting, and compositing need to be re-processed (i.e., have become dirty). The
RendererBinding also responds to events that may affect the application’s rendering (including semantic state, though this will eventually be moved to the
WidgetsBinding augments the renderer binding with support for widget building (i.e., configuring the render tree based on immutable UI descriptions). It also retains the
BuildOwner, an instance that facilitates rebuilding the render tree when configuration changes (e.g., a new widget is substituted). The
WidgetsBinding also responds to events that might require rebuilding related to accessibility and locale changes (though these may be moved to the
SemanticsBinding in the future).
TestWidgetsFlutterBinding supports the widget testing framework.
Element.inflateWidget checks for a global key before inflating a widget. If a global key is found, the corresponding element is returned instead (preserving the corresponding element and rendering subtree).
Global keys are cleaned up when the corresponding element is unmounted (via