back_button_interceptor 4.0.6

  • README.md
  • CHANGELOG.md
  • Example
  • Installing
  • Versions
  • 92

back_button_interceptor #

In simple cases, when you need to intercept the Android back-button, you usually add WillPopScope to your widget tree. However, when developing stateful widgets that interact with the back button, it's more convenient to use the BackButtonInterceptor.

You may add functions to be called when the back button is tapped. These functions may perform some useful work, and then, if any of them return true, the default button process (usually popping a Route) will not be fired.

In more detail: All added functions are called, in order. If any function returns true, the combined result is true, and the default button process will NOT be fired. Only if all functions return false (or null), the combined result is false, and the default button process will be fired.

Optionally, you may provide a z-index. Functions with a valid z-index will be called before functions with a null z-index, and functions with larger z-index will be called first. When they have the same z-index, functions added last are called first.

Each function gets the boolean stopDefaultButtonEvent that indicates the current combined result from all the previous functions. So, if some function doesn't want to fire if some other previous function already fired, it can do:

if (stopDefaultButtonEvent) return false;

The same result may be obtained if the optional ifNotYetIntercepted parameter is true. Then the function will only be called if all previous functions returned false (that is, if stopDefaultButtonEvent is false).

Note: After you've finished you MUST remove each function by calling the remove() method. Alternatively, you may also provide a name when adding a function, and then later remove it by calling the removeByName(name) method.

Note: If any of your interceptors throws an error, a message will be printed to the console, but the error will not be thrown. You can change the treatment of errors by changing the static errorProcessing field.

Note: If your functions need to know the current route in the navigator, you may use the helper static method BackButtonInterceptor.getCurrentNavigatorRouteName(context). To get all routes, you may use getCurrentNavigatorRouteStack(context).

Usage #

Import the package #

First, add back_button_interceptor as a dependency in your pubspec.yaml

Then, import it:

import 'package:back_button_interceptor/back_button_interceptor.dart';

Example usage #

@override
void initState() {
   super.initState();
   BackButtonInterceptor.add(myInterceptor);
}

@override
void dispose() {
   BackButtonInterceptor.remove(myInterceptor);
   super.dispose();
}

bool myInterceptor(bool stopDefaultButtonEvent) {
   print("BACK BUTTON!"); // Do some stuff.
   return true;
}

Example with named function and z-index #

@override
void initState() {
   super.initState();
   BackButtonInterceptor.add(myInterceptor, zIndex:2, name:"SomeName");
}

@override
void dispose() {
   BackButtonInterceptor.removeByName("SomeName");
   super.dispose();
}

bool myInterceptor(bool stopDefaultButtonEvent) {
   print("BACK BUTTON!"); // Do some stuff.
   return true;
}

Runnable Examples #

Don't forget to check the example tab. main.dart just intercepts the back-button and prints a string to the console.

back_button_interceptor/example/complex_example/main.dart in the GitHub repository is more involved. The first screen has a button which opens a second screen. The second screen has 3 red squares. But tapping the Android back-button (or the "pop" button) each square turns blue, one by one. Only when all squares are blue, tapping the back-button once more will return to the previous screen.

This package is test friendly. See an example on testing the back-button here: back_button_interceptor/test/complex_example/main_test.dart.

Testing #

For testing purposes, the BackButtonInterceptor.popRoute() method may be called directly, to simulate pressing the back button. The list of all fired functions and their results is
recorded in the BackButtonInterceptor.results static variable.

See also: #

[1.0.0] - 2019/01/02

  • Tested thoroughly. Single interceptor.

[2.0.0] - 2019/01/02

  • Multiple interceptors.

[2.0.2] - 2019/02/22

  • Fixed dart version.

[3.0.0] - 2019/03/03

  • Prevents silent errors swallowing.

[4.0.1] - 2019/03/09

  • Functions added last are fired first. Parameters ifNotYetIntercepted and zIndex.

[4.0.2] - 2019/04/02

  • Helper methods to get the current route name, and the current route stack.

[4.0.4] - 2019/04/17

  • Testing features.

