Struct PushOptions 

pub struct PushOptions<State>
where
    State: 'static,
{ /* private fields */ }

Options for NavigatorController::push_with_options, carrying a pushed page’s opacity, back-press BackPolicy, optional per-op transition override, optional result callback, and (for a DismissAnimated overlay) the shared dismiss-signal cell the navigator bumps on a back request.

Construct with opaque/transparent, then chain the builder setters. The existing push* methods are unchanged — they push with BackPolicy::Pop and no dismiss signal.

Implementations

impl<State> PushOptions<State>

where State: 'static,

pub fn opaque() -> PushOptions<State>

Options for an opaque page (the page below is culled while covered). Defaults: BackPolicy::Pop, navigator-default transition, no result callback, no dismiss signal.

pub fn transparent() -> PushOptions<State>

Options for a transparent page (e.g. a dialog/sheet/palette overlay — the page below stays visible). Same defaults as opaque otherwise.

pub fn back(self, policy: BackPolicy) -> PushOptions<State>

Set the page’s back-press BackPolicy (default BackPolicy::Pop).

pub fn transition(self, spec: TransitionSpec) -> PushOptions<State>

Override the navigator’s default transition for this push only.

pub fn on_result( self, callback: impl Fn(&mut State, PopResult) + 'static, ) -> PushOptions<State>

Register a result callback invoked with &mut State when this page is later popped (carrying the pop’s PopResult) — the same delivery the push_for_result path uses.

pub fn dismiss_signal(self, signal: Rc<Cell<u64>>) -> PushOptions<State>

Supply the shared generation cell the navigator increments when a DismissAnimated back press routes to this page (see BackPolicy’s observation seam). Ignored for the other policies.

pub fn on_visibility( self, f: impl Fn(PageVisibility) + 'static, ) -> PushOptions<State>

Observe this page’s PageVisibility: fired once at push (with Current) and on every subsequent change, never twice with the same value. This is the seam a screen pauses/resumes polling, a timer, or a camera session from.

Why it is a callback, not a published cell

A covered page is neither painted nor (under NavigatorView::cull_covered_builds) rebuilt, so it has no pass in which to poll anything. The seam therefore has to push. It is shaped exactly like on_result/ dismiss_signal: a plain Rc<dyn Fn> slot, no signal — frust-widgets is reactive-free.

No &mut State

The callback receives no &mut State, unlike on_result. It fires from a rebuild (a BuildCtx), which carries no erased app state, and it fires synchronously there: nothing is queued, so a covered page learns it is covered on the frame it happens. Capture what you need (a signal, an Rc<Cell<_>>, a controller handle) in the closure instead.

(on_result does defer — it needs &mut State — but it is no longer waiting on user input to be delivered: the rebuild that queues it also dispatches the InputEvent::Housekeeping broadcast that flushes it, so both seams now land on the same frame. See the module docs.)

“No cleanup on cover” is the contract, not a bug

A covering push does not fire the page’s on_cleanup and must never start to: the page stays mounted so its widget state survives the cover (the retained-page-state guarantee the whole navigator rests on — see the module docs’ paint-culling section). This seam exists precisely so a page can release its own resources on Covered and re-acquire them on Current, without the navigator disposing anything.

Calling back into the NavigatorController from here is safe: a push/pop only records an op, drained at the next rebuild.

pub fn route(self, location: Location) -> PushOptions<State>

Stamp this page’s route identity (R-B1): the Location it was pushed with, published on the navigator’s RouteStack and never derived from depth. Omit for a page pushed as a bare builder (an overlay/dialog) — it then publishes a None entry, which RouteStack::current_route skips.

pub fn pop_swipe(self, enabled: bool) -> PushOptions<State>

Override this page’s edge-swipe eligibility, ranked above every other gesture-policy slot: page → navigator explicit (NavigatorView::pop_swipe) → platform (NavigatorView::platform_pop_swipe) → preset-derived default. Still subject to BackPolicy: a DismissAnimated or Veto page never arms the gesture regardless of this override (see NavigatorWidget::swipe_armable).