ExpressiveBackHandle class
The system back for an overlay a component holds open over its route —
a split button's menu, an open FAB menu, a combobox's menu — rather than
in a route of its own (Compose's BackHandler(enabled = open) { close }).
While held it is a LocalHistoryEntry on the route, so the first back
closes the overlay and nothing else: the navigator's pop (the back
button, a router's back dispatch, a predictive back's commit) takes the
entry, not the route, and asks no PopScope on the page; the route
withholds its back gesture meanwhile (ModalRoute.popGestureEnabled),
so a predictive back never previews leaving the page; and the app tells
the platform it handles back (NavigationNotification), so on the first
route the back reaches the overlay instead of leaving the app.
On the kit's own routes (ExpressiveBackHandleRoute: pages, sheets, the
full-screen dialog, popups, the search view) the entry comes before the
page's PopScopes too; on another route Flutter asks a PopScope that
refuses first, as it does for a drawer.
A component calls sync in build with whether its overlay is open,
release the moment the overlay closes (a close followed at once by a
pop must pop the route), and dispose with its state. onBack is told
when a back took the entry; if the overlay stays open (a caller holding
it open), the component's next build holds the back again.
With closeWhenCovered, a popup held this way (a combobox's suggestions, a split button's menu) also closes when its route is covered: a route pushed over it (an alert, a dialog, a sheet), on its navigator or another (an alert on the root navigator over a page in a nested one, which the page's route cannot see but which takes the focus out of it). Left open, the popup stays drawn in its own route, under the new one, and is still open when that route is gone.
Constructors
- ExpressiveBackHandle({required VoidCallback onBack, bool closeWhenCovered = false})
-
A back handle that runs
onBackwhen the system goes back, and, withcloseWhenCovered, when a route covers the overlay's.
Properties
- closeWhenCovered → bool
-
Whether a cover closes the overlay too, through onBack: a route
pushed over the overlay's route, or the focus leaving that route,
while the overlay is open. onBack is told once the frame that
covered it is built; the focus stays where the covering route put it.
final
- hashCode → int
-
The hash code for this object.
no setterinherited
- onBack → VoidCallback
-
Closes the overlay: a back took the entry.
final
- runtimeType → Type
-
A representation of the runtime type of the object.
no setterinherited
Methods
-
dispose(
) → void - Lets the back go for good.
-
noSuchMethod(
Invocation invocation) → dynamic -
Invoked when a nonexistent method or property is accessed.
inherited
-
release(
) → void - Lets the back go: the overlay has closed.
-
sync(
BuildContext context, {required bool open}) → void -
Holds the back on
context's route whileopen, and lets it go otherwise (or when there is no route). -
toString(
) → String -
A string representation of this object.
inherited
Operators
-
operator ==(
Object other) → bool -
The equality operator.
inherited