RepaintDetector class
Detects expensive repainting using VM Timeline PAINT scopes or debug callback paint counts.
Hybrid Detector — the VM timeline measures the share of UI-thread
wall time spent inside PAINT scopes over each ~1 s window
(excessive_repaint, confirmed confidence). Debug callbacks provide
per-widget likely repaint origins (repaint_debug_<type>, likely
confidence) and an aggregate paint rate fallback
(excessive_repaint_debug, likely confidence).
Data sources accumulate into staging fields; the single _evaluate
method is the ONLY writer of _issues. Called from scanTree (scan
tick) and evaluateNow (timeline tick).
- Inheritance
-
- Object
- BaseDetector
- RepaintDetector
- Mixed-in types
- Annotations
-
- @experimental
Constructors
- RepaintDetector({int paintFrequencyThreshold = 30, double paintTimePercentThreshold = 10, bool captureMode = false, DateTime clock()?})
Properties
- description → String
-
Short description of what this detector checks.
finalinherited
- hashCode → int
-
The hash code for this object.
no setterinherited
-
highlights
→ List<
WidgetHighlight> -
Highlight candidates collected during the last scan.
Empty for detectors that don't produce visual highlights.
no setteroverride
- isEnabled ↔ bool
-
Whether this detector is currently active.
getter/setter pairoverride
-
issues
→ List<
PerformanceIssue> -
Current list of detected issues. Reset each analysis cycle.
no setteroverride
- key → String?
-
Stable identifier for config-driven gating of custom detectors.
finalinherited
- lastObservedPaintPercent → double
-
Share of UI-thread wall time, in percent, spent inside PAINT scopes
in the most recently closed window. Capture-mode operators export
this for sub-threshold legs where no
excessive_repaintissue fires.no setter - lifecycle → DetectorLifecycle
-
Lifecycle classification determining data source requirements.
finalinherited
- name → String
-
Human-readable name of this detector (e.g., "Frame Timing").
finalinherited
- paintFrequencyThreshold → int
-
Per-widget origin rate (repaints per second one instance started)
and debug-aggregate paints per second above which the debug-callback
paths fire; critical above 2×. Does not gate the VM time-share axis.
final
- paintTimePercentThreshold → double
-
Share of UI-thread wall time, in percent, spent inside PAINT scopes
over a ~1 s window above which
excessive_repaintfires. Critical above 3× this value. Default mirrorsDetectorThresholds.paintTimePercentThreshold.final - peakObservedPaintPercent → double
-
Highest paint-time share seen across naturally closed ~1 s windows
since the last resetCaptureState. Use for capture-mode magnitude
export so the value matches the audit gate's
'max'axis reduction. Returns 0 if no window has closed since reset.no setter - pendingDebugSnapshotForTest → DebugSnapshot?
-
Staged debug snapshot not yet consumed by a scan (for testing).
no setter
- requiresTreeScan → bool
-
Whether this detector scans the widget/render tree.
no setterinherited
- requiresVm → bool
-
Whether this detector needs VM service data to function.
DetectorLifecycle.runtime detectors benefit from VM data but don't require it.
no setterinherited
- runtimeType → Type
-
A representation of the runtime type of the object.
no setterinherited
- type → DetectorType
-
The detector type identifier used for configuration.
finalinherited
- validationMetadata → DetectorMetadata
-
Metadata for this detector. Must be non-null on shipping detectors —
the audit test gates this.
no setteroverride
- vmConnected ↔ bool
-
Current VM connectivity — set by the controller.
getter/setter pairoverride-setter
Methods
-
afterElement(
Element element) → void -
Called after an element's children have all been visited.
inherited
-
checkElement(
Element element) → void -
Check a single element during the unified tree walk.
override
-
discardDebugEvidence(
) → void - Drops the held debug types, for a scan that could not run: the counts it drained are gone, and the types held from earlier scans belong to a page that may no longer be shown.
-
dispose(
) → void -
Dispose of any resources held by this detector.
override
-
evaluateNow(
) → void -
Triggers issue evaluation using whatever data has been staged.
override
-
finalizeScan(
) → void -
Finalise the scan: process accumulated data and create issues.
override
-
flushPaintEvaluation(
) → void -
Forces an immediate close of the in-flight VM window so capture
tooling can read lastObservedPaintPercent without waiting for the
window timer. The partial window's share is its paint time over its
own elapsed time. Idempotent — re-running with no new paint time
preserves the prior values. Pure observable refresh; does not emit
issues (issue emission is owned by
_evaluateVmData, reached via_evaluate, which only runs from the scan pipeline). -
markRouteEpoch(
) → void - Starts over at a route change or hot reload: drops the held debug types and VM issue and restarts the open VM window, so evidence from the previous screen is neither shown nor mixed into the next window.
-
noSuchMethod(
Invocation invocation) → dynamic -
Invoked when a nonexistent method or property is accessed.
inherited
-
notifyWalkCompleted(
) → void -
Called when the tree walk completed without exceptions.
inherited
-
prepareScan(
BuildContext context) → void -
Prepare for a new scan cycle. Called once before the unified tree walk.
override
-
processFrame(
FrameStats frame) → void -
Process one presented frame from
FrameTiming.inherited -
processTimelineData(
ParsedTimelineData data) → void -
Process VM timeline data for PAINT scope time.
override
-
resetCaptureState(
) → void -
Clears all per-leg accumulator state so capture screens can
re-enter a fresh below/at/above leg without leakage from the
prior leg's paint time, debug snapshot, or pending issues, and
restarts the window clock.
_vmConnectedis owned by the controller and intentionally left untouched. -
scanTree(
BuildContext context) → void -
Scan the widget/render tree for issues.
inherited
-
toString(
) → String -
A string representation of this object.
inherited
-
updateDebugSnapshot(
DebugSnapshot snapshot) → void -
Called with debug callback data when available.
override
Operators
-
operator ==(
Object other) → bool -
The equality operator.
inherited
Constants
- debugCriticalMultiplier → const int
- A per-widget origin rate above this many times paintFrequencyThreshold is critical.
- vmExitFactor → const double
-
Fraction of paintTimePercentThreshold the paint share must stay
under for two windows before a shown
excessive_repaintclears.