PopScope

Guards the route it sits in against a user’s request to go back.

Import: package:fleury/fleury.dart, or package:fleury/fleury_core.dart in browser code.

Usage

PopScope(
  canPop: !hasUnsavedChanges,
  onBlocked: () => setState(() => status = 'Save or discard first'),
  child: editor,
)

Details

A back request is an Escape the screen doesn’t handle itself, a call to NavigatorState.maybePop (a Back button or command), or the route’s semantic close or dismiss action. While canPop is false, such a request leaves the route open and calls onBlocked instead — the place to confirm “discard changes?”. NavigatorState.pop (context.pop()) is NOT intercepted, so the screen can still close itself once the user confirms; nor are the other stack changes, such as NavigatorState.popUntil and NavigatorState.pushReplacement.

A PopScope guards the route of its nearest Navigator, and only the top route’s guards are consulted, so a guarded screen beneath a dialog doesn’t stop the dialog from closing. Multiple PopScopes in one route compose: any with canPop == false blocks, and each that blocks has its onBlocked called.

At the root, where there is nothing to pop, an Escape passes on to key bindings outside the navigator. A PopScope there with canPop false consumes that Escape and calls onBlocked, so a screen can confirm before an app exit bound to Escape. It never intercepts Ctrl+C.

Constructors

`PopScope()`

Parameter	Type	Default	Description
`child:`	`Widget`	required	The guarded content, typically the route’s screen. PopScope builds it unchanged.
`canPop:`	`bool`	`true`	Whether a back request may pop this route. When false the attempt is vetoed and `onBlocked` fires. More
`onBlocked:`	`VoidCallback?`	—	Called when a back request was vetoed (because `canPop` was false). More

canPop: Read at each attempt, so rebuilding with a new value (for example when unsaved changes appear) applies to the next one.
onBlocked: Runs during the attempt, once per vetoed attempt, and never for NavigatorState.pop.

Source

PopScope is defined in packages/fleury/lib/src/widgets/navigator.dart.

Category: Navigation & overlays · All widgets

Example · editable

Widget example() =>
Navigator(transition: RouteTransition.none, home: const _DraftsScreen());

class _GuardedEditorState extends State<_GuardedEditor> {
  late final TextEditingController _controller;
  late String _savedText;
  bool _dirty = false;
  String _status = 'No unsaved changes';

  @override
  void initState() {
    super.initState();
    _savedText = widget.initialText;
    _controller = TextEditingController(text: _savedText);
  }

  void _handleChanged(String value) {
    final dirty = value != _savedText;
    setState(() {
      _dirty = dirty;
      _status = dirty ? 'Unsaved changes' : 'No unsaved changes';
    });
  }

  void _save() {
    final value = _controller.text;
    widget.onSave(value);
    setState(() {
      _savedText = value;
      _dirty = false;
      _status = 'Saved — back is allowed';
    });
  }

  @override
  void dispose() {
    _controller.dispose();
    super.dispose();
  }

  @override
  Widget build(BuildContext context) => PopScope(
    canPop: !_dirty,
    onBlocked: () => setState(() => _status = 'Back blocked — save first'),
    child: Column(
      crossAxisAlignment: CrossAxisAlignment.start,
      children: [
        const Text('EDITOR', style: CellStyle(bold: true)),
        Text('status: $_status'),
        const SizedBox(height: 1),
        TextInput(
          autofocus: true,
          semanticLabel: 'Draft text',
          controller: _controller,
          onChanged: _handleChanged,
        ),
        const SizedBox(height: 1),
        Button(text: 'Back', onPressed: () => Navigator.of(context).maybePop()),
        Button(text: 'Save', onPressed: _save),
        Button(text: 'Discard', onPressed: context.pop),
      ],
    ),
  );
}

class _DraftsScreenState extends State<_DraftsScreen> {
  String _savedText = 'Release notes';

  void _saveDraft(String value) => setState(() => _savedText = value);

  @override
  Widget build(BuildContext context) => Column(
    crossAxisAlignment: CrossAxisAlignment.start,
    children: [
      const Text('DRAFTS', style: CellStyle(bold: true)),
      Text('saved: $_savedText'),
      const SizedBox(height: 1),
      Button(
        text: 'Edit draft',
        autofocus: true,
        onPressed: () => context.push<void>(
          _GuardedEditor(initialText: _savedText, onSave: _saveDraft),
        ),
      ),
    ],
  );
}

Live preview

Live · interactive

click & type to interact ⓘ how this demo runs