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
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_repaint issue 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_repaint fires. Critical above 3× this value. Default mirrors DetectorThresholds.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. _vmConnected is 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_repaint clears.