SpotlightOverlay class

Onboarding/tutorial coach-mark: dims the whole screen except a highlighted "hole" cut around a target widget's actual on-screen bounds, plus a guidance callout with a dismiss button.

An in-tree overlay like NeonDialog.overlay — not a route — so it works the same whether the caller sits above a plain screen or a full-screen Flame GameWidget (see CLAUDE.md's "Dialog pattern"). Mount it as a Positioned.fill sibling of the already-built target inside a Stack, same as RewardPopup/ConfettiOverlay are used in the demo screen — the target must already be laid out (its GlobalKey attached to a mounted widget) for the hole position to be correct.

Inheritance

Constructors

SpotlightOverlay({Key? key, required GlobalKey<State<StatefulWidget>> targetKey, required String message, required VoidCallback onDismiss, String? title, String? buttonLabel, Color? color, double holeRadius = 16, double holePadding = 8, Color? dimColor, String? stepIndicator, VoidCallback? onSkip, String? skipLabel})
const

Properties

buttonLabel → String?
Defaults to 'tutorial_got_it'.tr (BUG-94) — nullable because a locale-resolved string is no longer a compile-time constant.
final
color → Color?
Defaults to NeonTheme.purple — nullable because a NeonTheme color field is no longer a compile-time constant.
final
dimColor → Color?
Defaults to a black scrim if omitted.
final
hashCode → int
The hash code for this object.
no setterinherited
holePadding → double
Extra margin added around the target's actual bounds before cutting the hole, so the highlight isn't a pixel-tight outline.
final
holeRadius → double
Corner radius of the cut-out hole.
final
key → Key?
Controls how one widget replaces another widget in the tree.
finalinherited
message → String
final
onDismiss → VoidCallback
final
onSkip → VoidCallback?
When non-null, shows a secondary "skip" action next to buttonLabel that calls this instead of onDismiss — lets the player back out of a multi-step sequence early instead of only ever advancing one step at a time (ENH-48). Null (the default) hides it entirely.
final
runtimeType → Type
A representation of the runtime type of the object.
no setterinherited
skipLabel → String?
Label for the onSkip action, only shown when onSkip is non-null. Defaults to 'tutorial_skip'.tr (BUG-94).
final
stepIndicator → String?
Small progress caption shown above title/message (e.g. "Step 1/3") — null (the default) renders nothing, so a plain 1-off spotlight (not part of a TutorialSequence) is unaffected (ENH-48).
final
targetKey → GlobalKey<State<StatefulWidget>>
The already-mounted target widget to highlight.
final
title → String?
final

Methods

createElement() → StatefulElement
Creates a StatefulElement to manage this widget's location in the tree.
inherited
createState() → State<SpotlightOverlay>
Creates the mutable state for this widget at a given location in the tree.
override
debugDescribeChildren() → List<DiagnosticsNode>
Returns a list of DiagnosticsNode objects describing this node's children.
inherited
debugFillProperties(DiagnosticPropertiesBuilder properties) → void
Add additional properties associated with the node.
inherited
noSuchMethod(Invocation invocation) → dynamic
Invoked when a nonexistent 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 DiagnosticsNode.toStringDeep.
inherited
toString({DiagnosticLevel minLevel = DiagnosticLevel.info}) → String
A string representation of this object.
inherited
toStringDeep({String prefixLineOne = '', String? prefixOtherLines, DiagnosticLevel minLevel = DiagnosticLevel.debug, int wrapWidth = 65}) → 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

Operators

operator ==(Object other) → bool
The equality operator.
inherited