[4.0.5] - 2019/04/22

  • Small fix.

[4.0.6] - 2019/04/23

  • More testing features.

example/main.dart

import 'package:back_button_interceptor/back_button_interceptor.dart';
import 'package:flutter/material.dart';

void main() async => runApp(MaterialApp(home: Demo()));

class Demo extends StatefulWidget {
  @override
  DemoState createState() => new DemoState();
}

class DemoState extends State<Demo> {
  //
  @override
  void initState() {
    super.initState();
    BackButtonInterceptor.add(myInterceptor);
  }

  @override
  void dispose() {
    BackButtonInterceptor.remove(myInterceptor);
    super.dispose();
  }

  bool myInterceptor(bool stopDefaultButtonEvent) {
    print("BACK BUTTON!"); // Do some stuff.
    return true;
  }

  @override
  Widget build(BuildContext context) {
    //
    return Scaffold(
      appBar: AppBar(title: const Text('Back Button Interceptor Example')),
      body: Container(color: Colors.green),
    );
  }
}

Use this package as a library

1. Depend on it

Add this to your package's pubspec.yaml file:


dependencies:
  back_button_interceptor: ^4.0.6

2. Install it

You can install packages from the command line:

with Flutter:


$ flutter pub get

Alternatively, your editor might support flutter pub get. Check the docs for your editor to learn more.

3. Import it

Now in your Dart code, you can use:


import 'package:back_button_interceptor/back_button_interceptor.dart';
  
Version Uploaded Documentation Archive
4.0.6 Apr 23, 2019 Go to the documentation of back_button_interceptor 4.0.6 Download back_button_interceptor 4.0.6 archive
4.0.5 Apr 22, 2019 Go to the documentation of back_button_interceptor 4.0.5 Download back_button_interceptor 4.0.5 archive
4.0.4 Apr 17, 2019 Go to the documentation of back_button_interceptor 4.0.4 Download back_button_interceptor 4.0.4 archive
4.0.3 Apr 17, 2019 Go to the documentation of back_button_interceptor 4.0.3 Download back_button_interceptor 4.0.3 archive
4.0.2 Apr 2, 2019 Go to the documentation of back_button_interceptor 4.0.2 Download back_button_interceptor 4.0.2 archive
4.0.1 Mar 10, 2019 Go to the documentation of back_button_interceptor 4.0.1 Download back_button_interceptor 4.0.1 archive
4.0.0 Mar 9, 2019 Go to the documentation of back_button_interceptor 4.0.0 Download back_button_interceptor 4.0.0 archive
3.0.0 Mar 3, 2019 Go to the documentation of back_button_interceptor 3.0.0 Download back_button_interceptor 3.0.0 archive
2.0.2 Feb 22, 2019 Go to the documentation of back_button_interceptor 2.0.2 Download back_button_interceptor 2.0.2 archive
2.0.1 Feb 22, 2019 Go to the documentation of back_button_interceptor 2.0.1 Download back_button_interceptor 2.0.1 archive

All 12 versions...

Popularity:
Describes how popular the package is relative to other packages. [more]
85
Health:
Code health derived from static analysis. [more]
100
Maintenance:
Reflects how tidy and up-to-date the package is. [more]
100
Overall:
Weighted score of the above. [more]
92
Learn more about scoring.

We analyzed this package on Jun 12, 2019, and provided a score, details, and suggestions below. Analysis was completed with status completed using:

  • Dart: 2.3.1
  • pana: 0.12.17
  • Flutter: 1.5.4-hotfix.2

Platforms

Detected platforms: Flutter

References Flutter, and has no conflicting libraries.

Health suggestions

Format lib/back_button_interceptor.dart.

Run flutter format to format lib/back_button_interceptor.dart.

Dependencies

Package Constraint Resolved Available
Direct dependencies
Dart SDK >=2.0.0 <3.0.0
flutter 0.0.0
Transitive dependencies
collection 1.14.11
meta 1.1.6 1.1.7
sky_engine 0.0.99
typed_data 1.1.6
vector_math 2.0.8
Dev dependencies
flutter_test