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 onBack when the system goes back, and, with closeWhenCovered, 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 while open, 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