RepaintBoundary class
A widget that creates a separate display list for its child.
This widget creates a separate display list for its child, which can improve performance if the subtree repaints at different times than the surrounding parts of the tree.
This is useful since RenderObject.paint may be triggered even if its associated Widget instances did not change or rebuild. A RenderObject will repaint whenever any RenderObject that shares the same Layer is marked as being dirty and needing paint (see RenderObject.markNeedsPaint), such as when an ancestor scrolls or when an ancestor or descendant animates.
Containing RenderObject.paint to parts of the render subtree that are actually visually changing using RepaintBoundary explicitly or implicitly is therefore critical to minimizing redundant work and improving the app's performance.
When a RenderObject is flagged as needing to paint via RenderObject.markNeedsPaint, the nearest ancestor RenderObject with RenderObject.isRepaintBoundary, up to possibly the root of the application, is requested to repaint. That nearest ancestor's RenderObject.paint method will cause all of its descendant RenderObjects to repaint in the same layer.
RepaintBoundary is therefore used, both while propagating the
markNeedsPaint
flag up the render tree and while traversing down the
render tree via RenderObject.paintChild
, to strategically contain repaints
to the render subtree that visually changed for performance. This is done
because the RepaintBoundary widget creates a RenderObject that always
has a Layer, decoupling ancestor render objects from the descendant
render objects.
RepaintBoundary has the further side-effect of possibly hinting to the engine that it should further optimize animation performance if the render subtree behind the RepaintBoundary is sufficiently complex and is static while the surrounding tree changes frequently. In those cases, the engine may choose to pay a one time cost of rasterizing and caching the pixel values of the subtree for faster future GPU re-rendering speed.
Several framework widgets insert RepaintBoundary widgets to mark natural separation points in applications. For instance, contents in Material Design drawers typically don't change while the drawer opens and closes, so repaints are automatically contained to regions inside or outside the drawer when using the Drawer widget during transitions.
See also:
- debugRepaintRainbowEnabled, a debugging flag to help visually monitor render tree repaints in a running app.
- debugProfilePaintsEnabled, a debugging flag to show render tree repaints in the observatory's timeline view.
- Inheritance
Constructors
- RepaintBoundary({Key key, Widget child })
-
Creates a widget that isolates repaints.
const
- RepaintBoundary.wrap(Widget child, int childIndex)
-
Wraps the given child in a RepaintBoundary. [...]
factory
Properties
- child → Widget
-
The widget below this widget in the tree. [...]
final, inherited
- hashCode → int
-
The hash code for this object. [...]
read-only, inherited
- key → Key
-
Controls how one widget replaces another widget in the tree. [...]
final, inherited
- runtimeType → Type
-
A representation of the runtime type of the object.
read-only, inherited
Methods
-
createRenderObject(
BuildContext context) → RenderRepaintBoundary -
Creates an instance of the RenderObject class that this
RenderObjectWidget represents, using the configuration described by this
RenderObjectWidget. [...]
override
-
createElement(
) → SingleChildRenderObjectElement -
RenderObjectWidgets always inflate to a RenderObjectElement subclass.
inherited
-
debugDescribeChildren(
) → List< DiagnosticsNode> -
Returns a list of DiagnosticsNode objects describing this node's
children. [...]
@protected, inherited
-
debugFillProperties(
DiagnosticPropertiesBuilder properties) → void -
Add additional properties associated with the node. [...]
inherited
-
didUnmountRenderObject(
covariant RenderObject renderObject) → void -
A render object previously associated with this widget has been removed
from the tree. The given RenderObject will be of the same type as
returned by this object's createRenderObject.
@protected, inherited
-
noSuchMethod(
Invocation invocation) → dynamic -
Invoked when a non-existent method or property is accessed. [...]
inherited
-
toDiagnosticsNode(
{String name, DiagnosticsTreeStyle style }) → DiagnosticsNode -
Returns a debug representation of the object that is used by debugging
tools and by toStringDeep. [...]
inherited
-
toString(
{DiagnosticLevel minLevel: DiagnosticLevel.debug }) → String -
Returns 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 widget.
inherited
-
updateRenderObject(
BuildContext context, covariant RenderObject renderObject) → void -
Copies the configuration described by this RenderObjectWidget to the
given RenderObject, which will be of the same type as returned by this
object's createRenderObject. [...]
@protected, inherited
Operators
-
operator ==(
dynamic other) → bool -
The equality operator. [...]
inherited
Static Methods
-
wrapAll(
List< Widget> widgets) → List< RepaintBoundary> - Wraps each of the given children in RepaintBoundarys. [...]