Modal class
Hosts an unstyled modal behavior boundary above child.
modalBuilder runs only while the modal is open. Closing destroys that
subtree; opening again builds fresh state. The visible child is centered in
the current terminal and applications provide their own chrome, typically
with Panel. Resize recenters the same open subtree.
Opening snapshots the current focus. After the overlay mounts, focus moves to a live modal initialFocusNode, or otherwise to its first live focusable descendant. Closing restores the snapshot only while it remains attached to the same focus manager and can still request focus. Tab and Shift+Tab form a live closed loop over the modal's requestable descendants; a modal with no such descendants keeps focus on its private scope.
All pointer events outside the modal content are consumed at render-tree priority. dismissOnOutsideClick optionally closes on a primary-button down, while other outside events remain blocked. App-priority mouse observers may still see the raw event. Escape closes by default. When several modals share a focus manager, the topmost open entry owns focus repair. Closing it preserves a valid restored focus inside the modal below, or repairs that newly exposed modal to an available descendant.
Transition callbacks observe the new ModalController.isOpen value. A callback error does not leave the requested transition half-finished: the first error is rethrown after cleanup. Reentrant ModalController.open or ModalController.close calls determine the final state. Controller replacement preserves an open subtree without callbacks, and teardown does not invoke onClose.
- Inheritance
-
- Object
- Widget
- StatefulWidget
- Modal
Constructors
- Modal({required ModalController controller, required WidgetBuilder modalBuilder, required Widget child, Key? key, FocusNode? initialFocusNode, bool dismissOnEscape = true, bool dismissOnOutsideClick = false, VoidCallback? onOpen, VoidCallback? onClose})
-
Creates an unstyled modal behavior boundary.
const
Properties
- child → Widget
-
Ordinary subtree retained and painted below the modal.
final
- controller → ModalController
-
Controller attached exclusively to this modal while it is mounted.
final
- dismissOnEscape → bool
-
Whether Escape closes the modal.
final
- dismissOnOutsideClick → bool
-
Whether an outside primary-button press closes the modal.
final
- hashCode → int
-
The hash code for this object.
no setterinherited
- initialFocusNode → FocusNode?
-
Preferred caller-owned focus node for each fresh open.
final
- key → Key?
-
Controls how this widget replaces another of the same type.
finalinherited
- modalBuilder → WidgetBuilder
-
Builds the centered overlay subtree only while open.
final
- onClose → VoidCallback?
-
Invoked after each open-to-close transition starts, except teardown.
final
- onOpen → VoidCallback?
-
Invoked after each closed-to-open transition starts.
final
- runtimeType → Type
-
A representation of the runtime type of the object.
no setterinherited
Methods
-
createState(
) → State< Modal> -
Creates the mutable State for this widget.
override
-
noSuchMethod(
Invocation invocation) → dynamic -
Invoked when a nonexistent method or property is accessed.
inherited
-
toString(
) → String -
A string representation of this object.
inherited
Operators
-
operator ==(
Object other) → bool -
The equality operator.
inherited