Forem: flutter-clutter

Navigate without animation in Flutter

flutter-clutter — Sun, 23 Oct 2022 20:21:06 +0000

By default, Flutter configures your navigation in a way that the transition from one screen to another is presented with a slide or fade animation. While it can be a decent way to navigate for most of the scenarios, there are situations in which you might not want this to happen.
Let's see how we can change this predefined behavior.

Anonymous routes {#anonymous-routes}

The most basic and a very common way to navigate is by using an anonymous route. This means, we use Navigator.push() and thus create the Route during this call. The route is called anonymous because compared to Navigator.push(), this route does not have a name - similar to an anonymous function.

But if we create the Route in the moment of calling Navigator.push(), how can we configure the transition?

If we use a MaterialPageRoute like this:

Navigator.push(
  context,
  MaterialPageRoute(builder: (BuildContext context) => OtherScreen()),
);

we end up with a slide animation on iOS and macOS and a fade animation on Android.
This is because the animation inside the MaterialPageRoute is determined by the PageTransitionsTheme which is used in the respective buildTransitions() function.:

class PageTransitionsTheme with Diagnosticable {
  /// Constructs an object that selects a transition based on the platform.
  ///
  /// By default the list of builders is: [ZoomPageTransitionsBuilder]
  /// for [TargetPlatform.android], and [CupertinoPageTransitionsBuilder] for
  /// [TargetPlatform.iOS] and [TargetPlatform.macOS].
  const PageTransitionsTheme({ Map<TargetPlatform, PageTransitionsBuilder> builders = _defaultBuilders }) : _builders = builders;

  static const Map<TargetPlatform, PageTransitionsBuilder> _defaultBuilders = <TargetPlatform, PageTransitionsBuilder>{
    TargetPlatform.android: ZoomPageTransitionsBuilder(),
    TargetPlatform.iOS: CupertinoPageTransitionsBuilder(),
    TargetPlatform.macOS: CupertinoPageTransitionsBuilder(),
  };

Luckily, we have another option. Let's have a look at the inheritance of MaterialPageRoute:

Object → Route → OverlayRoute → TransitionRoute → ModalRoute → PageRoute → MaterialPageRoute

Since the second parameter of the push() method is of type Route, we just have to find another class that extends Route but is more configurable.

While we can not directly configure the Route regarding its transition, we can certainly do that using a descendant of this class: the PageRouteBuilder, which also extends Route as this inheritance order shows:

Object → Route → OverlayRoute → TransitionRoute → ModalRoute → PageRoute → PageRouteBuilder

In order to prevent the animation, we use the named arguments transitionDuration and reverseTransitionDuration, which we both set to Duration.zero:

Navigator.push(
  context, 
  PageRouteBuilder(
    pageBuilder: (BuildContext context, Animation<double> animation1, Animation<double> animation2) {
      return OtherScreen();
    },
    transitionDuration: Duration.zero,
    reverseTransitionDuration: Duration.zero,
  ),
);

By doing this, we ensure that neither navigating to nor returning from the screen results in an animation.

Generated routes {#generated-routes}

A better way to organize routes instead of directly using the push() method is to use generated routes. The idea is to have a single place where all routes are defined. By giving every route a name, you can refer to that route from everywhere inside your code (by using pushNamed()) instead of redefining this navigation logic multiple times.

For this approach, we will generate a separate class that extends MaterialPageRoute. Instead of creating an animation inside the buildTransitions() function, we just instantly return the child:

class UnanimatedPageRoute<T> extends MaterialPageRoute<T> {
  UnanimatedPageRoute({
    required Widget Function(BuildContext) builder,
    RouteSettings? settings,
    bool maintainState = true,
    bool fullscreenDialog = false,
  }) : super(
          builder: builder,
          settings: settings,
          maintainState: maintainState,
          fullscreenDialog: fullscreenDialog,
        );

  @override
  Widget buildTransitions(
    BuildContext context,
    Animation<double> animation,
    Animation<double> secondaryAnimation,
    Widget child,
  ) {
    return child;
  }
}

In the MaterialApp widget inside the onGenerateRoute function, we can now use this new class for navigation:

MaterialApp(
  onGenerateRoute: (settings) {
    if (settings.name == OtherScreen.routeName) {
      return UnanimatedPageRoute(
        builder: (context) => OtherScreen(),
      );
    }
  },
)

We could even decide per route if it's animated or not by creating a function that expects a bool parameter and uses the one or the other Route class depending on this parameter:

  Route<T?> buildPageRoute<T>(
    Widget child,
    bool animated,
  ) {
    if (animated) {
      return CupertinoPageRoute<T?>(
        builder: (BuildContext context) => child,
      );
    }

    return UnanimatedPageRoute<T?>(
      builder: (BuildContext context) => child,
    );
  }

MaterialApp(
  onGenerateRoute: (settings) {
    if (settings.name == OtherScreen.routeName) {
      return buildPageRoute(
        builder: (context) => OtherScreen(),
        false // or true if we want it to be slided in
      );
    }
  },
)

We can utilize this solution for anonymous routing using push() as well:

Navigator.push(
  context,
  UnanimatedPageRoute(builder: (BuildContext context) => OtherScreen()),
);

go_router

With the go_router package we get a high level API for declarative routing in Flutter. The package wraps around the Navigator 2.0 API. Instead of routes, we deal with pages there.\
So in order to configure go_router in a similar fashion like we did above, we create a function called buildPageWithoutAnimation() that ignores the given animation arguments and returns the child immediately.

CustomTransitionPage<T> buildPageWithoutAnimation({
  required BuildContext context, 
  required GoRouterState state, 
  required Widget child,
}) {
  return CustomTransitionPage<T>(
    key: state.pageKey,
    child: child,
    transitionsBuilder: (context, animation, secondaryAnimation, child) => child
  );
}

…

GoRoute(
  path: '/other-screen',
  builder: (BuildContext context, GoRouterState state) => const OtherScreen(),
  pageBuilder: (BuildContext context, GoRouterState state) => buildPageWithoutAnimation<void>(
    context: context, 
    state: state, 
    child: OtherScreen(),
  ),
),

Conclusion

The concept of how to prevent an animation during the transition from one screen to another is pretty simple: instead of returning an animation in the respective builder function, we return the new screen (widget) directly.

When dealing with push(), we just set the transition duration to zero which leaves no time for the animation.

Creating a geo map quiz game in Flutter

flutter-clutter — Sun, 24 Apr 2022 18:49:09 +0000

The hard part of creating a good single player game is the implementation of a challenging but not unbeatable opponent. In case of quizzes, the opponent is a knowledge base. Let’s use the huge amount of geological knowledge bases to create a geo quiz game.

The idea is as follows:

The user is presented a random city or town on a map that has a circle on top indicating a radius. The user is then asked to guess the amount of random entity types within that area (for example: How many McDonald’s do you think are inside of that radius?). The user makes a guess, taps a button and is presented with the correct answer.

You would be surprised how hard it is to actually guess the correct amount!

So basically there are two different screens that look like this:

So what are the pieces we need to put together for this to work:

Display a map inside of the app
Display a certain radius around a given center
Choose a random city or town (fetching its coordinates)
Get the coordinates of all entities of a certain type inside of an area

Fetching the geo data

Before we start implementing anything with Flutter, let’s take care of getting the geo data we need.

There are quite some options we can choose from but if we require our API to be free and open source, the options decrease. Luckily, there is a huge collaborative project called OpenStreetMap. It is said to have more than 6000 contributors every day that voluntarily enhance the data. The data might not be as accurate as it is for Google Maps for some areas, but in any case it’s sufficient for our use case.

OpenStreetMap itself provides a REST API, but this is primarily for editing and updating map data. An alternative is Overpass API. It is a read-only API that gives the data consumer access to the underlying data of OSM, which is exactly what we want.

Let’s get familiar with the API. Unlike common web services like REST or SOAP, this API has its own query language called Overpass QL. The idea is to have a quantity of statements that manipulate the set containing the resulting nodes (or ways or relations).

Nodes are described using tags, which are basically key value pairs. For example places have the tag “population” with the number of citizens as the key.

Every statement written in Overpass QL ends with a semicolon.

Before we dive too deep into the semantics of the language, I will explain some basics based on a real working query:

[out:json][timeout:80];

area["ISO3166-1"="DE"][admin_level=2]->.germany;
(
  node["place"="town"](if: t["population"] > 20000)(area.germany);
  node["place"="city"](area.germany);
);

out;

We start by defining the output format (JSON in this case). We also define a timeout of 80 seconds because the query will take some time to be completed. That’s because the result set will be quite big.

We then define an area. That’s because otherwise, we would query the whole world which would take too long. In our case, it’s the area with the tag “DE” for the key “ISO3166-1”. This norm defines the country codes. That means we restrict the area to Germany (country code: DE).

Within brackets we define the result set. We let it consist of all nodes with the tag being either town (with a population greater than 20.000) or city.

More information about places can be found in the official wiki.

But how do we test if our query produces a proper result? Thanks to Martin Raifer, there is a website called Overpass Turbo. This website lets the user query the overpass API and inspect the results on an embedded map (or as raw data).

The visualized response as JSON looks as follows (shortened to the first two elements):

{
   "version":0.6,
   "generator":"Overpass API 0.7.56.7 b85c4387",
   "osm3s":{
      "timestamp_osm_base":"2020-10-26T12:50:03Z",
      "timestamp_areas_base":"2020-10-26T11:40:02Z",
      "copyright":"The data included in this document is from www.openstreetmap.org. The data is made available under ODbL."
   },
   "elements":[
{
  "type": "node",
  "id": 12101533,
  "lat": 49.6810158,
  "lon": 8.6227577,
  "tags": {
    "ele": "115",
    "is_in": "Bergstraße,Darmstadt,Hessen,Bundesrepublik Deutschland,Europe",
    "name": "Bensheim",
    "name:de": "Bensheim",
    "name:ru": "Бенсхайм",
    "openGeoDB:loc_id": "14285",
    "place": "town",
    "population": "39642",
    "wikidata": "Q14872"
  }
},
{
  "type": "node",
  "id": 13355228,
  "lat": 48.7427584,
  "lon": 9.3071685,
  "tags": {
    "alt_name": "Esslingen",
    "is_in": "Esslingen,Stuttgart,Baden-Württemberg,Bundesrepublik Deutschland,Europe",
    "name": "Esslingen am Neckar",
    "name:ru": "Эсслинген-на-Неккаре",
    "openGeoDB:loc_id": "16357",
    "openGeoDB:postal_codes": "73728,73730,73732,73733,73734",
    "place": "town",
    "population": "92261",
    "wikidata": "Q3786"
  }
},
    ...
   ]
}

We may not need all of the information, but what we definitely need for our game are the coordinates (lon and lat) and the name.

Implementation

The main part of the implementation is about the geo data. Let’s start with the static data we acquired by executing the previous query and then proceed with dynamic API calls.

Fetching cities and towns

The geo data we just fetched, is static. There won’t be lots of positional changes regarding the towns and cities in Germany in the next years. That’s why we download the data once and access that local data on the file system instead of making a new request to the Overpass API every time.

We take the JSON from the response and put it into a file. Then we create a new project and put it in a folder that we name “assets”:

I downloaded both the German and English cities and put their respective JSON files in a directory called “locations”, which is located directly under the assets folder.

We also need to edit the pubpsec.yml to make the files under the assets folder accessible during runtime:

assets:
    - assets/locations/

Let’s create a service that encapsulates the functionalities that are connected to geographic locations:

import 'dart:convert';

import 'package:flutter/services.dart' show rootBundle;

class GeoService {
  GeoService({
    this.fileName = 'cities_de'
  }): assert(fileName != '');

  final String fileName;

  List<Location> _cachedList;

  Future<List<Location>> getLocations() async {
    if (_cachedList == null) {
      Map<dynamic, dynamic> json = await _getJsonFromFile(fileName);
      _cachedList = _jsonToLocations(json);
    }

    return _cachedList;
  }

  Future<Map<dynamic, dynamic>> _getJsonFromFile(String fileName) async {
    String jsonString = await rootBundle.loadString('assets/locations/$fileName.json');

    return jsonDecode(jsonString);
  }

  List<Location> _jsonToLocations(Map<dynamic, dynamic> json) {
    List<Location> locations = [];

    for (var element in json["elements"]) {
      locations.add(
        Location.fromJson(element)
      );
    }

    return locations;
  }
}

class Location {
  final double longitude;
  final double latitude;
  final String name;

  Location({
    this.longitude,
    this.latitude,
    this.name,
  });

  Location.fromJson(Map<dynamic, dynamic> json) :
    longitude = json['lon'],
    latitude = json['lat'],
    name = json['tags']['name'];
}

We add one public method to our newly created service: getLocations(). This method returns a list of a new model named Location, which holds the coordinates and a name.

The service’s constructor argument is the file name. Since we have a file for German cities (cities_de) and one for English cities (cities_en), we let the caller decide, which one to use and let the German cities be the fallback.

For converting JSON to the Location model, we follow the official guidelines on serializing JSON inside model class and add a fromJson() method.

We then iterate over every child of the elements key inside the JSON data.

Fetching entities

When a new task in the game starts, we need to fetch the respective entities in the given area around the city. The request looks like this:

[out:json][timeout:25];

(
  node["brand"="McDonald's"]["amenity"="fast_food"]["cuisine"="burger"](around:50000,52.520008,13.404954);
);
out body;

In this example, we query all the McDonald’s restaurants that are in a 50 km radius around Berlin.

Let’s abstract from the text form of the query by creating a OverpassQuery class, that holds the parts of the query we need:

class OverpassQuery {
  String output;
  int timeout;
  List<SetElement> elements;

  OverpassQuery({
    this.output,
    this.timeout,
    this.elements
  });

  Map<String, String> toMap() {
    String elementsString = '';

    for (SetElement element in elements) {
      elementsString += '$element;';
    }

    String data = '[out:$output][timeout:$timeout];($elementsString);out;';

    return <String, String> {
      'data': data
    };
  }
}

class SetElement {
  final Map<String, String> tags;
  final LocationArea area;

  SetElement({
    this.tags,
    this.area
  });

  @override
  String toString() {
    String tagString = '';

    tags.forEach((key, value) {
      tagString += '["$key"="$value"]';
    });

    String areaString = '(around:${area.radius},${area.latitude},${area.longitude})';

    return 'node$tagString$areaString';
  }
}

class LocationArea {
  final double longitude;
  final double latitude;
  final double radius;

  LocationArea({
    this.longitude,
    this.latitude,
    this.radius
  });
}

class ResponseLocation {
  double longitude;
  double latitude;
  String name;
  String city;
  String street;

  ResponseLocation({
    this.longitude,
    this.latitude,
    this.name,
    this.city,
    this.street,
  });

  ResponseLocation.fromJson(Map<dynamic, dynamic> json) {
    this.longitude = json['lon'];
    this.latitude = json['lat'];

    Map<String, dynamic> tags = json['tags'];

    if (tags == null) {
      return;
    }

    this.name = json['tags']['name'];
    this.city = json['tags']['addr:city'];
    this.street = json['tags']['addr:street'];
  }
}

class QueryLocation {
  final double longitude;
  final double latitude;

  QueryLocation({
    this.longitude,
    this.latitude,
  });
}

We know that a query (at least the one we need) consists of three parts:

Options (timeout; output format)
Defining the result set
Instruction to output the data

The most relevant part is defining the result set. This is modeled as a list of SetElements. Every SetElement has a list of Tags (being a String Map) and an to limit the space.

A crucial part of our OverpassQuery is the toMap() method because this method brings the query into a form that can be used as the body of our HTTP request to the Overpass API.

Now that we have a class representing an OverpassQuery, let’s use this query to perform an actual request to the Overpass-API. So in addition to the query class, we add an API class:

import 'dart:convert';

import 'package:xml/xml.dart';
import 'package:http/http.dart';

import '../models/overpass_query.dart';


class OverpassApi {
  static String _apiUrl = 'overpass-api.de';
  static String _path = '/api/interpreter';

  Future<List<ResponseLocation>> fetchLocationsAroundCenter(QueryLocation center, Map<String, String> filter, double radius) async {
    Request request = Request('GET', Uri.https(_apiUrl, _path));
    request.bodyFields = _buildRequestBody(center, filter, radius);

    String responseText;

    try {
      StreamedResponse response = await Client()
          .send(request)
          .timeout(const Duration(seconds: 5));

      responseText = await response.stream.bytesToString();
    }
    catch (exception) {
      print(exception);
      return Future.error(exception);
    }

    var responseJson;

    try {
      responseJson = jsonDecode(responseText);
    }
    catch (exception) {
      String error = '';
      final document = XmlDocument.parse(responseText);
      final paragraphs = document.findAllElements("p");

      paragraphs.forEach((element) {
        if (element.text.trim() == '') {
          return;
        }

        error += '${element.text.trim()}';
      });

      return Future.error(error);
    }

    if (responseJson['elements'] == null) {
      return [];
    }

    List<ResponseLocation> resultList = [];

    for (var location in responseJson['elements']) {
      resultList.add(ResponseLocation.fromJson(location));
    }

    return resultList;
  }

  Map<String, String> _buildRequestBody(QueryLocation center, Map<String, String> filter, double radius) {
    OverpassQuery query = new OverpassQuery(
      output: 'json',
      timeout: 25,
      elements: [
        SetElement(
          tags: filter,
          area: LocationArea(
            longitude: center.longitude,
            latitude: center.latitude,
            radius: radius
          )
        )
      ],
    );

    return query.toMap();
  }
}

There is a lot going on in this class so I will explain step by step:

The only public method we have is fetchLocationsAroundCenter(). This method receives a location, a filter and a radius. A filter is a list of an associative array (Map). This represents the tag filters. This is useful if we e. g. only want to fetch the trees. A tree in OSM is determined by the tag "natural": "tree". A McDonald’s entity is determined by "brand": "McDonald's".

So the filter Map says: only if the tags of the entities meet the structure of the given map, they will be queried.

The radius argument determines the km around the center in which the filtered entities should be searched.

The _buildRequestBody()‘s responsibility is to convert the given OverpassQuery to a valid body that meets the requirements of the HTTP-Library of Dart. In this case, the bodyFields field of the Request is basically a Map<String, String>. That’s why this is the return value of our method.

Now why do we need XML-parsing here? Well, the API acts a little bit strange here. In case of success, the response is a JSON string. If there was an error, it’s embedded into an XML document. That’s the reason why try to parse the JSON string. If there was an error parsing it, we know there was an error, parse the XML document and extract the error from the XML. Otherwise, we return the “elements” value from the JSON.

Putting everything in the GeoService

Now that we have an API class that handles Overpass-API requests for us, we need to use that class in our GeoService:

class GeoService {
  GeoService({
    @required this.overpassApi,
    this.fileName = 'cities_de'
  }): assert(overpassApi != null);

  final OverpassApi overpassApi;
  final String fileName;

  ...

  Future<List<Location>> getEntitiesInArea({
    Location center, SearchType type, double radiusInMetres = 5000
  }) async {
    List<ResponseLocation> fetchResult = await this.overpassApi.fetchLocationsAroundCenter(
      QueryLocation(
        longitude: center.longitude,
        latitude: center.latitude
      ),
      type.tags,
      radiusInMetres
    );

    List<Location> result = [];

    fetchResult.forEach((element) {
      result.add(
        Location(
          longitude: element.longitude,
          latitude: element.latitude,
          name: element.name
        )
      );
    });

    return result;
  }

  ...

}

With the constructor now expecting the OverpassAPI class in its constructor, we are now able to call it inside our newly created function. We pass the QueryLocation, the tags and the radius and iterate over the result set, turning it into a List<Location>.

Search types

As an observant reader you might have noticed that the getEntitiesInArea() method of our GeoService expects a SearchType. This is a class we haven’t introduced yet. The idea is to have different search types like trees, bars etc. of which a random one is picked when the user wants a new geo guessing exercise round and passed to the API call.

For this, we need a place to define the available search types and a service that returns them.

Let’s define a search_types.json that is located under assets/ and define our search types like this:

{
  "elements": [
    {
      "name": {
        "singular": "bar",
        "plural": "bars"
      },
      "tags": {
        "amenity": "bar"
      }
    },
    {
      "name": {
        "singular": "pub",
        "plural": "pubs"
      },
      "tags": {
        "amenty": "pub"
      }
    },
    {
      "name": {
        "singular": "McDonald's",
        "plural": "McDonald's"
      },
      "tags": {
        "brand": "McDonald's",
        "amenity": "fast_food",
        "cuisine": "burger"
      }
    },
    {
      "name": {
        "singular": "street lamp",
        "plural": "street lamps"
      },
      "tags": {
        "highway": "street_lamp"
      }
    },
    {
      "name": {
        "singular": "tree",
        "plural": "trees"
      },
      "tags": {
        "natural": "tree"
      }
    },
    {
      "name": {
        "singular": "memorial",
        "plural": "memorials"
      },
      "tags": {
        "historic": "memorial"
      }
    },
    {
      "name": {
        "singular": "bus stop",
        "plural": "bus stops"
      },
      "tags": {
        "highway": "bus_stop"
      }
    },
    {
      "name": {
        "singular": "fire station",
        "plural": "fire stations"
      },
      "tags": {
        "amenity": "fire_station"
      }
    },
    {
      "name": {
        "singular": "bench",
        "plural": "benches"
      },
      "tags": {
        "amenity": "bench"
      }
    },
    {
      "name": {
        "singular": "village",
        "plural": "villages"
      },
      "tags": {
        "place": "village"
      }
    },
    {
      "name": {
        "singular": "post box",
        "plural": "post boxes"
      },
      "tags": {
        "amenity": "post_box"
      }
    },
    {
      "name": {
        "singular": "recycling container",
        "plural": "recycling containers"
      },
      "tags": {
        "amenity": "recycling"
      }
    }
  ]
}

By having a JSON file with its search type definitions, we have a very extendible game.

Apart from the tags the search type should have, we also define the singular and plural of the word so that we can display meaningful sentences with the search type like: “How many bars are around Hamburg?”

Now we need a service to retrieve these search type from the JSON file and put it into a new class:

import 'dart:convert';

import 'package:flutter/services.dart' show rootBundle;

class SearchTypeService {
  List<SearchType> _cachedList;

  Future<List<SearchType>> getSearchTypes() async {
    if (_cachedList == null) {
      List<dynamic> json = await _getJsonFromFile('search_types');
      _cachedList = _jsonToSearchTypes(json);
    }

    return _cachedList;
  }

  Future<List<dynamic>> _getJsonFromFile(String fileName) async {
    String jsonString = await rootBundle.loadString('assets/$fileName.json');

    return jsonDecode(jsonString)['elements'];
  }

  List<SearchType> _jsonToSearchTypes(List<dynamic> json) {
    List<SearchType> searchTypes = [];

    for (var element in json) {
      searchTypes.add(
        SearchType.fromJson(element)
      );
    }

    return searchTypes;
  }
}

class SearchType {
  String singular;
  String plural;
  Map<String, String> tags;

  SearchType({
    this.singular,
    this.plural,
    this.tags
  });

  SearchType.fromJson(Map<dynamic, dynamic> json) {
    this.singular = json['name']['singular'];
    this.plural = json['name']['plural'];

    Map<String, String> tags = new Map();

    json['tags'].forEach((key, value) {
      tags[key] = value;
    });

    this.tags = tags;
  }
}

This happens in a similar fashion like the GeoService fetches the cities from the cities_xx.json.

Displaying a map

Now it’s time to actually display a map in the UI. Because we are working with OSM, we can’t use the google_maps_flutter package. Instead, we are going to use flutter_map. It’s an implementation of the popular Javascript library Leaflet. Let’s add this dependency to our pubspec:

dependencies:
  flutter:
    sdk: flutter

  http: 0.12.2
  xml: 4.5.1
  flutter_map: 0.10.1+1

Now that we have the possibility to display a map, we are going to implement the main widget, showing the map and enabling the user to interact with the quiz:

import 'dart:math';

import 'package:flutter/material.dart';
import 'package:flutter_geo_guesser/api/overpass_api.dart';
import 'package:flutter_geo_guesser/services/geo_service.dart';
import 'package:flutter_geo_guesser/services/search_type_service.dart';
import 'package:flutter_map/flutter_map.dart';
import 'package:latlong/latlong.dart';

class Quiz extends StatefulWidget {
  @override
  _QuizState createState() => _QuizState();
}

class _QuizState extends State<Quiz> {
  final MapController _mapController = new MapController();
  final OverpassApi _overpassApi = new OverpassApi();
  GeoService _geoService;

  List<SearchType> _searchTypes = [];
  List<Location> _locations = [];

  Location _currentLocation;
  List<Location> _entities = [];
  SearchType _currentType;
  bool _answered = false;

  @override
  void initState() {
    _geoService = new GeoService(overpassApi: _overpassApi);

    WidgetsBinding.instance.addPostFrameCallback((timeStamp) async {
      _initialize();
    });

    super.initState();
  }

  @override
  Widget build(BuildContext context) {
    return Scaffold(
      appBar: AppBar(
        backgroundColor: Colors.white,
        title: Center(child: Text("Guess what! 🤔", style: TextStyle(color: Colors.black))),
      ),
      body: Center(
        child: Stack(
          children: [
            _getMap(),
            _getTopContainer()
          ],
        )
      ),
      floatingActionButton: FloatingActionButton(
        onPressed: _proceed,
        child: Icon(Icons.check),
      ),
    );
  }

  ...

}

First, we’re initializing a bunch of member variables. The first three are just to keep single instances of the controller and services we are using. These are initialized once.

_searchedTypes and _locations represent the static data we are reading from our JSON files (cities_xy.json and search_types.json).

The rest of the variables exist to store the current state of the quiz. This is necessary so that we can adjust what the widget shows accordingly.

The main layout is pretty simple: we have a Stack with the map at the bottom and a top container on top. This container shows either the current quiz question (“How many entities of type xy are there around z?”) or the answer (“There are x entitites of type y around z”).

The FloatingActionButton exists to let the user proceed. Either to the next question or from the unanswered state to answered state.

Let’s have a look at the _initialize() method we are calling inside of initState() after the first frame was rendered:

void _initialize() async {
    _searchTypes = await SearchTypeService().getSearchTypes();
    _locations = await _geoService.getLocations();

    _getNewLocation();
    _getNewSearchType();
  }

  void _getNewLocation() {
    if (_locations.isEmpty) {
      return;
    }

    setState(() {
      _currentLocation = _locations[Random().nextInt(_locations.length)];
    });

    _mapController.move(
        new LatLng(_currentLocation.latitude, _currentLocation.longitude),
        11
    );
  }

  void _getNewSearchType() {
    _currentType = _searchTypes[Random().nextInt(_searchTypes.length)];
  }

Initially, we are fetching the search types we have set in our search_type.json. We also fetch the locations from cities_xx.json. After that, we let our algorithm choose a new random location and let the MapController move there which centers this location in our map. After having chosen a new location, we also choose a new SearchType.

Now that we’ve had a look at the initialization, let’s inspect what happens when the user taps the FloatingActionButton which calls the _proceed() method:

void _proceed() async {
    if (_answered == true) {
      _showNewQuestion();
      return;
    }

    _answerQuestion();
  }

  void _showNewQuestion() {
    setState(() {
      _getNewLocation();
      _getNewSearchType();
      _entities = [];
      _answered = false;
    });
  }

  Future _answerQuestion() async {
    _indicateLoading();

    _entities = await GeoService(overpassApi: _overpassApi).getEntitiesInArea(
        center: _currentLocation,
        type: _currentType
    );

    Navigator.of(context).pop();

    setState(() {
      _answered = true;
    });
  }

There are two states in which the FAB can be tapped: when the current question is display or when the current answer is displayed.

We differentiate these two states by evaluation the _answered variable.

If _answered equals true, it means that tapping the FAB should display a new question. That’s why we choose a new location, a new search type and reset the entities and the answered flag.

Otherwise, if _answered equals false, we need to display the answer to the previous question. First, we indicate a loading because the following procedure can take some time as it’s out of our control how quickly the Overpass API responds to our query. Then we fetch the entities in the current location, await the result, dismiss the loading indicator and set the _answered flag to true.

Great! Now that we have the necessary data in place, we’re only left to use this data to display a map that visualizes it.

FlutterMap _getMap() {
    return FlutterMap(
      mapController: _mapController,
      options: new MapOptions(
        interactive: false,
        center: _currentLocation != null ? new LatLng(_currentLocation.latitude, _currentLocation.longitude) : null,
        zoom: 11,
      ),
      layers: [
        new TileLayerOptions(
            urlTemplate: "https://{s}.tile.openstreetmap.org/{z}/{x}/{y}.png",
            subdomains: ['a', 'b', 'c']
        ),
        new MarkerLayerOptions(
          markers: _getMarkers(),
        ),
        new MarkerLayerOptions(
          markers: _getAreaMarkers(),
        ),
      ],
    );
  }

  List<Marker> _getMarkers() {
    List<Marker> markers = [];

    for (Location location in _entities) {
      markers.add(
          new Marker(
            width: 6,
            height: 6,
            point: new LatLng(location.latitude, location.longitude),
            builder: (ctx) =>
            new Container(
              decoration: BoxDecoration(
                  shape: BoxShape.circle,
                  color: Colors.red
              ),
            ),
          )
      );
    }

    return markers;
  }

  List<Marker> _getAreaMarkers() {
    if (_currentLocation == null) {
      return [];
    }

    return [new Marker(
      width: 230.0,
      height: 230.0,
      point: new LatLng(_currentLocation.latitude, _currentLocation.longitude),
      builder: (ctx) =>
      new Container(
        decoration: BoxDecoration(
            shape: BoxShape.circle,
            color: Colors.blue.withOpacity(0.1),
            border: Border.all(color: Colors.blueAccent)
        ),
      ),
    )];
  }

  Container _getTopContainer() {
    return Container(
      alignment: Alignment.topCenter,
      child: Container(
          padding: EdgeInsets.all(32),
          height: 160,
          alignment: Alignment.center,
          width: double.infinity,
          color: Colors.white.withOpacity(0.8),
          child: Text(
            _getText(),
            style: TextStyle(fontSize: 24),
            textAlign: TextAlign.center,
          )
      ),
    );
  }

  String _getText() {
    if (_currentLocation == null) {
      return '';
    }

    if (_currentType == null) {
      return '';
    }

    if (_answered == false) {
      return "How many ${_currentType.plural} are there 5 km around ${_currentLocation.name}?";
    }

    return "${_entities.length.toString()} ${_currentType.plural}\naround ${_currentLocation.name}";
  }

The FlutterMap itself receives the controller and some MapOptions. We don’t want the map to be interactive (that would include the ability to pan and zoom) because it would make things too easy for the user. If we have a _currentLocation, we want the center to be this location.

Without layers, the map does not display anything. That’s why we need to specify them. At the bottom we want the OSM map to be displayed (Leaflet supports other providers as well).

On top of that, we display a red dot for every entity of the current SearchType.

Last but not least, we display the area circle indicating the radius in which we are searching for the current SearchType. Being semi-transparent, it still displays the underlying red dots.

Result

That’s it, we’re done. Let’s look at the result from the user perspective:

Final words

The existing map plugins make it very easy to embed a map into a Flutter app. Utilizing the enormous amount of free data provided by the Overpass API in combination with a map plugin, we were able to create a quiz game that makes the user guess how many entities of a certain type surround a given town or city.

The application is kept extendable. All of the static data like cities and search types is stored in separate JSON files instead of the code.

GET FULL CODE

Flutter: How to reload a widget after Navigator.pop()

flutter-clutter — Sat, 27 Nov 2021 08:54:27 +0000

When the user navigates from one screen to another, he most likely eventually comes back after he has finished his task on the second screen. The action on his second screen could have affected the first screen, so we want to reload its data after he has popped the route. How do we do that? And can we decide - depending on his actions - if we want to refresh the first screen?

The use case

Let's say we have an app that let's you create, edit and manage notes. There is

A "note overview" screen that lists all of your notes
A "create note" screen that lets you create a new note
An "edit note" screen that lets you edit a created note

Navigator.push and its return value

We assume that the user starts on the "note overview" screen and has the ability to navigate to "create note" and "edit note".

Flutter's navigation concept provides two possibilities to change the current route:

Navigating via an anonymous route via push()
Navigating via a named route via pushNamed()

In both cases, the return value of the method is a Future. That means: we can wait for the result and react accordingly.

One side note, though: if you use pushNamed() which is generally recommended as it leads to all routes being defined at one place and reduces code duplication, you might face a type error. Read this article for further details.

So we know how to navigate to a different route. But how do we trigger this Future's completion? That's where the opposite of push() comes into play: pop().

The resulting navigation would look like this:

In terms of our sample note app, this would apply to the "edit note" route and the "create note" route. Assuming that our data source is remote, we would want to reload the overview once a new note is added or an existing note is edited.

Reacting to a popped route

To capture a Future's return value, we have two options:

Using then()
Using async / await

That means we can either handle the second route being popped like this:

await Navigator.pushNamed(
  context,
  '/note/details',
  arguments: noteId,
);

_refreshData();

Or like this:

Navigator.pushNamed(
  context,
  '/note/details',
  arguments: noteId,
).then((_) {
  _refreshData()
});

Either way is fine. I personally prefer the await way because it prevents unnecessary nesting and is thus much more readable in my opinion.

What about canceling?

We still have one problem, though: if we keep it this way, we reload the first route independent of the second route's cause to pop. The user could have just tapped the back button. We would know that in this case, nothing has changed, so there would be no reason to refresh. We'd refresh the first route anyways. This uses unnecessary computational power (and bandwidth).

Without any further involvement, the usual back button tap performs a Navigator.pop() without any arguments. Good for us, because every other (intentional) pop can be fed with an argument telling the caller if something has changed (if a refresh is necessary). As a caller we can be certain then: if the return value of pop() is null or false, nothing has changed so don't refresh. Otherwise (if it's true), do refresh!

So the edit and create widgets would do something like this:

Navigator.of(context).pop(true);

And the overview widget would react like this:

final bool? shouldRefresh = await Navigator.pushNamed<bool>(
  context,
  '/note/details',
  arguments: noteId,
);

if (shouldRefresh) {
  _refreshData();
}

How does it work with Dialogs and BottomSheets?

Let's assume, we have the ability to apply certain actions to our notes directly on the overview screen by long tapping the respective entries.

Here we basically have the same situation: we want to wait for the user to interact with the BottomSheet and react depending on what his action was. In particular, we want to know, if the action the user has executed influences the note list which would require the application to refresh it in order to present an up-to-date list.

The good thing is that the API to show a BottomSheet is quite similar to push(). showModalBottomSheet has a type argument as well and returns a Future being typed with the given type.

This is what the method call to open the BottomSheet could look like:

final bool? shouldRefresh = showModalBottomSheet<bool>(
  context: context,
  builder: (BuildContext context) {
    return Padding(
      padding: const EdgeInsets.all(24.0),
      child: Column(
        mainAxisSize: MainAxisSize.min,
        children: <Widget>[
          Text(
            'Note options',
            style: Theme.of(context).textTheme.headline5,
          ),
          SizedBox(
            height: 16,
          ),
          ListTile(
            leading: Icon(Icons.star_rounded),
            title: Text('Mark as favorite'),
            onTap: () {
              await _setNoteAsMarked();
              Navigator.pop(true);
            },
          ),
          ListTile(
            leading: Icon(Icons.delete_rounded),
            title: Text('Delete note'),
            onTap: () {
              await _deleteNote();
              Navigator.pop(true);
            },
          ),
        ],
      ),
    );
  },
);

if (shouldRefresh) {
  _refreshData();
}

Like in the above example with push, we wait for the result and only refresh the list of the return value is true (representing the necessity to refresh).

Important: In this code example, we use await to wait for the results of the action. This is supposed to emphasize that we must only refresh the list once the server has responded (assuming we're dealing with a web service here that manages our data). Otherwise, we refresh the list too early, before the new state has been persisted. When dealing with BLoC, we'd need to setup a BlocListener in order to listen for the moment when the API call was successful and then call Navigator.pop(true).

The way to deal with Dialogs is the same as showDialog has the same API as showModalBottomSheet:

final bool? shouldRefresh = showDialog<bool>(
  context: context,
  builder: (BuildContext context) {
    return AlertDialog(
      content: Column(
        mainAxisSize: MainAxisSize.min,
        children: <Widget>[
          ListTile(
            leading: Icon(Icons.star_rounded),
            title: Text('Mark as favorite'),
            onTap: () => null,
          ),
          ListTile(
            leading: Icon(Icons.delete_rounded),
            title: Text('Delete note'),
            onTap: () => null,
          ),
        ],
      ),
    );
  },
);

if (shouldRefresh) {
  _refreshData();
}

What if I have a nested navigation?

Let's say the route you are navigating to, performs a navigation itself like this:

Can we apply the above mentioned pattern as well? Does it make things more complicated?

In fact, we have a call chain here: the first screen calls showModalBottomSheet() and waits for its response. Inside the BottomSheet, Navigator.pushNamed() is called and waited for, which opens up the final route (edit note screen). When this route is popped (e. g. the submit button is tapped), the BottomSheet receives a response (true or false) and forwards this response to Navigator.pop() which eventually arrives at the initial caller.

That means the pattern does not change. Every route is supposed to act independently by returning a specific value to Navigator.pop() being returned to the caller that navigated to the route. That's a good thing because every route navigating to our target route can decide for itself how to react on the return values.

Sometimes, it's also appropriate to return something more meaningful like an enum instead of a bool. This can be the case for a BottomSheet we might want to react differently depending on the chosen option. So we provide an enum to Navigator.pop() in the BottomSheet that gives the calling route the possibility to react depending on the value of this enum.

On the diagram this might look more complicated, but on the code side, there is nothing much going on.

Conclusion

Basically reloading the original route when navigating to a second one is as simple as waiting for the result of the second route (using then() or async / await) which is determined by the argument given to pop(). When using pushNamed with a static type, there are things to consider.

When there is a call chain with more than two routes, the mechanic stays the same for every part of the chain: wait for the return value and react accordingly, which possibly includes forwarding the result.

Opening BottomSheets and Dialogs behaves likewise.

When tapping the back button or dismissing BottomSheets and Dialogs, the caller receives null as the return value and can react conforming to that.

Applying the BLoC pattern in practice

flutter-clutter — Thu, 08 Oct 2020 11:30:10 +0000

There are numerous documentations on the web explaining the purpose of the BLoC pattern and how it's applied to minimal examples. This tutorial aims for the migration of an existing app to this state management architecture.

For that, we use the calculator app whose creation was explained in another tutorial. The whole app's state is managed by a StatefulWidget. Let's tweak it to let the entire state be managed by a BLoC which will lead to a separation of the UI from the business logic.

Motivation

Why do we want such a migration in the first place? As long as everything works, we can keep it that way, can't we?

Yes and no. Of course the current implementation works. However, if we were to change anything, we were unable to say with certainty that the functionality would not break.

This problem is nothing new. That's why people invented software testing. But now we come to the core question: is this implementation even testable? What would our unit-tests look like if we wanted to ensure the current implementation?

The answer is: it's not. Our widget has two responsibilities: displaying the UI and defining the business logic. Changing parts of the UI could possibly break the business logic because it's not strictly separated. Same applies the other way around.

Uncle Bob's opinion on that: a responsibility is defined as a reason to change. Every class or module should have exactly one reason to be changed.

Implementation

Implementing the BLoC pattern involves a lot of boilerplate code (Bloc, Event, State and all of its abstract logic). That's why we make it easy for us and use a prefabricated solution: the bloc library. The package contains several classes that prevents us from implementing the pattern ourselves.

Let's add the dependency to the project:

dependencies:
  flutter:
    sdk: flutter
  flutter_bloc: ^6.0.3
  equatable: ^1.2.5

Events

Let's start with the events. That's quite easy because a glimpse at the UI can pretty quickly make us realize which events we need:

There are four types of buttons the user can press resulting in four distinct interactions:

Pressing a number button (0-9)
Pressing an operator button (+, -, x, /)
Pressing the result calculation button (=)
Pressing the "clear" button (c)

Let's translate these formal requirements into events in the BLoC context:

import 'package:equatable/equatable.dart';
import 'package:meta/meta.dart';

abstract class CalculationEvent extends Equatable {
  const CalculationEvent();
}

class NumberPressed extends CalculationEvent {
  final int number;

  const NumberPressed({@required this.number}) : assert(number != null);

  @override
  List<Object> get props => [number];
}

class OperatorPressed extends CalculationEvent {
  final String operator;

  const OperatorPressed({@required this.operator}) : assert(operator != null);

  @override
  List<Object> get props => [operator];
}

class CalculateResult extends CalculationEvent {
  @override
  List<Object> get props =>  [];
}

class ClearCalculation extends CalculationEvent {
  @override
  List<Object> get props =>  [];
}

The only events that require a parameter are NumberPressed and OperatorPressed (because we need to distinguish which one was taken). The two other events don't have any properties.

States

The states are fairly easy. That's because our UI does not care about what exactly happened. It only cares about the situation when the whole calculation (consisting of two operands, an operator and a result) changes. That's why we only need one actual state saying that the calculation has changed. Additionally we need one initial state. Since we don't have any asynchronous operations, we don't need a "loading" state either.

import 'package:equatable/equatable.dart';
import 'package:meta/meta.dart';

import '../calculation_model.dart';

abstract class CalculationState extends Equatable {
  final CalculationModel calculationModel;

  const CalculationState({@required this.calculationModel}) : assert(calculationModel != null);

  @override
  List<Object> get props => [calculationModel];
}

class CalculationInitial extends CalculationState {
  CalculationInitial() : super(calculationModel: CalculationModel());
}

class CalculationChanged extends CalculationState {
  final CalculationModel calculationModel;

  const CalculationChanged({@required this.calculationModel})
      : assert(calculationModel != null),
        super(calculationModel: calculationModel);

  @override
  List<Object> get props => [calculationModel];
}

Instead of duplicating every property in both of the states, we use a separate class called CalculationModel. This way, if we change something (e.g. displaying the last result as well), we only need to change one model. This is what the model looks like:

import 'package:equatable/equatable.dart';

class CalculationModel extends Equatable {
  CalculationModel({
    this.firstOperand,
    this.operator,
    this.secondOperand,
    this.result,
  });

  final int firstOperand;
  final String operator;
  final int secondOperand;
  final int result;

  @override
  String toString() {
    return "$firstOperand$operator$secondOperand=$result";
  }

  @override
  List<Object> get props => [firstOperand, operator, secondOperand, result];
}

It's important to let this model extend Equatable. Same goes for the states. This is because we need the UI to change only when something has actually changed. We need to define how Dart decides whether there was a change. This is done by defining props.

BLoC

class CalculationBloc extends Bloc<CalculationEvent, CalculationState> {
  CalculationBloc() : super(CalculationInitial());

  @override
  Stream<CalculationState> mapEventToState(
    CalculationEvent event,
  ) async* {
    if (event is ClearCalculation) {
      yield CalculationInitial();
    }
  }
}

There is only one method we need to override: mapEventToState(). This method is responsible for handling incoming events and emitting the new state. We start with the simplest one: ClearCalculation. This makes it emit the initial state again (CalculationInitial).

Next one: OperatorPressed event.

  Future<CalculationState> _mapOperatorPressedToState(
      OperatorPressed event,
      ) async {
    List<String> allowedOperators = ['+', '-', '*', '/'];

    if (!allowedOperators.contains(event.operator)) {
      return state;
    }

    CalculationModel model = state.calculationModel;

    return CalculationChanged(
      calculationModel: CalculationModel(
        firstOperand: model.firstOperand == null ? 0 : model.firstOperand,
        operator: event.operator,
        secondOperand: model.secondOperand,
        result: model.result
      )
    );
  }

We notice something: it's crucial that we use a new instance of the model. If we work with the reference, the bloc library will have problems checking the equality and thus might fail to let the UI know about the update. However, we need to let the new instance have the old values so that we don't lose state when we emit a new CalculationState.

This seems like a lot of boilerplate code if we have a method that handles several cases with several states as outcome. That's why we enhance the CalculationModel by a method called copyWith():

  CalculationModel copyWith({
      int Function() firstOperand,
      String Function() operator,
      int Function() secondOperand,
      int Function() result
    })
  {
    return CalculationModel(
      firstOperand: firstOperand?.call() ?? this.firstOperand,
      operator: operator?.call() ?? this.operator,
      secondOperand: secondOperand?.call() ?? this.secondOperand,
      result: result?.call() ?? this.result,
    );
  }

You might ask yourself why we expect functions and not the date types itself. It's because otherwise null values are treated exactly as not given parameters. I will explain in another article in more detail.

Now we can write the very same method _mapOperatorPressedToState like this:

  Future<CalculationState> _mapOperatorPressedToState(
      OperatorPressed event,
      ) async {
    List<String> allowedOperators = ['+', '-', '*', '/'];

    if (!allowedOperators.contains(event.operator)) {
      return state;
    }

    CalculationModel model = state.calculationModel;

    CalculationModel newModel = state.calculationModel.copyWith(
      firstOperand: () => model.firstOperand == null ? 0 : model.firstOperand,
      operator: () => event.operator
    );

    return CalculationChanged(calculationModel: newModel);
  }

Let's continue with the handling of the CalculateResult event:

  Future<CalculationState> _mapCalculateResultToState(
      CalculateResult event,
    ) async {
    CalculationModel model = state.calculationModel;

    if (model.operator == null || model.secondOperand == null) {
      return state;
    }

    int result = 0;

    switch (model.operator) {
      case '+':
        result = model.firstOperand + model.secondOperand;
        break;
      case '-':
        result = model.firstOperand - model.secondOperand;
        break;
      case '*':
        result = model.firstOperand * model.secondOperand;
        break;
      case '/':
        if (model.secondOperand == 0) {
          CalculationModel resultModel = CalculationInitial().calculationModel.copyWith(
            firstOperand: () => 0
          );

          return CalculationChanged(calculationModel: resultModel);
        }
        result = model.firstOperand ~/ model.secondOperand;
        break;
    }

We just apply the logic, we had before the transformation. Notable here is that a division by zero results in "0" as the first operand for the next calculation.

Now, the biggest event is NumberPressed because depending on the state of calculation we're currently in, pressing a number can have different effects. That's why the handling is a little bit more complex here:

  Future<CalculationState> _mapNumberPressedToState(
    NumberPressed event,
  ) async {
    CalculationModel model = state.calculationModel;

    if (model.result != null) {
      CalculationModel newModel = model.copyWith(
        firstOperand: () => event.number,
        result: () => null
      );

      return CalculationChanged(calculationModel: newModel);
    }

    if (model.firstOperand == null) {
      CalculationModel newModel = model.copyWith(
        firstOperand: () => event.number
      );

      return CalculationChanged(calculationModel: newModel);
    }

    if (model.operator == null) {
      CalculationModel newModel = model.copyWith(
        firstOperand: () => int.parse('${model.firstOperand}${event.number}')
      );

      return CalculationChanged(calculationModel: newModel);
    }

    if (model.secondOperand == null) {
      CalculationModel newModel = model.copyWith(
        secondOperand: () => event.number
      );

      return CalculationChanged(calculationModel: newModel);
    }

    return CalculationChanged(
      calculationModel: model.copyWith(
        secondOperand: () =>  int.parse('${model.secondOperand}${event.number}')
      )
    );
  }

But again, we're just copying off the former behavior from the version of the app without BLoC pattern.

Last thing to do is letting the widget emit the events and react on the emitted states of the BLoC.

  @override
  Widget build(BuildContext context) {
    return MaterialApp(
      debugShowCheckedModeBanner: false,
      title: 'Flutter basic calculator',
      home: Scaffold(
        body: BlocProvider(
          create: (context) {
            return CalculationBloc();
          },
          child: Calculation(),
        ),
      ),
    );
  }

First off, in the main.dart, we need to add a BlocProvider. This is necessary to enable our widget to communicate with the BLoC.

Now, instead of calling setState whenever we recognize an interaction with the UI, we emit an event:

  numberPressed(int number) {
    context.bloc<CalculationBloc>().add(NumberPressed(number: number));
  }

  operatorPressed(String operator) {
    context.bloc<CalculationBloc>().add(OperatorPressed(operator: operator));
  }

  calculateResult() {
    context.bloc<CalculationBloc>().add(CalculateResult());
  }

  clear() {
    context.bloc<CalculationBloc>().add(ClearCalculation());
  }

Now, if we want the UI to display the result accordingly, we need to wrap the ResultDisplay with a BlocBuilder this gives us the ability to react on an emitted state.

BlocBuilder<CalculationBloc, CalculationState>(
  builder: (context, CalculationState state) {
    return ResultDisplay(
      text: _getDisplayText(state.calculationModel),
    );
  },
),
...
String _getDisplayText(CalculationModel model) {
  if (model.result != null) {
    return '${model.result}';
  }

  if (model.secondOperand != null) {
    return '${model.firstOperand}${model.operator}${model.secondOperand}';
  }

  if (model.operator != null) {
    return '${model.firstOperand}${model.operator}';
  }

  if (model.firstOperand != null) {
    return '${model.firstOperand}';
  }

  return "${model.result ?? 0}";
}

Final words

The BLoC pattern is fantastic way of separating UI concerns from business logic concerns. Also, it enables the developer to manage state leaving the widget only as a reactive presentation layer. It might be a little bit confusing at first, but once you get the fundamental thoughts, it is not so hard to apply this pattern. I hope this little example cleared it up a little bit.

If you want the full source, there is the repository before (current master) and after the BLoC PR:

GET FULL CODE WITH BLOC

GET FULL CODE WITHOUT BLOC

Smartphone movement speedometer in Flutter

flutter-clutter — Wed, 30 Sep 2020 19:04:15 +0000

Communicating with the hardware of a phone can be tricky in Flutter because it abstracts from the hardware and even the OS. However, regarding the accelerometer, there is an official package that is extremely simple to use.

Let's utilize this package to show a speedometer that indicates the speed the smartphone is currently moving at.

Implementation

Before we start to draw anything onto the screen, let's take care of capturing the current velocity of the phone's movement using the sensors package.

dependencies:
  flutter:
    sdk: flutter
  sensors: '>=0.4.2+5 <2.0.0'

Now that we have the package added to our project, we want to use its API.

import 'dart:math';

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

import 'speedometer.dart';

class SpeedometerContainer extends StatefulWidget {
  @override
  _SpeedometerContainerState createState() => _SpeedometerContainerState();
}

class _SpeedometerContainerState extends State<SpeedometerContainer> {
  double velocity = 0;
  double highestVelocity = 0.0;

  @override
  void initState() {
    userAccelerometerEvents.listen((UserAccelerometerEvent event) {
      _onAccelerate(event);
    });
    super.initState();
  }

  void _onAccelerate(UserAccelerometerEvent event) {
    double newVelocity = sqrt(
        event.x * event.x + event.y * event.y + event.z * event.z
    );

    if ((newVelocity - velocity).abs() < 1) {
      return;
    }

    setState(() {
      velocity = newVelocity;

      if (velocity > highestVelocity) {
        highestVelocity = velocity;
      }
    });
  }

  @override
  Widget build(BuildContext context) {
    return Scaffold(
      backgroundColor: Colors.black,
      body: Stack(
        children: [
          Container(
            padding: EdgeInsets.only(bottom: 64),
            alignment: Alignment.bottomCenter,
            child: Text(
              'Highest speed:\n${highestVelocity.toStringAsFixed(2)} km/h',
              style: TextStyle(
                  color: Colors.white
              ),
              textAlign: TextAlign.center,
            )
          ),
          Center(
            child: Speedometer(
              speed: velocity,
              speedRecord: highestVelocity,
            )
          )
        ]
      )
    );
  }
}

This widget wraps the actual speedometer (that has a visual representation on the screen). It captures the current velocity and forwards this value to the widget that is to be created.

During initState(), we bind a listener to userAccelerometerEvents, which is a Stream of events. The package description says about the event:

UserAccelerometerEvents [...] describe the velocity of the device, but don't include gravity. They can also be thought of as just the user's affect on the device.

This is very good. It's the velocity and not the acceleration so we don't need to add or multiply anything, we can use the value as it is. Also, the gravity is not included.

The only thing we need to do, is to boil the acceleration down to one value. That's because at the moment, the velocity is represented as x, y and z direction. That looks like a Vector3 so if we just take the square root of the sum of the different values squared, we should be good to go.

Because we don't want the needle to move panicky whenever the velocity changes by a fraction of a minimal value, we decide to update it only when the change compared to the former value is greater than 1. We also store the highest velocity so that we can display the current record.

Let's continue with creating the actual Speedometer widget.

import 'dart:math';

import 'package:flutter/material.dart';

class Speedometer extends StatelessWidget {
  Speedometer({
    @required this.speed,
    @required this.speedRecord,
    this.size = 300
  });

  final double speed;
  final double speedRecord;
  final double size;

  @override
  Widget build(BuildContext context) {
    return CustomPaint(
      painter: SpeedometerPainter(
        speed: speed,
        speedRecord: speedRecord
      ),
      size: Size(size, size)
    );
  }
}

It's fairly simple: we let speed and speedRecord be the only constructor arguments so that the widget we have just created can inject its sensor data into it. We also expect a Size that determines the size the speedometer has on the screen (it's a square). It defaults to 300 and is used as the size argument for our CustomPainter.

class SpeedometerPainter extends CustomPainter {
  SpeedometerPainter({
    this.speed,
    this.speedRecord
  });

  final double speed;
  final double speedRecord;

  Size size;
  Canvas canvas;
  Offset center;
  Paint paintObject;

  @override
  void paint(Canvas canvas, Size size) {}

  @override
  bool shouldRepaint(CustomPainter oldDelegate) {
    return true;
  }

Before we start drawing the actual speedometer, let's list all the parts of it:

Outer circle: This is the circle that has the markers and speed texts inside of it
Inner circle: Purely decorative circle having the current speed as text inside of it
Speed markers: The markers indicating the different speeds to give the viewer an orientation what the needle points at
Speed marker texts: The labels showing the different speeds
Speed indicator bars: In addition to the needle and the text, we want to have bars at the outside of the circle indicating the current speed. Makes it look cooler
Needle: Pointing towards the current speed
Ghost needle: Pointing towards the speed record
Needle holder: The circle at the center that mimics a component holding the needle
Speed text: A text below the needle holder that shows the current speed

Let's start with an initialization so that we don't have to provide Canvas and Size argument to every private method and can use the member variables of or SpeedometerPainter instead.

void _init(Canvas canvas, Size size) {
  this.canvas = canvas;
  this.size = size;
  center = size.center(Offset.zero);
  paintObject = Paint();
}

void _drawOuterCircle() {
  paintObject
    ..color = Colors.red
    ..strokeWidth = 2.5
    ..style = PaintingStyle.stroke;

  canvas.drawCircle(
      size.center(Offset.zero),
      size.width / 2.2,
      paintObject
  );
}

The inner circle is just an outline, so we switch the PaintStyle to stroke:

void _drawInnerCircle() {
  paintObject
    ..color = Colors.red.withOpacity(0.4)
    ..strokeWidth = 1.0
    ..style = PaintingStyle.stroke;

  canvas.drawCircle(
    size.center(Offset.zero),
    size.width / 4,
    paintObject
  );
}

Now it's time to draw the markers around the circle as well as the speed labels. We want the important ones like every 10 km/h to appear bigger than the ones in between.

void _drawMarkers() {
  paintObject.style = PaintingStyle.fill;

  for (double relativeRotation = 0.15; relativeRotation <= 0.851; relativeRotation += 0.01) {
    double normalizedDouble = double.parse((relativeRotation - 0.15).toStringAsFixed(2));
    int normalizedPercentage = (normalizedDouble * 100).toInt();
    bool isBigMarker = normalizedPercentage % 10 == 0;

     _drawRotated(
        relativeRotation,
        () => _drawMarker(isBigMarker)
      );

      if (isBigMarker)
        _drawRotated(
          relativeRotation,
          () => _drawSpeedScaleText(relativeRotation, normalizedPercentage.toString())
        );
  }
}

We iterate over a relative rotation value and draw the respective markers at certain values. relativeRotation describes the amount of rotation along the outer circle (0 means zero rotation, starting at the bottom center, 1 means 360 ° rotation being again at the bottom center).

To make only the the important speed markers appear bigger, we need to determine, if in the current iteration, we have a percentage that is dividable by ten without a rest. We achieve that by normalizing the percentage using an Integer. This is necessary because the double precision would produce values like 0.150000001 instead. There might be a more elegant way than this data type conversion.

Let's talk about the _drawRotated() method we need to properly draw the marker.

  void _drawRotated(double angle, Function drawFunction) {
    canvas.save();
    canvas.translate(center.dx, center.dy);
    canvas.rotate(angle * pi * 2);
    canvas.translate(-center.dx, -center.dy);
    drawFunction();
    canvas.restore();
  }

This is something we are going to need for multiple visual components of the speedometer. We can imagine this like you're drawing on a piece of paper. Instead of drawing something rotated, we can only draw straight. But what we can do is to rotate the sheet of paper. So we move the sheet of paper to the center and rotate it by an angle. If we then finish drawing and rotate the sheet back (canvas.restore()), we have drawn a rotated object.

We use that function with a callback called _drawMarker:

void _drawMarker(bool isBigMarker) {
  paintObject
    ..color = Colors.red
    ..shader = null;

  Path markerPath = Path()
    ..addRect(
      Rect.fromLTRB(
        center.dx - size.width / (isBigMarker ? 200 : 300),
        center.dy + (size.width / 2.2),
        center.dx + size.width / (isBigMarker ? 200 : 300),
        center.dy + (size.width / (isBigMarker ? 2.5 : 2.35)),
      )
    );

  canvas.drawPath(markerPath, paintObject);
}

We draw the marker to the bottom center. The rotation function being wrapped around this makes it start at 15 % and end at 85 % of the circle. If isBigMarker is true, we decrease the size.

Every size used in this needs to be relative to the size.width (or size.height). This way we ensure that the whole painting will be responsive depending on the given size.

void _drawSpeedScaleText(double rotation, String text) {
  TextSpan span = new TextSpan(
    style: new TextStyle(
      fontWeight: FontWeight.bold,
      color: Colors.red,
      fontSize: size.width / 20
    ),
    text: text
  );
  TextPainter textPainter = TextPainter(
    text: span,
    textDirection: TextDirection.ltr,
    textAlign: TextAlign.center
  );

  textPainter.layout();

  final textCenter = Offset(
    center.dx,
    size.width - (size.width / 5.5) + (textPainter.width / 2)
  );

  final textTopLeft = Offset(
    textCenter.dx - (textPainter.width / 2),
    textCenter.dy - (textPainter.height / 2)
  );

  textPainter.paint(canvas, textTopLeft);
}

We use a TextPainter to paint our labels to the canvas.

Well, this is not exactly what we wanted. But why is that? Well imagine rotating the sheet of paper and drawing the text. It will always point towards you making it only readable when you rotate the sheet. We need to fix this by not only rotating the canvas round its center by the given amount but also rotate the sheet around the center of the text by the same amount but in the other direction. This way we correct the rotated text.

canvas.save();

// Rotate the canvas around the position of the text so that the text is oriented properly

canvas.translate(
  textCenter.dx,
  textCenter.dy
 );
canvas.rotate(-rotation * pi * 2);
canvas.translate(
  -textCenter.dx,
  -textCenter.dy
);

textPainter.paint(canvas, textTopLeft);

canvas.restore();

Now let's draw the speed bars around the outer circle that mimic the current speed.

void _drawSpeedIndicators(Size size) {
  for (double percentage = 0.15; percentage <= 0.85; percentage += 4 / (size.width)) {
    _drawSpeedIndicator(percentage);
  }

  for (double percentage = 0.15; percentage < 0.15 + (speed / 100); percentage += 4 / (size.width)) {
    _drawSpeedIndicator(percentage, true);
  }
}

void _drawSpeedIndicator(double relativeRotation, [bool highlight = false]) {
  paintObject.shader = null;
  paintObject.strokeWidth = 1;
  paintObject.style = PaintingStyle.stroke;
  paintObject.color = Colors.white54;

  if (highlight) {
    paintObject.color = Color.lerp(
      Colors.yellow, Colors.red, (relativeRotation - 0.15) / 0.7
    );
    paintObject.style = PaintingStyle.fill;
  }

  Path markerPath = Path()
    ..addRect(
      Rect.fromLTRB(
        center.dx - size.width / 40,
        size.width - (size.width / 30),
        center.dx,
        size.width - (size.width / 100)
      )
    );

  _drawRotated(relativeRotation, () {
    canvas.drawPath(markerPath, paintObject);
  });
}

We draw the outlines for every speed indicator that is not reached by the current speed. For every other indicator, we fill it with a color that is interpolated from yellow to red depending on how near it is to 0 / 70.

The needles are still missing! Remember: we want one needle to display the current speed and another to display the speed record.

_drawNeedle(
  0.15 + (speedRecord / 100),
  Colors.white54,
  size.width / 120
);
_drawNeedle(
  0.15 + (speed / 100),
  Colors.red,
  size.width / 70
);

void _drawNeedle(double rotation, Color color, double width) {
  paintObject
    ..style = PaintingStyle.fill
    ..color = color;

  Path needlePath = Path()
    ..moveTo(center.dx - width, center.dy)
    ..lineTo(center.dx + width, center.dy)
    ..lineTo(center.dx, center.dy + size.width / 2.5)
    ..moveTo(center.dx - width, center.dy);

  _drawRotated(rotation, () {
    canvas.drawPath(needlePath, paintObject);
  });
}

The needle is just a triangle from the center to the outer circle. Because we need to draw two needles, we make the method abstract and expect a rotation, a color and a width.

The speed needle is based on speed whereas the ghost needle is based on speedRecord.

void _drawNeedleHolder() {
  RadialGradient gradient = RadialGradient(
    colors: [Colors.orange, Colors.red, Colors.red, Colors.black],
    radius: 1.2,
    stops: [0.0, 0.7, 0.9, 1.0]
  );

  paintObject
    ..color = Colors.blueGrey
    ..shader = gradient.createShader(
      Rect.fromCenter(
        center: center,
        width: size.width / 20,
        height: size.width / 20
      )
    );

  canvas.drawCircle(
    size.center(Offset.zero),
    size.width / 15,
    paintObject
  );
}

The needle is nothing more than a circle with a radial fill.

void _drawSpeed() {
  TextSpan span = new TextSpan(
    style: new TextStyle(
      fontWeight: FontWeight.bold,
      color: Colors.red,
      fontSize: size.width / 12
    ),
    text: '${speed.toStringAsFixed(0)}'
  );

  TextPainter textPainter = TextPainter(
    text: span,
    textDirection: TextDirection.ltr,
    textAlign: TextAlign.center
  );

  textPainter.layout();

  final textCenter = Offset(
    center.dx,
    center.dy + (size.width / 10) + (textPainter.width / 2)
  );

  final textTopLeft = Offset(
    textCenter.dx - (textPainter.width / 2),
    textCenter.dy - (textPainter.width / 2)
  );

  textPainter.paint(canvas, textTopLeft);
}

The text of the current speed is the rounded value of speed and displayed below the needle holder.

Conclusion

The sensor package makes it very easy to fetch the current velocity of the phone's movement. Using a CustomPainter we were able to quickly draw a speedometer that displays it in a fancy way!

FULL CODE

Flutter tutorial: image magnifier

flutter-clutter — Wed, 23 Sep 2020 12:46:48 +0000

Especially when dragging markers across an image, it's quite common to show a magnifier that enlarges the area because it's covered by the finger. Let's have a look at how to implement that in Flutter.

Our goal

This above description is very broad. Let's go into further detail by defining the key features of our magnifier:

There is a half-transparent circle than can be dragged across the image
Once it's being dragged, the magnifier appears on the top left
Whenever the circle interferes with the magnifier, it jumps to the top right
The magnifier enlarges the area of the underlying image by a factor that is definable
Once the drag ends, the magnifier disappears
This does not only work for images but for every widget

Implementation

We start by implementing a sample screen that contains the image we want to add the possibility to zoom on. For this, we use the most popular test image: Lena Forsén, better known as Lenna.

  @override
  Widget build(BuildContext context) {
    return Stack(
      children: [
        Image(
          image: AssetImage('assets/lenna.png')
        )
      ],
    );
  }

We use a Stack widget because we want to put the touch bubble and the magnifier on top later on.

The touch bubble

Now we need the touch bubble the user should be able to position on the part of the image that should be magnified.

class _SampleImageState extends State<SampleImage> {
  static const double touchBubbleSize = 20;

  Offset position;
  double currentBubbleSize;
  bool magnifierVisible = false;

  @override
  void initState() {
    currentBubbleSize = touchBubbleSize;
    SystemChrome.setEnabledSystemUIOverlays([SystemUiOverlay.bottom]);
    super.initState();
  }

  @override
  Widget build(BuildContext context) {
    return Stack(
      children: [
        Magnifier(
          position: position,
          visible: magnifierVisible,
          child: Image(
            image: AssetImage('assets/lenna.png')
          ),
        ),
        _getTouchBubble()
      ],
    );
  }

  Positioned _getTouchBubble() {
    return Positioned(
        top: position == null ? 0 : position.dy - currentBubbleSize / 2,
        left: position == null ? 0 : position.dx - currentBubbleSize / 2,
        child: GestureDetector(
          child: Container(
            width: currentBubbleSize,
            height: currentBubbleSize,
            decoration: BoxDecoration(
              shape: BoxShape.circle,
              color: Theme.of(context).accentColor.withOpacity(0.5)
            ),
          )
        )
    );
  }

We need to store the position of the touch bubble so that we can provide that piece of information to the magnifier. This is necessary so that the magnifier can only enlarge the particular area that is determined by the touch bubble.

We also have a static size of the touch bubble which determines the base size the bubble returns to when no interaction is happening. We also need the actual current size that can differ when the user drags the bubble. To highlight the drag event we want the bubble to grow by 50 %.

We could implement it like above and just extract the visual description of the touch bubble into its own method which resides in the sample image widget. However, it's a good idea to put it into its own widget.

This will make it look like this:

import 'package:flutter/material.dart';

class TouchBubble extends StatelessWidget {
  TouchBubble({
    @required this.position,
    this.bubbleSize
  });

  final Offset position;
  final double bubbleSize;

  @override
  Widget build(BuildContext context) {
    return Positioned(
      top: position == null ? 0 : position.dy - bubbleSize / 2,
      left: position == null ? 0 : position.dx - bubbleSize / 2,
      child: GestureDetector(
        child: Container(
          width: bubbleSize,
          height: bubbleSize,
          decoration: BoxDecoration(
            shape: BoxShape.circle,
            color: Theme.of(context).accentColor.withOpacity(0.5)
          ),
        )
      )
    );
  }
}

So far so good. But yet, there is no interaction possible:

The touch bubble is visible at the top left because that is the fallback value for the top and left property of the Positioned widget inside our TouchBubble class.

In order to add interactivity to our magnifier, we let the TouchBubble expect some callbacks in its constructor:

import 'package:flutter/material.dart';

class TouchBubble extends StatelessWidget {
  TouchBubble({
    this.position,
    @required this.onStartDragging,
    @required this.onDrag,
    @required this.onEndDragging,
    @required this.bubbleSize,
  }) : assert(onStartDragging != null),
       assert(onDrag != null),
       assert(onEndDragging != null),
       assert(bubbleSize != null && bubbleSize > 0);

  final Offset position;
  final double bubbleSize;
  final Function onStartDragging;
  final Function onDrag;
  final Function onEndDragging;

  @override
  Widget build(BuildContext context) {
    return Positioned(
      ...
      child: GestureDetector(
        onPanStart: (details) => onStartDragging(details.globalPosition),
        onPanUpdate: (details) => onDrag(details.globalPosition),
        onPanEnd: (_) => onEndDragging(),
        ...
      )
    );
  }
}

Now we have three new additional arguments: onStartDragging, onDrag and onEndDragging. The behavior that is triggered by these functions, will be defined in the parent widget. We annotate all of them (expect for position because we have a fallback) as @required which tells our IDE to warn us if we omit this argument. Additionally, we provide asserts for runtime errors to occur at the correct place if we ignore the suggestions of our IDE.

onStartDragging and onDrag are expected to be provided with the new absolute (global) position. onEndDragging does not expect any argument.

Our new SampleImage widget looks like this:

import 'package:flutter/material.dart';
import 'package:flutter/services.dart';
import 'package:flutter_magnifier/touch_bubble.dart';

class SampleImage extends StatefulWidget {
  @override
  _SampleImageState createState() => _SampleImageState();
}

class _SampleImageState extends State<SampleImage> {
  static const double touchBubbleSize = 20;

  Offset position;
  double currentBubbleSize;
  bool magnifierVisible = false;

  @override
  void initState() {
    currentBubbleSize = touchBubbleSize;
    SystemChrome.setEnabledSystemUIOverlays([SystemUiOverlay.bottom]);
    super.initState();
  }

  @override
  Widget build(BuildContext context) {
    return Stack(
      children: [
        Image(
          image: AssetImage('assets/lenna.png')
        ),
        TouchBubble(
          position: position,
          bubbleSize: currentBubbleSize,
          onStartDragging: _startDragging,
          onDrag: _drag,
          onEndDragging: _endDragging,
        )
      ],
    );
  }

  void _startDragging(Offset newPosition) {
    setState(() {
      magnifierVisible = true;
      position = newPosition;
      currentBubbleSize = touchBubbleSize * 1.5;
    });
  }

  void _drag(Offset newPosition) {
    setState(() {
      position = newPosition;
    });
  }

  void _endDragging() {
    setState(() {
      currentBubbleSize = touchBubbleSize;
      magnifierVisible = false;
    });
  }
}

The position is updated on drag start and on drag update. When the dragging starts, the mag is made visible and increases its size by 50 %. When dragging has ended, the size is turned back to normal and the magnifier is turned invisible.

It leads to a UI that behaves like this:

The magnifier

Before we jump into the implementation, let's think for a second, what magnifying actually means. We take an image, scale it up, move the image to where the center of the mag is and then crop it so that only the inner part of the mag shows the translated image.

The translation is also influenced by the scale factor. Visually this can be explained like this:

Let's first create a new widget that represents our magnifier:

class Magnifier extends StatefulWidget {
  const Magnifier({
    @required this.child,
    @required this.position,
    this.visible = true,
    this.scale = 1.5,
    this.size = const Size(160, 160)
  }) : assert(child != null);

  final Widget child;
  final Offset position;
  final bool visible;
  final double scale;
  final Size size;

  @override
  _MagnifierState createState() => _MagnifierState();
}

class _MagnifierState extends State<Magnifier> {
  Size _magnifierSize;
  double _scale;
  Matrix4 _matrix;

  @override
  void initState() {
    _magnifierSize = widget.size;
    _scale = widget.scale;
    _calculateMatrix();

    super.initState();
  }

  @override
  void didUpdateWidget(Magnifier oldWidget) {
    super.didUpdateWidget(oldWidget);

    _calculateMatrix();
  }

  @override
  Widget build(BuildContext context) {
    return Stack(
      children: [
        widget.child,
        if (widget.visible && widget.position != null)
          _getMagnifier(context)
      ],
    );
  }

  void _calculateMatrix() {
    if (widget.position == null) {
      return;
    }

    setState(() {
      double newX = widget.position.dx - (_magnifierSize.width / 2 / _scale);
      double newY = widget.position.dy - (_magnifierSize.height / 2 / _scale);

      final Matrix4 updatedMatrix = Matrix4.identity()
        ..scale(_scale, _scale)
        ..translate(-newX, -newY);

      _matrix = updatedMatrix;
    });
  }
}

We have a few constructor arguments here. The most relevant are child and position. Because we want this feature to work with every widget, we need this widget to be provided (child parameter). In order to determine which part of the underlying widget should be magnified, we also let it require a position parameter.

visible is used to only display it when the user drags the bubble. scale and size should be self-explanatory and have a default value.

The crucial business logic here is the _calculateMatrix() method because it determines scaling and translation based on the position of the touch bubble. We take the identity matrix and use the scale and translation method to update it. Important: we need to use the center of the touch bubble as the anchor. That's why we subtract half of the height and the width to determine the position.

Okay, now the part of drawing the actual magnifier is still missing. We call _getMagnifier() but yet, there is no implementation.

Widget _getMagnifier(BuildContext context) {
  return Align(
    alignment: Alignment.topLeft,
    child: ClipOval(
      child: BackdropFilter(
        filter: ImageFilter.matrix(_matrix.storage),
        child: Container(
            width: _magnifierSize.width,
            height: _magnifierSize.height,
            decoration: BoxDecoration(
              color: Colors.transparent,
              shape: BoxShape.circle,
              border: Border.all(color: Colors.blue, width: 2)
        ),
      ),
    ),
  );
}

This deserves some explanation. Now, the crucial widget here is BackdropFilter. This filter takes a filter and a child. It applies the given filter to the child. The filter we use is matrix. This lets us apply the calculated matrix to the child. It's very important to wrap it in a ClipOval because we only want a sized circle to be seen and not the whole scaled and translated duplication of our original image.

In order to improve the possibility to place the bubble exactly where we want to, we can add a crosshair to the magnifier. This requires us to replace the Container by a self-drawn widget.

import 'package:flutter/material.dart';

class MagnifierPainter extends CustomPainter {
  const MagnifierPainter({
    @required this.color,
    this.strokeWidth = 5
  });

  final double strokeWidth;
  final Color color;

  @override
  void paint(Canvas canvas, Size size) {
    _drawCircle(canvas, size);
    _drawCrosshair(canvas, size);
  }

  void _drawCircle(Canvas canvas, Size size) {
    Paint paintObject = Paint()
      ..style = PaintingStyle.stroke
      ..strokeWidth = strokeWidth
      ..color = color;

    canvas.drawCircle(
      size.center(
        Offset(0, 0)
      ),
      size.longestSide / 2, paintObject
    );
  }

  void _drawCrosshair(Canvas canvas, Size size) {
    Paint crossPaint = Paint()
      ..strokeWidth = strokeWidth / 2
      ..color = color;

    double crossSize = size.longestSide * 0.04;

    canvas.drawLine(
      size.center(Offset(-crossSize, -crossSize)),
      size.center(Offset(crossSize, crossSize)),
      crossPaint
    );

    canvas.drawLine(
      size.center(Offset(crossSize, -crossSize)),
      size.center(Offset(-crossSize, crossSize)),
      crossPaint
    );
  }

  @override
  bool shouldRepaint(CustomPainter oldDelegate) {
    return true;
  }
}

We start by drawing a circle of the given size but in stroke mode so we only draw the outline. After that, we draw the cross by using the center and shifting it by 4 % of the magnifier size to the top left and bottom right.

Now the _getMagnifier() method in the Magnifier class looks like this:

  Widget _getMagnifier(BuildContext context) {
    return Align(
      alignment: Alignment.topLeft,
      child: ClipOval(
        child: BackdropFilter(
          filter: ImageFilter.matrix(_matrix.storage),
          child: CustomPaint(
            painter: MagnifierPainter(
              color: Theme.of(context).accentColor
            ),
            size: _magnifierSize,
          ),
        ),
      ),
    );
  }

What we want to take care of now is that the magnifier jumps to the top right when our touch bubble's position interferes with the magnifier.

  Alignment _getAlignment() {
    if (_bubbleCrossesMagnifier()) {
      return Alignment.topRight;
    }

    return Alignment.topLeft;
  }

  bool _bubbleCrossesMagnifier() => widget.position.dx < widget.size.width &&
    widget.position.dy < widget.size.height;

Instead of assigning Alignment.topLeft statically to the magnifier, we decide whether to use topLeft or topRight based on its position.

Now we need to add an extra block to the calculateMatrix() method:

if (_bubbleCrossesMagnifier()) {
  final box = context.findRenderObject() as RenderBox;
  newX -= ((box.size.width - _magnifierSize.width) / _scale);
}

Whenever the conditions are met, we influence the matrix translation by shifting the newX by the whole width subtracted by the mag width because that is exactly the amount by which the magnifier moves when the alignment is changed from left to right.

Closing comment

Using the expensive but handy Widget BackdropFilter and a little bit of matrix calculation, we were able to implement a magnifier that is able to enlarge every child widget given a position. The magnifier is located at the top left but jumps out of the way when our touch collides with the position of the magnifier.

You can see it in action (and see the code) by having a look at my edge detection project. The magnifier is used on touch bubbles that mimic the detected edges around a dynamic image.

How to create the popular Matrix effect (digital rain) in Flutter

flutter-clutter — Thu, 17 Sep 2020 11:14:16 +0000

I recently found out it's been over twenty years since the release of The Matrix. The digital rain of letters is probably known to almost everyone even those who haven't watched the movie. Let's give it a try and mimic this effect using Flutter.

Having seen a few videos of the effect, I can summarize it as follows:

It consists of numerous "character rains" that all start at the top of the screen with a random horizontal position
Every now and then a new rain spawns
The latest character is always white, the colors before are green and there is a gradient so that the first characters fade out
Background is black
The characters are random characters including letters, numbers and other characters
The vertical rains differ in the length (height) of visible characters

Implementation

Let's start with the implementation of a single vertical rain. Once we have that, we let the whole effect be a composition of multiple rains.

import 'package:flutter/material.dart';

class VerticalTextLine extends StatefulWidget {
  VerticalTextLine({
    this.speed = 12.0,
    this.maxLength = 10,
    Key key
  }) : super(key: key);

  final double speed;
  final int maxLength;

  @override
  _VerticalTextLineState createState() => _VerticalTextLineState();
}

class _VerticalTextLineState extends State<VerticalTextLine> {
  List<String> _characters = ['T', 'E', 'S', 'T'];

  @override
  Widget build(BuildContext context) {

    return Column(
      mainAxisSize: MainAxisSize.min,
      mainAxisAlignment: MainAxisAlignment.start,
      children: _getCharacters(),
    );
  }

  List<Widget> _getCharacters() {
    List<Widget> textWidgets = [];

    for (var character in _characters) {
      textWidgets.add(
          Text(character, style: TextStyle(color: Colors.white),)
      );
    }

    return textWidgets;
  }
}

This is a very simple start. Just a widget that displays a static vertical line of text at the top of its container.

The constructor arguments are speed and maxLength, which will later determine, how quickly the rain runs down the screen and what the maximum length of the visible text is. This way we have a variance in position, speed and length.

Now, instead of displaying a plain white text, we want the last character to be white and the text before that to have the above described gradient.

@override
Widget build(BuildContext context) {
  List<Color> colors = [Colors.transparent, Colors.green, Colors.green, Colors.white];

  double greenStart;
  double whiteStart = (_characters.length - 1) / (_characters.length);

  if (((_characters.length - _maxLength) / _characters.length) < 0.3) {
    greenStart = 0.3;
  }
  else {
    greenStart = (_characters.length - _maxLength) / _characters.length;
  }

  List<double> stops = [0, greenStart, whiteStart, whiteStart];

  return _getShaderMask(stops, colors);
}

ShaderMask _getShaderMask(List<double> stops, List<Color> colors) {
  return ShaderMask(
    shaderCallback: (Rect bounds) {
      return LinearGradient(
        begin: Alignment.topCenter,
        end: Alignment.bottomCenter,
        stops: stops,
        colors: colors,
      ).createShader(bounds);
    },
    blendMode: BlendMode.srcIn,
    child: Column(
      mainAxisSize: MainAxisSize.min,
      mainAxisAlignment: MainAxisAlignment.start,
      children: _getCharacters(),
    )
  );
}

For the purpose of displaying the text as a gradient, we use something called a ShaderMask. This can be used to fade out the edge of a child. The shaderCallback parameter expects a function that receives a bounding rectangle and returns a Shader. Good thing the Gradient class provides a createShader() method. This enables us to control the shading behavior by using a Gradient.

We use blendMode.srcIn. That means: take the source (the child parameter) and use the destination (shaderCallback return value) as a mask. This leads to the text staying the way it is with the gradient only defining its color.

The stops argument of a Gradient is a list of doubles that represent the relative position across the gradient, at which a certain color (which is defined at the same position in the colors argument) should begin. So if the stops list contained 0 and 0.5 and the colors list contained Colors.white and Colors.red, the gradient would start with white and interpolate to red until half of its height and would be red from there to the bottom.

We want it to start with transparent color and then interpolate to green (at the character that is located maxLength characters before the end of the column). This color should last until the penultimate visible character where it changes to white.

If the whole character list is smaller than maxLength, we just take 30 % as a static point for the green color to start.

Next step is to turn this text with a static length into a growing column.

class _VerticalTextLineState extends State<VerticalTextLine> {
  int _maxLength;
  Duration _stepInterval;
  List<String> _characters = [];
  Timer timer;

  @override
  void initState() {
    _maxLength = widget.maxLength;
    _stepInterval = Duration(milliseconds: (1000 ~/ widget.speed));
    _startTimer();
    super.initState();
  }
  void _startTimer() {
    timer = Timer.periodic(_stepInterval, (timer) {
      final _random = new Random();
      final list = ['A', 'B', 'C'];
      String element = list[_random.nextInt(list.length)];

      setState(() {
        _characters.add(element);
      });
    });
  }

...

speed is interpreted in the way that 1.0 means 1 character per second. So it's the frequency of characters added per second.

Instead of having a static list of allowed characters, we can also use a random int to create a String from a UTF character code:

String element = String.fromCharCode(
  _random.nextInt(512)
);

Now we need to create a widget that composes multiple of our vertical text lines:

import 'dart:async';
import 'dart:math';

import 'package:flutter/material.dart';
import 'package:flutter_matrix_effect/vertical_text_line_current.dart';

class MatrixEffect extends StatefulWidget {
  @override
  State<StatefulWidget> createState() {
    return _MatrixEffectState();
  }
}

class _MatrixEffectState extends State<MatrixEffect> {
  List<Widget> _verticalLines = [];
  Timer timer;

  @override
  void initState() {
    _startTimer();
    super.initState();
  }

  @override
  Widget build(BuildContext context) {
    return Stack(
      children: _verticalLines
    );
  }

  void _startTimer() {
    timer = Timer.periodic(Duration(milliseconds: 300), (timer) {
      setState(() {
        _verticalLines.add(
            _getVerticalTextLine(context)
        );
      });
    });
  }

  @override
  void dispose() {
    timer.cancel();
    super.dispose();
  }

  Widget _getVerticalTextLine(BuildContext context) {
    Key key = GlobalKey();
    return Positioned(
      key: key,
      left: Random().nextDouble() * MediaQuery.of(context).size.width,
      child: VerticalTextLine(
        speed: 1 + Random().nextDouble() * 9,
        maxLength: Random().nextInt(10) + 5
      ),
    );
  }
}

Every 300 milliseconds, we add a new VerticalTextLine to the list.

Since we're dealing with a list of widgets here, it's mandatory to use the key parameter of the widgets we add. Otherwise, if we manipulated the list by removing one element, a reference would be missing which would result in no widget being properly removed from the list (and from the widget tree).

We place the rains by using a Positioned widget with a random left parameter. Also, we let the speed vary from 1 to 10 and the maximum length from 5 to 15.

We still have one problem: Every vertical text line we spawn, stays in the widget tree forever. It might fade out over time because of our gradient, but it will always occupy memory. This leads to the app becoming very laggy after a short period of time. We need the rain to decide when to disappear and tell its parent.

  VerticalTextLine({
    @required this.onFinished,
    this.speed = 12.0,
    this.maxLength = 10,
    Key key
  }) : super(key: key);

  final double speed;
  final int maxLength;
  final VoidCallback onFinished;

...

  void _startTimer() {
    timer = Timer.periodic(_stepInterval, (timer) {
      final _random = new Random();
      String element = String.fromCharCode(
        _random.nextInt(512)
      );

      final box = context.findRenderObject() as RenderBox;

      if (box.size.height > MediaQuery.of(context).size.height * 2) {
        widget.onFinished();
        return;
      }

      setState(() {
        _characters.add(element);
      });
    });
  }

We achieve the above mentioned exit condition by using a callback that is being called from the vertical text line. The condition to disappear is when the size of the rendered widget (the column) is twice as high as the current screen height. This way, the moment of disappearing should be smooth enough not to be noticed by the viewer. The timer does not need to be cancelled manually, because we do this onDispose anyways.

The onFinished callback we provide to the VerticalTextLine looks as follows:

onFinished: () {
  setState(() {
    _verticalLines.removeWhere((element) {
      return element.key == key;
    });
  });
},

Conclusion

Using a ShaderMask, a LinearGradient, a Timer and a GlobalKey, we were able to quickly mimic the well-known visual effect from The Matrix.

GET FULL CODE

How to simulate an LED display in Flutter

flutter-clutter — Sat, 05 Sep 2020 14:43:22 +0000

I have recently taken a ride with a train. I had a closer look at the LED display that shows the current station, the destination and the current time. It made me wonder if it's possible to simulate that in Flutter. Let's find out!

The simulated LED display should display text dynamically. We don't want to create our own LED font in which the "LED combination" of every letter is statically stored. We want an LED display that can display every text with every font.

So let's implement a screen that has a TextField in which the user can input text. Above that we display the very same text on a simulated LED display.

Theory

What we are doing here, is a classic rasterisation. So basically something you see every day millions of times, whether you know it or not. That's because every display is based on pixels. No matter how good the resolution of an image is and even if it's a vector image, at the time of being displayed, the image needs to be mapped on a discrete dimension that is limited by physics. That doesn't only happen to images, of course, but also to text. Today's displays have such a high resolution that the viewer does not really notice that. Anti-aliasing also makes it appear so smooth that pixels don't come to one's mind.

But how can we access the pixels of a widget in Flutter? Well that's not that easy, because this is a rather low-level part of the rendering engine the developer is not supposed to access. So there are no APIs that let us access that.

So we need to think of another way. Instead of directly accessing the pixels of a rendered widget, we should rather take note of the Image package. This package has a getPixelSafe() method, allowing the caller to access a pixel given the x and y arguments.

Okay, we now know how to access a pixel in some format of a third party package. How is that going to help? Well, if we manage to convert a text into an image, we can access its pixels from there. Good news: our good old friend, the Canvas class in combination with PictureRecorder is able to create a Picture with a toImage() function.

There are a more steps in between which make it a rather complex conversion chain, so let's visualize what's going on there:

You don't need to understand every single step. What's important to remember, though: directly accessing pixels of Widgets is not possible. Thus we need to to an intermediate conversion to a rendered image. This requires a canvas and an external package. Let's head over to the implementation. Then everything will become clearer.

The implementation

We are going to have a bunch of classes to make the code more readable. The heart of our app will be the DisplaySimulator this widget represents the part that actually mimics the LED display. Because we want to have full control and draw the display ourselves, we also need a CustomPainter. This one will be called DisplayPainter.

Additionally, we need a component that takes a string and converts it to a two-dimensional list of pixels. This is what the ToPixelsConverter will be responsible of.

Let's start with the DisplaySimulator:

import 'dart:typed_data';
import 'package:flutter/material.dart';
import 'package:flutter/services.dart';

const canvasSize = 100.0;

class DisplaySimulator extends StatefulWidget {
  DisplaySimulator({
    this.text,
    this.border = false,
    this.debug = false
  });

  final String text;
  final bool border;
  final bool debug;


  @override
  _DisplaySimulatorState createState() => _DisplaySimulatorState();
}

class _DisplaySimulatorState extends State<DisplaySimulator> {
  ByteData imageBytes;
  List<List<Color>> pixels;

  @override
  Widget build(BuildContext context) {
    _obtainPixelsFromText(widget.text);

    return Column(
      children: <Widget>[
        SizedBox(height: 96,),
        _getDebugPreview(),
        SizedBox(height: 48,),
        _getDisplay(),
      ],
    );
  }

  Widget _getDebugPreview() {
    if (imageBytes == null || widget.debug == false) {
      return Container();
    }

    return Image.memory(
      Uint8List.view(imageBytes.buffer),
      filterQuality: FilterQuality.none,
      width: canvasSize,
      height: canvasSize,
    );
  }

  Widget _getDisplay() {
    return Container();
  }

  void _obtainPixelsFromText(String text) async {
    // Here we will set imageBytes and pixels
  }
}

The DisplaySimulator has three constructor arguments: the text which is obviously the text that is supposed to be displayed on the simulated display. The second argument border determines whether a border should be shown around the display. This can give a nice look. Third one is debug. As we discovered in the theory part, a lot of conversions happen from the initial string to the final effect. The crucial one is probably from the string to the byte data of the image. To make debugging easier, we add the possibility to display this intermediate conversion.

As a first iteration we only show the debugging part, not yet the actual display. So _getDisplay() only returns an empty Container whereas _getDebugPreview() returns an Image made from the buffer we expect to get from our ToPixelsConverter.

We need the imageBytes for the debugging part and the pixels for the display.

Okay, we know what the result of the conversion should look like. Let's make a model class for that conversion result:

class ToPixelsConversionResult {
  ToPixelsConversionResult({
    this.imageBytes,
    this.pixels
  });

  final ByteData imageBytes;
  final List<List<Color>> pixels;
}

Now we implement the converter from string to pixels:

import 'dart:typed_data';
import 'dart:ui' as ui;
import 'package:flutter/material.dart';
import 'package:flutter/services.dart';
import 'package:flutter_digital_text_display/text_to_picture_converter.dart';
import 'package:image/image.dart' as imagePackage;

class ToPixelsConverter {
  ToPixelsConverter.fromString({
    @required this.string,
    @required this.canvasSize,
    this.border = false
  });

  String string;
  Canvas canvas;
  bool border;
  final double canvasSize;

  Future<ToPixelsConversionResult> convert() async {
    final ui.Picture picture = TextToPictureConverter.convert(
        text: this.string, canvasSize: canvasSize
    );
    final ByteData imageBytes = await _pictureToBytes(picture);
    final List<List<Color>> pixels = _bytesToPixelArray(imageBytes);

    return ToPixelsConversionResult(
      imageBytes: imageBytes,
      pixels: pixels
    );
  }

  Future<ByteData> _pictureToBytes(ui.Picture picture) async {
    final ui.Image img = await picture.toImage(canvasSize.toInt(), canvasSize.toInt());
    return await img.toByteData(format: ui.ImageByteFormat.png);
  }

  List<List<Color>> _bytesToPixelArray(ByteData imageBytes) {
    List<int> values = imageBytes.buffer.asUint8List();
    imagePackage.Image decodedImage = imagePackage.decodeImage(values);
    List<List<Color>> pixelArray = new List.generate(canvasSize.toInt(), (_) => new List(canvasSize.toInt()));

    for (int i = 0; i < canvasSize.toInt(); i++) {
      for (int j = 0; j < canvasSize.toInt(); j++) {
        int pixel = decodedImage.getPixelSafe(i, j);
        int hex = _convertColorSpace(pixel);
        pixelArray[i][j] = Color(hex);
      }
    }

    return pixelArray;
  }

  int _convertColorSpace(int argbColor) {
    int r = (argbColor >> 16) & 0xFF;
    int b = argbColor & 0xFF;
    return (argbColor & 0xFF00FF00) | (b << 16) | r;
  }
}

We have one named constructor that has three arguments:

string: This is required as it's the text we are going to display. We are just going to pass through the argument from the parent widget
canvasSize: The size of the canvas the text is rendered on. This is important is in combination with the font size it determines the size and count of the pixels
border: Boolean that determines whether to display a border around the display. Also passed through from the parent

The only public method of this class is convert(). It takes the string and let it be converted to a Picture by the TextToPictureConverter, we are going to implement in a minute. This conversion is necessary to get the ByteData. This piece of information is used to iterate over the pixels, which are then turned into Color objects. If we store the original color, we can simulate multicolored LED displays.

It's worth noting that the image library uses the KML color format which has also a hexadecimal representation, but the red and blue part is switched. Thus we need to convert #AABBGGRR to #AARRGGBB. This is essentially what _convertColorSpace() does.

We use Monospace font family to make every character have the same width and height.

Great, now that we have the conversion ready, we can use it to display our debug widget:

void _obtainPixelsFromText(String text) async {
  ToPixelsConversionResult result = await ToPixelsConverter.fromString(
    string: text, border: widget.border, canvasSize: canvasSize
  ).convert();

  setState(() {
    this.imageBytes = result.imageBytes;
    pixels = result.pixels;
  });
}

Now, in order to test everything, let's quickly hack a Home widget that embeds the DisplaySimulator and puts a TextField underneath to allow the user to change the text that's being displayed:

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

class Home extends StatefulWidget {
  @override
  _HomeState createState() => _HomeState();
}

class _HomeState extends State<Home> {
  String text;

  @override
  void initState() {
    text = '';
    super.initState();
  }

  @override
  Widget build(BuildContext context) {
    return SingleChildScrollView(
      child: Align(
        alignment: Alignment.topCenter,
        child: Column(
          children: [
            DisplaySimulator(
              text: text,
              border: false,
              debug: true,
            ),
            SizedBox(height: 48),
            _getTextField()
          ],
        )
      )
    );
  }

  Container _getTextField() {
    BorderSide borderSide = BorderSide(color: Colors.blue, width: 4);
    InputDecoration inputDecoration = InputDecoration(
      border: UnderlineInputBorder(borderSide: borderSide),
      disabledBorder: UnderlineInputBorder(borderSide: borderSide),
      enabledBorder: UnderlineInputBorder(borderSide: borderSide),
      focusedBorder: UnderlineInputBorder(borderSide: borderSide),
    );

    return Container(
      width: 200,
      child: TextField(
        maxLines: null,
        enableSuggestions: false,
        textAlign: TextAlign.center,
        style: TextStyle(
          color: Colors.yellow,
          fontSize: 32,
          fontFamily: "Monospace"
        ),
          decoration: inputDecoration,
          onChanged: (val) {
            setState(() {
              text = val;
            });
          },
      )
    );
  }
}

Okay, if we start the app, we see the input field but not the debug widget. Although it seems that it sometimes flickers and appears. That's an issue being discussed on Github and the fix seems fairly simple: using the argument gaplessPlayback:

Widget _getDebugPreview() {
  if (imageBytes == null || widget.debug == false) {
    return Container();
  }

  return Image.memory(
    Uint8List.view(imageBytes.buffer),
    gaplessPlayback: true,
    filterQuality: FilterQuality.none,
    width: canvasSize,
    height: canvasSize,
  );
}

Awesome. We enter text and are able to see a rendered image containing the very same text. Now we are going to use the pixel array to display the actual LED display.

We need to implement the getDisplay() method of the DisplaySimulator widget. At first, I've tried to do that using the widget tree with something like this:

Widget _getDisplay() {
  if (pixels == null) {
    return Container();
  }

  return Container(
    color: Colors.black87,
    child:
    Row(
      children: [
        for (int i = 0; i < pixels.length; i++)
          Column(
            children: [
            for (int j = 0; j < pixels.length; j++)
              Container(
                decoration: BoxDecoration(
                  borderRadius: BorderRadius.all(Radius.circular(4)),
                  color: pixels[i][j],
                ),
                height: 4,
                width: 4,
              ),
            ]
          )
      ],
    )
  );
}

Unfortunately, the performance was very poor. The display was lagging every time I typed a new character. Also, the the text easily went across the border. I then decided to go for the CustomPaint approach. This makes our getDisplay() method rather small:

Widget _getDisplay() {
  if (pixels == null) {
    return Container();
  }

  return CustomPaint(
    size: Size.square(MediaQuery.of(context).size.width),
    painter: DisplayPainter(pixels: pixels, canvasSize: canvasSize)
  );
}

The display logic can be found in the CustomPainter called DisplayPainter:

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

class DisplayPainter extends CustomPainter {
  DisplayPainter({
    this.pixels, this.canvasSize
  });

  List<List<Color>> pixels;
  double canvasSize;

  @override
  void paint(Canvas canvas, Size size) {
    if (pixels == null) {
      return;
    }

    canvas.drawRect(Rect.fromLTWH(0, 0, size.width, size.height), Paint()..color = Colors.black);

    double widthFactor = canvasSize / size.width;

    Paint rectPaint = Paint()..color = Colors.black;
    Paint circlePaint = Paint()..color = Colors.yellow;

    for (int i = 0; i < pixels.length; i++) {
      for (int j = 0; j < pixels[i].length; j++) {

        var rectSize = 1.0 / widthFactor;
        var circleSize = 0.3 / widthFactor;

        canvas.drawRect(
            Rect.fromCenter(
                center: Offset(
                    i.toDouble() * rectSize + rectSize / 2,
                    j.toDouble() * rectSize + rectSize / 2
                ),
                width: rectSize,
                height: rectSize
            ),
            rectPaint
        );

        if (pixels[i][j].opacity < 0.3) {
          continue;
        }

        canvas.drawCircle(
            Offset(
              i.toDouble() * rectSize  + rectSize / 2 - circleSize / 2,
              j.toDouble() * rectSize  + rectSize / 2 - circleSize / 2,
            ),
            circleSize,
            circlePaint
        );
      }
    }
  }

  @override
  bool shouldRepaint(CustomPainter oldDelegate) {
    return true;
  }
}

We start with a mono-colored display. For this, we only draw every pixel with an opacity of more than 30 %. This lets us get rid of the anti-aliased pixels. We then use a static color (yellow in this case) to draw every pixel of the canvas based image. We then stretch the painted image across the hole width, which is the screen width (because we call it with MediaQuery.of(context).size). This makes it look like this:

Very cool! Our first working display.

If we remove the condition that only display pixels with opacity more that 30 % and let the paint color be yellow with the luminance determined by the opacity of the pixel, we can invert the effect.

canvas.drawCircle(
    Offset(
      i.toDouble() * rectSize  + rectSize / 2 - circleSize / 2,
      j.toDouble() * rectSize  + rectSize / 2 - circleSize / 2,
    ),
    circleSize,
    circlePaint..color = Colors.yellow.withOpacity(1-pixels[i][j].computeLuminance())
);

This looks as follows:

You might wonder, if this works for images too. The good news: we are handling ByteData here. Actually, that's the same format that is returned by rootBundle.load. So if we rewrite the code a little bit, we can also display images.

Future<ByteData> _pictureToBytes(ui.Picture picture) async {
  return await rootBundle.load('assets/flutter-logo.png');
}

A mono-colored display is cool as long as we only have plain text. But the Flutter logo looks a little bit sad like this. And what about Emojis? If we type them now, we only get a yellow blob. So how about actually using the color information we previously stored in the pixels list?

canvas.drawCircle(
    Offset(
      i.toDouble() * rectSize  + rectSize / 2 - circleSize / 2,
      j.toDouble() * rectSize  + rectSize / 2 - circleSize / 2,
    ),
    circleSize,
    circlePaint..color = pixels[i][j]
);

Final words

Accessing the raw pixels of a widget is not easy and in the high abstraction level Flutter provides us, not possible. However, it can be achieved using a trick: a conversion chain from text to canvas to picture actually allows us to access the pixels. With this piece of data we can easily create a simulated LED display by arranging the pixels with a little bit of distance next to each other and drawing them as circles.

Maybe you have additional ideas what cool effects can be achieved using this information?

GET FULL CODE

Flutter tutorial: Audio player in retro design

flutter-clutter — Sun, 30 Aug 2020 11:42:46 +0000

Who remembers good old audio tapes? In my opinion although they are technically outdated, they are still very fascinating. Compared to modern media, one could actually see what's happening inside.

To appreciate this awesome invention, let's implement an actually working audio player that mimics the visuals and behavior of a good old tape!

The goal

The above animation describes our goal better than 1000 words, but let's define the features more formally:

There is a tape at the top and a control panel below
One can choose an audio file from the phone by tapping the eject button (the one on the right)
The title and author are extracted from the meta information and written on the blank label of the tape When a song is chosen and the play button is tapped, the pins of the tape rotate counter-clockwise (and the song actually plays)
The left tape reel shrink whereas the right tape reel grow according to the current position of the song
The pause button just pauses the song. When tapping "play" afterwards, it's possible to resume
The stop button rewinds the song to the beginning
A button of the control panel indicates being tapped by shrinking. When one button is tapped, every other button goes back to the original size

The implementation

We are going to start with the basic skeleton: a Tape widget. This widget will have the responsibility of painting the tape using the parent's space.

class Tape extends StatefulWidget {
  @override
  _TapeState createState() => _TapeState();
}

class _TapeState extends State<Tape> with SingleTickerProviderStateMixin {
  AnimationController _controller;

  @override
  void initState() {
    super.initState();

    _controller = new AnimationController(
      duration: const Duration(milliseconds: 2000),
      vsync: this
    );

    Tween<double> tween = Tween<double>(
      begin: 0.0, end: 1.0
    );

    tween.animate(_controller);
  }

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

  @override
  Widget build(BuildContext context) {
    return Column(
      mainAxisSize: MainAxisSize.min,
      children: [
        SizedBox(
          width: 300,
          height: 200,
          child: AnimatedBuilder(
            builder: (BuildContext context, Widget child) {
              return CustomPaint(
                painter: TapePainter(),
              );
            },
            animation: _controller,
          ),
        ),
      ],
    );
  }

  void stop() {
  }

  void pause() {
  }

  void play() {
  }

  void choose() {
  }
}

This is the first basic iteration of our Tape class. We already know we want to rotate the pins to make it look like the cassette is being played. That's why we initialize an AnimationController with a duration of 2 seconds and attach a tween animating a double from 0.0 to 1.0 that represents the amount of rotation.

The build method returns a SizedBox with a width ratio of 3:2 whose child is an AnimatedBuilder containing our CustomPaint. AnimatedBuilder because we want our tape to be repainted every time the animation is updated so that we have the rotating pins at the center.

Drawing the tape

The code won't compile because we're missing the actual TapePainter. Let's take care of that.

class TapePainter extends CustomPainter {
  double holeRadius;
  Offset leftHolePosition;
  Offset rightHolePosition;
  Path leftHole;
  Path rightHole;
  Path centerWindowPath;

  Paint paintObject;
  Size size;
  Canvas canvas;

  @override
  void paint(Canvas canvas, Size size) {
    this.size = size;
    this.canvas = canvas;

    holeRadius = size.height / 12;
    paintObject = Paint();

    _initHoles();
    _initCenterWindow();
  }


  void _initCenterWindow() {
    Rect centerWindow = Rect.fromLTRB(size.width * 0.4, size.height * 0.37, size.width * 0.6, size.height * 0.55);
    centerWindowPath = Path()..addRect(centerWindow);
  }

  void _initHoles() {
    leftHolePosition = Offset(size.width * 0.3, size.height * 0.46);
    rightHolePosition = Offset(size.width * 0.7, size.height * 0.46);

    leftHole = Path()..addOval(
      Rect.fromCircle(
        center: leftHolePosition,
        radius: holeRadius
      )
    );

    rightHole = Path()..addOval(
      Rect.fromCircle(
        center: rightHolePosition,
        radius: holeRadius
      )
    );
  }

  @override
  bool shouldRepaint(CustomPainter oldDelegate) {
    return true;
  }
}

Before we actually draw the cassette, we need to initialize certain things. That's because we want to extract the draw process of every part of the tape into a single method to keep the code readable and maintainable. Because we don't want to provide the very same arguments over and over again to every method, we initialize them at the beginning and make them member variables of the class.

We let the position of the holes depend on the width we have. This way, we prevent a completely static painting. The center window also depends on the measurements we're given.

The holes and their radii are needed for drawing several parts because the holes will be cut through them. Same for the window.

_drawTape() {
  RRect tape = RRect.fromRectAndRadius(
    Rect.fromLTRB(0, 0, size.width, size.height),
    Radius.circular(16)
  );

  Path tapePath = Path()..addRRect(tape);

  tapePath = Path.combine(PathOperation.difference, tapePath, leftHole);
  tapePath = Path.combine(PathOperation.difference, tapePath, rightHole);
  tapePath = Path.combine(PathOperation.difference, tapePath, centerWindowPath);

  canvas.drawShadow(tapePath, Colors.black, 3.0, false);
  paintObject.color = Colors.black;
  paintObject.color = Color(0xff522f19).withOpacity(0.8);
  canvas.drawPath(tapePath, paintObject);
}

We start by adding a new private method called _drawTape() that actually draws the tape which is nothing else but a rounded rectangle covering the hole size with the holes and the window being cut into the shape. We also draw a shadow to make it look a little bit more realistic.

...
Path _cutCenterWindowIntoPath(Path path) {
  return Path.combine(PathOperation.difference, path, centerWindowPath);
}

_cutHolesIntoPath(Path path) {
  path = Path.combine(PathOperation.difference, path, leftHole);
  path = Path.combine(PathOperation.difference, path, rightHole);

  return path;
}
...

Because we are going to need the same cutting algorithm for other parts of the tape as well, we are extracting it into separate methods called _cutCenterWindowIntoPath() and _cutHolesIntoPath(). Then we replace the Path.combine calls by our new methods.

Next, we are going to paint the label on top of the tape.

void _drawLabel() {
  double labelPadding = size.width * 0.05;
  Rect label = Rect.fromLTWH(labelPadding, labelPadding, size.width - labelPadding * 2, size.height * 0.7);
  Path labelPath = Path()..addRect(label);
  labelPath = _cutHolesIntoPath(labelPath);
  labelPath = _cutCenterWindowIntoPath(labelPath);

  Rect labelTop = Rect.fromLTRB(label.left, label.top + label.height * 0.2, label.right, label.bottom - label.height * 0.1);
  Path labelTopPath = Path()..addRect(labelTop);
  labelTopPath = _cutHolesIntoPath(labelTopPath);
  labelTopPath = _cutCenterWindowIntoPath(labelTopPath);

  paintObject.color = Color(0xffd3c5ae);
  canvas.drawPath(labelPath, paintObject);
  paintObject.color = Colors.red;
  canvas.drawPath(labelTopPath, paintObject);
}

The label consists of a grayish rectangle that provides some space for the actual text label describing the current song at the top and a red body. The label also needs to be cut at the position of the holes and the window.

It's starting to look like an actual cassette. Let's add the window which is nothing but a hole yet. On top of that, let's add this black rectangle that is a typical visual part of an audio tape.

void _drawCenterWindow() {
  paintObject.color = Colors.black38;
  canvas.drawPath(centerWindowPath, paintObject);
}

void _drawBlackRect() {
  Rect blackRect = Rect.fromLTWH(size.width * 0.2, size.height * 0.31, size.width * 0.6, size.height * 0.3);
  Path blackRectPath = Path()
    ..addRRect(
        RRect.fromRectXY(blackRect, 4, 4)
    );

  blackRectPath = Path.combine(PathOperation.difference, blackRectPath, leftHole);
  blackRectPath = Path.combine(PathOperation.difference, blackRectPath, rightHole);
  blackRectPath = _cutCenterWindowIntoPath(blackRectPath);

  paintObject.color = Colors.black.withOpacity(0.8);
  canvas.drawPath(blackRectPath, paintObject);
}

Since we already have the path of the window, drawing a semi-transparent rectangle on top of that is an easy task.

The rectangle is also a very basic shape. Just a rounded rectangle whose dimensions are defined by fractions of the given size. The holes and the window need to be cut here as well.

We're almost done with painting the basic components of the cassette. A tiny detail that's still missing are the circles in which the pins will be rotating. So let's indicate that by painting a white ring where the holes are located.

void _drawHoleRings() {
  Path leftHoleRing = Path()..addOval(
    Rect.fromCircle(
      center: leftHolePosition,
      radius: holeRadius * 1.1
    )
  );

  Path rightHoleRing = Path()..addOval(
    Rect.fromCircle(
      center: rightHolePosition,
      radius: holeRadius * 1.1
    )
  );

  leftHoleRing = Path.combine(PathOperation.difference, leftHoleRing, leftHole);
  rightHoleRing = Path.combine(PathOperation.difference, rightHoleRing, rightHole);

  paintObject.color = Colors.white;
  canvas.drawPath(leftHoleRing, paintObject);
  canvas.drawPath(rightHoleRing, paintObject);
}

Nothing really special here. We take the hole positions we initialized at the beginning and draw circles that have a slightly higher radius than the holes and then we subtract the holes from these shapes which results in only the outlines.

Now we're done with the static part of the tape. The dynamic parts are: the rotating pins, the tape reels and the text label showing author and title.

Adding animated parts

We're going to prepare the tape so that it expects values that are going to be defined by the animation later but can be static for now.

...
AnimatedBuilder(
  builder: (BuildContext context, Widget child) {
    return CustomPaint(
      painter: TapePainter(
        rotationValue: _controller.value,
        title: 'Rick Astley - Never Gonna Give You Up',
        progress: 0
      ),
    );
  },
  animation: _controller,
),
...
class TapePainter extends CustomPainter {
  TapePainter({
    @required this.rotationValue,
    @required this.title,
    @required this.progress,
  });

  double rotationValue;
  String title;
  double progress;
...

Let's take care of the label first as it's the easiest part.

void _drawTextLabel() {
  TextSpan span = new TextSpan(style: new TextStyle(color: Colors.black), text: title);
  TextPainter textPainter = TextPainter(
    text: span,
    textDirection: TextDirection.ltr,
    textAlign: TextAlign.center
  );

  double labelPadding = size.width * 0.05;

  textPainter.layout(
    minWidth: 0,
    maxWidth: size.width - labelPadding * 2,
  );

  final offset = Offset(
    (size.width - textPainter.width) * 0.5,
    (size.height - textPainter.height) * 0.12
  );

  textPainter.paint(canvas, offset);
}

We are using a TextPainter to achieve what we want. We let the text be drawn across the width of the label with a little padding. The text has a center alignment.

Next, we'll take care of the rotating pins.

void _drawTapePins() {
  paintObject.color = Colors.white;
  final int pinCount = 8;

  for (var i = 0; i < pinCount; i++) {
    _drawTapePin(leftHolePosition, rotationValue + i / pinCount);
    _drawTapePin(rightHolePosition, rotationValue + i / pinCount);
  }
}

void _drawTapePin(Offset center, double angle) {
  _drawRotated(Offset(center.dx, center.dy), -angle, () {
    canvas.drawRect(
      Rect.fromLTWH(
        center.dx - 2,
        center.dy - holeRadius,
        4,
        holeRadius / 4,
      ),
      paintObject
    );
  });
}

void _drawRotated(Offset center, double angle, Function drawFunction) {
  canvas.save();
  canvas.translate(center.dx, center.dy);
  canvas.rotate(angle * pi * 2);
  canvas.translate(-center.dx, -center.dy);
  drawFunction();
  canvas.restore();
}

This one is a little bit trickier so I'm gonna explain everything step by step.

In general, we need the possibility to draw something being rotated by a certain angle. Then we can draw the same pin several times but each time rotated a little bit more around the center which in sum generates the whole. In order to do that, we add a new method called _drawRotated() which rotates the canvas before drawing in order to achieve the effect of something being drawn rotated by a given angle.

_drawTapePin() draws a pin which is nothing more than a rectangle going from the (given) center up. The height is the holeRadius we initialized earlier. We use minus angle because we want it to rotate counter-clockwise.

The _drawTapePin() method is called as often as the pin count (in our case 8). In the loop the rotation value is multiplied with the current loop index divided by the pin count. This way, the pins are evenly spread across the circle.

The last dynamic parts are the moving tape reels.

void _drawTapeReels() {
  Path leftTapeRoll = Path()..addOval(
    Rect.fromCircle(
      center: leftHolePosition,
      radius: holeRadius * (1 - progress) * 5
    )
  );

  Path rightTapeRoll = Path()..addOval(
    Rect.fromCircle(
      center: rightHolePosition,
      radius: holeRadius * progress * 5
    )
  );

  leftTapeRoll = Path.combine(PathOperation.difference, leftTapeRoll, leftHole);
  rightTapeRoll = Path.combine(PathOperation.difference, rightTapeRoll, rightHole);

  paintObject.color = Colors.black;
  canvas.drawPath(leftTapeRoll, paintObject);
  canvas.drawPath(rightTapeRoll, paintObject);
}

It's simple: we just draw two black circles that mimic the tape reels. The radius of the circles directly depend on the progress argument we added earlier. It's supposed to range from 0 to 1. The left one's radius is defined by (1 - progress), which makes it shrink, the right one just uses progress which makes it grow.

Adding the control panel

Now we have a tape that can theoretically animate based on a song that is played. Unfortunately, there is no user interaction possible yet because we have no UI parts that support it. Next step: adding a control panel.

class TapeButton extends StatelessWidget {
  TapeButton({
    @required this.icon,
    @required this.onTap,
    this.isTapped = false
  });

  final IconData icon;
  final Function onTap;
  final bool isTapped;

  @override
  Widget build(BuildContext context) {
    return GestureDetector(
      child: Container(
        width: isTapped ? 53.2 : 56,
        height: isTapped ? 60.8 : 64,
        decoration: BoxDecoration(
          color: Colors.black,
          borderRadius: BorderRadius.all(Radius.circular(8))
        ),
        child: Center(
          child: Icon(icon, color: Colors.white)
        ),
      ),
      onTap: onTap
    );
  }
}

First, we need a tappable button. Whether it's tapped or not will be determined by the parent widget because we want only one button to be tapped at a time. Once another button is tapped, every other button is untapped. Being tapped is visualized by a smaller button.

enum TapeStatus { initial, playing, pausing, stopping, choosing }

class Tape extends StatefulWidget {
  @override
  _TapeState createState() => _TapeState();
}

class _TapeState extends State<Tape> with SingleTickerProviderStateMixin {
  AnimationController _controller;
  TapeStatus _status = TapeStatus.initial;
  ...
  @override
  Widget build(BuildContext context) {
    return Column(
      mainAxisSize: MainAxisSize.min,
      children: [
        SizedBox(
          width: 300,
          height: 200,
          child: AnimatedBuilder(
            builder: (BuildContext context, Widget child) {
              return CustomPaint(
                painter: TapePainter(
                  rotationValue: _controller.value,
                  title: 'Rick Astley - Never Gonna Give You Up',
                  progress: 0
                ),
              );
            },
            animation: _controller,
          ),
        ),
        SizedBox(height: 40),
        Row(
          mainAxisAlignment: MainAxisAlignment.center,
          children: [
            TapeButton(icon: Icons.play_arrow, onTap: play, isTapped: _status == TapeStatus.playing),
            SizedBox(width: 8),
            TapeButton(icon: Icons.pause, onTap: pause, isTapped: _status == TapeStatus.pausing),
            SizedBox(width: 8),
            TapeButton(icon: Icons.stop, onTap: stop, isTapped: _status == TapeStatus.stopping),
            SizedBox(width: 8),
            TapeButton(icon: Icons.eject, onTap: choose, isTapped: _status == TapeStatus.choosing),
          ],
        )
      ],
    );
  }

We create a new enum that holds the different possible states. We use this enum to trigger the isTapped argument of the constructors of the TapeButton widget we have just created.

Awesome, we have a control panel now. What's left is to give the buttons actual functionality.

dependencies:
  flutter:
    sdk: flutter
  file_picker: ^1.13.3
  audioplayers: ^0.15.1
  flutter_ffmpeg: ^0.2.10

For this, we're going to need three new dependencies. file_picker is used to let the user pick an audio file when the eject button is tapped. audioplayers lets us play, pause and stop the audio file. flutter_ffmpeg can extract meta information from a file. This is necessary because we want to display the author and the title of the current song.

import 'package:audioplayers/audioplayers.dart';
import 'package:file_picker/file_picker.dart';
import 'package:flutter/material.dart';
import 'package:flutter_retro_audioplayer/tape_button.dart';
import 'package:flutter_ffmpeg/flutter_ffmpeg.dart';
...
class _TapeState extends State<Tape> with SingleTickerProviderStateMixin {
  AnimationController _controller;
  TapeStatus _status = TapeStatus.initial;
  AudioPlayer _audioPlayer;
  String _url;
  String _title;
  double _currentPosition = 0.0;
...
  void stop() {
    setState(() {
      _status = TapeStatus.stopping;
      _currentPosition = 0.0;
    });
    _controller.stop();
    _audioPlayer.stop();
  }

  void pause() {
    setState(() {
      _status = TapeStatus.pausing;
    });
    _controller.stop();
    _audioPlayer.pause();
  }

  void play() async {
    if (_url == null) {
      return;
    }

    setState(() {
      _status = TapeStatus.playing;
    });
    _controller.repeat();
    _audioPlayer.play(_url);
  }

Stop, Play and Pause are fairly simple compared to the choose() method so we start with them.

By tapping "stop" we want the status to be TapeStatus.stopping. That will make every other button release. We set _currentPosition to 0 which influences our visual audio tape and makes the tape reels reset. We want the _controller to stop. This stops the animation of rotating pins. Lastly, we let the audio playback stop.

Pause behaves accordingly with the difference of not setting everything to 0 so that the playback can be resumed from there.

Play stats the animation and the playback. It has a check for _url which is the file url that is returned when picking a file. If no file is there then no playback should happen. It starts _controller.repeat() because we want the animation of the pins to be ongoing.

choose() async {
  stop();

  setState(() {
    _status = TapeStatus.choosing;
  });
  File file = await FilePicker.getFile(
      type: FileType.audio
  );

  _url = file.path;
  _audioPlayer.setUrl(_url);

  final FlutterFFprobe _flutterFFprobe = new FlutterFFprobe();
  Map<dynamic, dynamic> mediaInfo = await _flutterFFprobe.getMediaInformation(_url);

  String title = mediaInfo['metadata']['title'];
  String artist = mediaInfo['metadata']['artist'];
  int duration = mediaInfo['duration'];

  _audioPlayer.onPlayerCompletion.listen((event) {
    stop();
  });

  _audioPlayer.onAudioPositionChanged.listen((event) {
    _currentPosition = event.inMilliseconds / duration;
  });

  setState(() {
    _title = "$artist - $title";
    _status = TapeStatus.initial;
  });
}

The executing of the choose method starts with executing stop(). That's because we want everything to be reset before we play the new song. We then use FilePicker to let the user pick a file. The resulting url is set as a member variable and then used to gather media information using FlutterFFprobe. We then start listening to two events: when the playback is completed, the tape should rewind. That's done by calling stop(). Whenever the position is changed, the _currentPosition variable should be updated with a relative value from 0 to 1. This is necessary for the painting of our tape. Lastly, the _title string is updated with actual metadata from the audio file.

TapePainter(
  rotationValue: _controller.value,
  title: _title,
  progress: _currentPosition
)

Now that we have any dynamic value available, we replace the static values and call the constructor of our painter with the actual values.

Conclusion

That's it, we're done with the implementation.

With the help of three packages and a CustomPainter, we were able to implement a cross-platform audio player that mimics an audio tape. The audio tape has animating parts that depend on the current position of the song.

GET FULL CODE

Burning paper effect in Flutter

flutter-clutter — Fri, 21 Aug 2020 11:24:13 +0000

Perhaps you know this effect from the cult series "Bonanza" from television in the 1960s. If you don't, imagine a sheet of paper burning from the middle to the edges of the viewpoint. This can be used as a splash screen or a screen transition. This is what it looks like:

The goal

Let’s describe what we want the result to look like so that we can work on the bullet points during the implementation:

There is a solid (of a given color) that spans over the screen
From the center, a hole is growing that reveals what is underneath
The hole’s shape is a polygon shape that grows irregularly
A black contour around the edge of the hole indicates the burning or burnt area
In order to make the effect more realistic, a gradient around the hole is placed

Implementation

In order to make our burning paper animation configurable, we need to wrap it with a widget. This way, we can individualize the animation using the constructor’s arguments.

class BurningPaper extends StatefulWidget {
  BurningPaper({
    this.color = Colors.white,
    this.duration = const Duration(seconds: 3),
    this.pointAmount = 30
  });

  final Color color;
  final Duration duration;
  final int pointAmount;

  @override
  _BurningPaperState createState() => _BurningPaperState();
}

class _BurningPaperState extends State<BurningPaper> with SingleTickerProviderStateMixin {
  AnimationController _controller;
  Animation _animation;
  List<double> points;

  @override
  void initState() {
    super.initState();
    // Here we need to initialize everything
  }

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

  @override
  Widget build(BuildContext context) {
    // Here we need to add the painter to the widget tree
    return Container();
  }
}

What we want to make customizable is the color of the paper, the time it takes for the paper to be burnt and the amount of points that are used to describe the hole. The latter influences the shape of the hole. More points lead to more spiky shape.

We already prepared the methods initState() and build() which we are going to fill with our logic in the following.

But before we write the logic for any kind of information, we are going to write the heart of our logic: the painter. This piece of code is responsible for painting the burnt paper being dependent on the current state of the animation and the given parameters.

class BurningPaperPainter extends CustomPainter {
  BurningPaperPainter({
    @required this.color,
    @required this.points,
  });

  Color color;
  List<double> points;

  @override
  void paint(Canvas canvas, Size size) {
    Path hole = Path();
    Path outline = Path();
    Offset center = Offset(size.width / 2, size.height / 2);

    _buildPaths(hole, outline, center);
    _paintPathsOnCanvas(size, outline, hole, canvas);
  }

  @override
  bool shouldRepaint(CustomPainter oldDelegate) {
    return true;
  }
}

We are going to have two paths: the hole itself and the outline which is almost identical with the hole but a little bit bigger and drawn in black.

There are two methods: _buildPaths and _paintPathsOnCanvas the former is responsible for turning the given point list into paths. The latter is used to actually paint them on the canvas.

void _buildPaths(Path innerHole, Path outerHole, Offset center) {
  for (int i = 0; i < points.length; i++) {
    double point = points[i];
    double radians = pi / 180 * (i / points.length * 360);
    double cosine = cos(radians);
    double sinus = sin(radians);

    double xInner = sinus * point;
    double yInner = cosine * point - sinus;

    double outlineWidth = point * 1.02;

    double nxOuter = sinus * (outlineWidth);
    double nyOuter = cosine * (outlineWidth) - sinus;

    if (i == 0) {
      innerHole.moveTo(xInner + center.dx, yInner * -1 + center.dy);
      outerHole.moveTo(nxOuter + center.dx, nyOuter * -1 + center.dy);
    }

    innerHole.lineTo(xInner + center.dx, yInner * -1 + center.dy);
    outerHole.lineTo(nxOuter + center.dx, nyOuter * -1 + center.dy);
  }
}

We iterate over every “point” which actually describes the distance (radius) from the center. With a little bit of trigonometry, we evenly distribute these radians across a hole circle, rotating every point a little bit further until the circle is completed.

In parallel, we draw the same hole with a 2 % higher distance for every point, which creates an outline around the inner hole.

To make our Path start at the right position and not at (0|0), we move to the first point before drawing the first line.

void _paintPathsOnCanvas(Size size, Path hole, Path outline, Canvas canvas) {
  Rect rect = Rect.fromLTWH(0, 0, size.width, size.height);

  Path holePath = Path.combine(
    PathOperation.difference,
    Path()..addRect(rect),
    hole
  );

  Path outlinePath = Path.combine(
      PathOperation.difference,
      hole,
      outline
  );

  Paint shadowPaint = Paint()
    ..maskFilter = MaskFilter.blur(BlurStyle.outer, 32)
    ..color = Color(0xff966400);

  canvas.drawPath(holePath, Paint()..color = color);
  canvas.drawPath(hole, shadowPaint);
  canvas.drawPath(outlinePath, Paint()..color = Colors.black.withOpacity(0.5));
}

Okay, now it’s time to actually draw the paths we just create on canvas. It’s important that before we draw them, we subtract them from a rectangle of the size covering the whole screen. Otherwise, there would be no transparency showing the underlying screen, but instead just a growing polygon in the given solid color.

In order to mimic a half-burnt paper around the actual hole, we draw a shadow-like object around the hole. To achieve this effect, we use a MaskFilter called blur. We need to set the blurStyle to outer because we don’t want it to cover the hole. We then draw the paths in the following order: first the path that has the hole at the center. On top of that the shadow path that mimics the half-burnt area. Last but not least we draw the outline.

Now that we have defined the behavior of the painter, we still need to add it to the widget tree under our BurningPaper widget.

@override
Widget build(BuildContext context) {
  return Container(
    width: double.infinity,
    height: double.infinity,
    child: CustomPaint(
      painter: BurningPaperPainter(
        color: widget.color,
        points: points
      )
    )
  );
}

In order to cover the whole size of our screen, we use a Container with infinite dimensions and put the CustomPaint below this widget in the tree. We forward the color and points from the surrounding widget to the CustomPaint.

Now let’s try it out by inserting our BurningPaper widget at the root node of the widget tree:

@override
Widget build(BuildContext context) {
  return Material(
      child: Stack(
        children: <Widget>[
          Container(
            decoration: BoxDecoration(
                gradient: RadialGradient(
                  colors: [Colors.orange, Colors.orangeAccent]
                )
            ),
            child: Center(
              child: Text(
                "Burning\nPaper\nEffect",
                style: TextStyle(fontSize: 48, color: Colors.white),
                textAlign: TextAlign.center,
              )
            ),
          ),
          IgnorePointer(
              child: BurningPaper(
                //color: Theme.of(context).accentColor
              )
          )
        ]
      )
  );
}

When we try it out, we see nothing but the underlying widget saying “burning paper effect”. Why is that?

It’s because our point array does not have the ability to grow, yet. Let’s go and add this functionality.

@override
void initState() {
  super.initState();

  points = [for (var i = 0; i < widget.pointAmount; i+=1) 0];

  _controller = AnimationController(
    duration: widget.duration,
    vsync: this,
  );

  _animation = Tween<double>(begin: 0, end: 1).animate(
    CurvedAnimation(
      parent: _controller,
      curve: Curves.easeIn,
    ),
  );

  _controller.forward();

  _controller.addListener(() {
    setState(() {
      for(int i = 0; i < points.length; i++) {
        double newRandomPoint = points[i] + Random().nextDouble() * _animation.value * 100;
        points[i] = newRandomPoint + _animation.value / 2;
      }
    });
  });
}

Instead of letting the distance of the points to the center of the whole grow completely randomly, we use a Tween as a base. We use a CurvedAnimation that uses an easeIn curve. Everytime the controller senses a change, we take the last value and add to it the average of a random value and the current value of the tween.

The random value is just a double (between 0.0 and 1.0) multiplied with the current animation value times 100.

Result

Let’s have a look at the result using different colors for the paper:

Conclusion

With a CustomPainter and a list of Integers that are randomly increment on every animation step, we were able to quickly create the illusion of a hole burning into the center of a sheet of paper. By using Path.combine and the difference of the hole canvas and the hole that is defined by the array of Integers (representing the radius) we were able to achieve the desired result with a manageable number of code lines. The effect is customizable in terms of its color and the duration of the animation.

Flutter tutorial: Implementing a calculator

flutter-clutter — Fri, 14 Aug 2020 12:29:01 +0000

This is a total beginner tutorial, it requires zero prior knowledge. It is thought as an entry point after having had a bit of introduction into Flutter. It's supposed to give the practical input about how to implement the very first app with Flutter.

The goal

The idea is to implement a calculator whilst learning the basics of Flutter. It should be functional but not overly complicated to develop. For that reason, we delimit the feature set by the following:

It should have the possibility to let the user perform all basic calculations: add, subtract, multiply, divide
We do not work with float values, thus division only includes integers
A clean button resets the state and enables the user to define a new calculation
A bar at the top shows the current calculation with the first operand, the operator and the second operand
After a tap on the equals sign the user is presented the result of the calculation

What you are going to learn

Basic layouting using Rows and Columns
Using a StatefulWidget to keep track of the state
Extracting reusable UI into its own widget
Making use of MediaQuery to determine the size of the screen

Implementation

Setup

import 'package:flutter/material.dart';

void main() {
  runApp(CalculatorApp());
}

class CalculatorApp extends StatelessWidget {
  @override
  Widget build(BuildContext context) {
    return MaterialApp(
      title: 'Flutter basic calculator',
      home: Scaffold(
        body: Calculation()
      ),
    );
  }
}

The root widget of our application is a MaterialApp. This gives us a lot of predefined functionality that are in line with Google's Material Design. A Scaffold also provides a lot of APIs but for now it's only relevant for us at it makes the default font look good.
The Calculation widget is not yet created, you should get an error saying "The method 'Calculation' isn't defined for the type 'CalculatorApp'". We will fix it in a minute by implementing the widget. The purpose of it is to represent the screen that holds all of the UI elements of our calculator.

Putting separate functionality in its own widget is actually a good practice as it encapsulates responsibility. This is good for testing, performance and readability. Read this article for more information about it.

import 'package:flutter/material.dart';

class Calculation extends StatefulWidget {
  @override
  _CalculationState createState() => _CalculationState();
}

class _CalculationState extends State<Calculation> {
  int result;

  @override
  Widget build(BuildContext context) {
    return ResultDisplay(text: '0');
  }
}

The widget needs to be a StatefulWidget because we want to hold information like the current result and later also the operands and the operator. Tip: if you are unsure whether you need a StatefulWidget or a StatelessWidget, just start with a stateless one. Android Studio and VS Code offer a shortcut to convert a StatelessWidget to a StatefulWidget which you can use if you change your mind.

ResultDisplay

ResultDisplay is the only widget that will be displayed in our first iteration. It's the top part of the calculator showing the result of the current calculation.

import 'package:flutter/material.dart';

class ResultDisplay extends StatelessWidget {
  ResultDisplay({
    @required this.text
  });

  final int result;

  @override
  Widget build(BuildContext context) {
    return Container(
      width: double.infinity,
      height: 80,
      color: Colors.black,
      child: Text(
        text,
        style: TextStyle(
          color: Colors.white,
          fontSize: 34
        ),
      )
    );
  }
}

We make our ResultDisplay widget a stateless widget. That's because it does not change over time. The only dynamic part is the text itself, which the widget gets injected in the constructor. When the text changes, the parent widget will trigger a rebuild of this widget which makes it display the new text. If you want to know more about the difference of StatelessWidget and StatefulWidget and when to use which one, read more about it in this article.

We use Dart's syntactic sugar for constructors that do nothing else but mapping the arguments to the class properties. This prevents a little bit of boilerplate.

Now we create a Container widget with infinite width because we want to span across the whole width of the screen and a fix of 80 pixels. We set the color attribute in order to determine the background color.

On top of that we want to display the result with a white color and a font size of 34. The text itself is the result of the text property of this class which gets it in the constructor. We will take care of that later and let it be '0' for now.

If you run the app now, it should look something like this:

It's a start, but apart from the debug banner and the status bar overlay which we are going to take care of afterwards, the 0 is not aligned the way we want. We want it to be centered vertically and have a padding to the right.

There are widgets called Align and Padding which we could use. However, we would have an unnecessary deep nesting with Align being parent of Padding being parent of Container. In fact, Align and Padding are nothing more than Container widgets with certain parameters set. So instead of nesting widgets, we just set the respective properties of our already existing Container widget:

@override
Widget build(BuildContext context) {
  return Container(
    width: double.infinity,
    height: 80,
    color: Colors.black,
    child: Container(
      alignment: Alignment.centerRight,
      padding: EdgeInsets.only(right: 24),
      child: Text(
        text,
        style: TextStyle(
        color: Colors.white,
        fontSize: 34
      ),
      )
    )
  );
}

Now let's take care of the annoying debug banner and the status bar that covers our newly implemented widget. Getting rid of the debug banner is as simple as setting the debugShowCheckedModeBanner property in our MaterialApp:

@override
Widget build(BuildContext context) {
  return MaterialApp(
    debugShowCheckedModeBanner: false,
    title: 'Flutter basic calculator',
    home: Scaffold(
        body: Calculation()
    ),
  );
}

Regarding the status bar, we have two options: either we extend our app into the notch and apply a top padding so that the status bar overlaps nothing particular useful or we decide to render our app content into a SafeArea. This is a possibility to prevent interference of the UI with the OS-specific top and bottom bars.

class CalculatorApp extends StatefulWidget {
  @override
  _CalculatorAppState createState() => _CalculatorAppState();
}

class _CalculatorAppState extends State<CalculatorApp> {
  @override
  void initState() {
    SystemChrome.setSystemUIOverlayStyle(
      SystemUiOverlayStyle(
        statusBarColor: Colors.transparent,
      )
    );

    super.initState();
  }

  @override
  Widget build(BuildContext context) {
    return MaterialApp(
      debugShowCheckedModeBanner: false,
      title: 'Flutter basic calculator',
      home: Scaffold(
        body: Calculation()
      ),
    );
  }
}

class ResultDisplay extends StatelessWidget {
...
@override
Widget build(BuildContext context) {
  return Container(
    width: double.infinity,
    height: 120,
    color: Colors.black,
    child: Container(
      alignment: Alignment.bottomRight,
      padding: EdgeInsets.only(right: 24, bottom: 24),
      child: Text(
        text,
        style: TextStyle(
        color: Colors.white,
        fontSize: 34
      ),
      )
    )
  );
}

We turn the CalculatorApp into a StatefulWidget because we need the initState() method to perform an action once. Doing such tasks in the build() is not a good practice as it's not guaranteed that the method is only executed once.

Instead of vertically centering the text, which would lead to it being halfway positioned inside the notch, we choose a bottom right alignment and a bottom padding of 24.

class CalculatorApp extends StatelessWidget {
  @override
  Widget build(BuildContext context) {
    return MaterialApp(
      title: 'Flutter basic calculator',
      home: Scaffold(
        body: SafeArea(
            child: Calculation()
        )
      ),
    );
  }
}

The other option is to wrap our Calculation widget in a SafeArea. The disadvantage is that the look of the app is not as immersive as there is a black bar at the top.

Excluding the ResultDisplay, there are 4 Rows within the Column. A Column allows for vertical widget placement. The Row likewise in the horizontal direction.

@override
Widget build(BuildContext context) {
  return Column(
    children: [
      ResultDisplay(text: '0'),
      Row(
        children: [
          // Here we want to place the buttons of the first Row
        ],
      )
    ]
  );
}

Creating the keypad button

Let's design a widget first, that resembles a button on our keypad. It should be square, show its label and have a ripple effect on tap.

import 'package:flutter/material.dart';

class CalculatorButton extends StatelessWidget {
  CalculatorButton({
    @required this.label,
    @required this.onTap,
    @required this.size,
    this.backgroundColor = Colors.white,
    this.labelColor = Colors.black
  });

  final String label;
  final VoidCallback onTap;
  final double size;
  final Color backgroundColor;
  final Color labelColor;

  @override
  Widget build(BuildContext context) {
    ...
  }
}

Again, we use the shorthand constructor to assign the arguments to the member variables. These are:

label: What's written on the button, e.g. a number or an operator
onTap: A callback that is executed whenever the button is tapped
size: The button's dimension. We only need one value as the buttons are supposed to be square
backgroundColor: The background color, which defaults to white because most of the buttons have a white background
labelColor: The label color, which defaults to black because most of the buttons have a black label

Now that we have written the constructor, let's design the build() that actually determines the visuals of our button.

@override
Widget build(BuildContext context) {
  return Padding(
    padding: EdgeInsets.all(6),
    child: Container(
      width: size,
      height: size,
      decoration: BoxDecoration(
        boxShadow: [
          BoxShadow(
            color: Colors.grey, 
            offset: Offset(1, 1), 
            blurRadius: 2
          ),
        ],
        borderRadius: BorderRadius.all(
          Radius.circular(size / 2)
        ),
        color: backgroundColor
      ),
      child: // Label text and other stuff here
    )
  );
}

We start with a Padding widget that creates an inset around its child by the specified EdgeInsets. It's important to do it this way and not use the padding property of the Container widget because while the former creates a margin, the latter creates a padding and what we want is a margin between the buttons of the keypad.

The container represents the button itself. width and height are both of the given size. In order to mimic a button, we add a drop shadow using the BoxShadow widget and the boxShadow property of the Container widget.

So far we have a rectangle. We turn it into a circle by using the borderRadius property with half the size.

The color property of a Container widget determines its background color. We set it to backgroundColor.

Now, let's take care of the label and a ripple effect:

...
FlatButton(
  shape: CircleBorder(),
  onPressed: onTap,
  child: Center(
    child: Text(
      label,
      style: TextStyle(fontSize: 24, color: labelColor),
    )
  ),
),
...

A FlatButton is a certain kind of MaterialButton. These widgets take care of the button's styling and interaction behaves like Google's Material Design prescribes it.

The official docs say:

Use flat buttons on toolbars, in dialogs, or inline with other content but offset from that content with padding so that the button's presence is obvious. Flat buttons intentionally do not have visible borders and must therefore rely on their position relative to other content for context. In dialogs and cards, they should be grouped together in one of the bottom corners. Avoid using flat buttons where they would blend in with other content, for example in the middle of lists.

Material design flat buttons have an all-caps label, some internal padding, and some defined dimensions. To have a part of your application be interactive, with ink splashes, without also committing to these stylistic choices, consider using InkWell instead.

Okay, while using a FlatButton would technically work, it doesn't seem the right thing to use here, as we display it in a different way. Actually we only want a button with a ripple effect. Let's follow the recommendation of the documentation and use an InkWell.

If we just replace the FlatButton by an InkWell, we would not see an effect. That's because the parent Container has a background color that would cover everything we want to see. Flutter's team is well aware of this circumstance and developed an Ink widget to address this issue.

@override
Widget build(BuildContext context) {
  return Padding(
    padding: EdgeInsets.all(6),
    child: Ink(
      width: size,
      height: size,
      decoration: BoxDecoration(
        boxShadow: [
          BoxShadow(
            color: Colors.grey,
            offset: Offset(1, 1),
            blurRadius: 2
          ),
        ],
        borderRadius: BorderRadius.all(
          Radius.circular(size / 2)
        ),
        color: backgroundColor
      ),
      child: InkWell(
        customBorder: RoundedRectangleBorder(
          borderRadius: BorderRadius.all(Radius.circular(size / 2)),
        ),
        onTap: onTap,
        child: Center(
          child: Text(
            label,
            style: TextStyle(fontSize: 24, color: labelColor),
          )
        ),
      ),
    )
  );
}

In order to maintain the circular shape, we apply a RoundedRectangleBorder as the customBorder property of the InkWell widget.

We display the button by placing it under the ResultDisplay:

Row(
  children: [
    CalculatorButton(
      label: '7',
      onTap: () => {},
      size: 90,
      backgroundColor: Colors.white,
      labelColor: Colors.black,
    )
  ],
)

We set the onTap to an empty function and the size to 90. We will change both of the values later.

Great. Now, let's fill the rest of the keypad. To simplify this, we wrap the CalculatorButton with a function. This way, we can define default values for the colors because most of the buttons have the same color combination. Also, when we set the size depending on the screen width, we don't have to copy and paste this calculation for every Button.

Widget _getButton({String text, Function onTap, Color backgroundColor = Colors.white, Color textColor = Colors.black}) {
  return CalculatorButton(
    label: text,
    onTap: onTap,
    size: 90,
    backgroundColor: backgroundColor,
    labelColor: textColor,
  );
}

Filling the keypad with buttons

Now, lets insert every button we know we are going to need.

@override
Widget build(BuildContext context) {
  return Column(
    children: [
      ResultDisplay(text: '0'),
      Row(
        children: [
          _getButton(text: '7', onTap: () => numberPressed(7)),
          _getButton(text: '8', onTap: () => numberPressed(8)),
          _getButton(text: '9', onTap: () => numberPressed(9)),
          _getButton(text: 'x', onTap: () => operatorPressed('*'), backgroundColor: Color.fromRGBO(220, 220, 220, 1)),
        ],
      ),
      Row(
        children: [
          _getButton(text: '4', onTap: () => numberPressed(4)),
          _getButton(text: '5', onTap: () => numberPressed(5)),
          _getButton(text: '6', onTap: () => numberPressed(6)),
          _getButton(text: '/', onTap: () => operatorPressed('/'), backgroundColor: Color.fromRGBO(220, 220, 220, 1)),
        ],
      ),
      Row(
        children: [
          _getButton(text: '1', onTap: () => numberPressed(1)),
          _getButton(text: '2', onTap: () => numberPressed(2)),
          _getButton(text: '3', onTap: () => numberPressed(3)),
          _getButton(text: '+', onTap: () => operatorPressed('+'), backgroundColor: Color.fromRGBO(220, 220, 220, 1))
        ],
      ),
      Row(
        children: [
          _getButton(text: '=', onTap: calculateResult, backgroundColor: Colors.orange, textColor: Colors.white),
          _getButton(text: '0', onTap: () => numberPressed(0)),
          _getButton(text: 'C', onTap: clear, backgroundColor: Color.fromRGBO(220, 220, 220, 1)),
          _getButton(text: '-', onTap: () => operatorPressed('-'),backgroundColor: Color.fromRGBO(220, 220, 220, 1)),
        ],
      ),
    ]
  );
}
...
operatorPressed(String operator) {}
numberPressed(int number) {}
calculateResult() {}
clear() {}

Empty functions were added for the callbacks being executed when a button is pressed. By filling these with actual content, we achieve interactivity.

Adding interactivity

We start by defining what happens when the number is tapped:

numberPressed(int number) {
  setState(() {
    if (result != null) {
      result = null;
      firstOperand = number;
      return;
    }
    if (firstOperand == null) {
      firstOperand = number;
      return;
    }
    if (operator == null) {
      firstOperand = int.parse('$firstOperand$number');
      return;
    }
    if (secondOperand == null) {
      secondOperand = number;
      return;
    }

    secondOperand = int.parse('$secondOperand$number');
  });
}

There are different cases here:

If the previous calculation is finished (thus result is not null), set the result to null and let the number that was just pressed to the new first operand
If the first operand is null (this is the case at the beginning or when the clear button was pressed), set the first operand to the pressed number
If the operator is null, pressing a number button will concat the number to the first operand. Otherwise we could only perform one-digit operations
Same logic applies to the second operand

Now let's take care of the user pressing a button with an operator:

operatorPressed(String operator) {
  setState(() {
    if (firstOperand == null) {
      firstOperand = 0;
    }
    this.operator = operator;
  });
}

Since the default value of the first operand is null, we have the case of somebody pressing an operator button with no set first operand. In this case we treat it like zero. We set the member variable operand to the given operand.

Okay, now let's have a look at the function that is executed once the result button is tapped:

calculateResult() {
  if (operator == null || secondOperand == null) {
    return;
  }
  setState(() {
    switch (operator) {
      case '+':
        result = firstOperand + secondOperand;
        break;
      case '-':
        result = firstOperand - secondOperand;
        break;
      case '*':
        result = firstOperand * secondOperand;
        break;
      case '/':
        if (secondOperand == 0) {
          return;
        }
        result = firstOperand ~/ secondOperand;
        break;
    }

    firstOperand = result;
    operator = null;
    secondOperand = null;
    result = null;
  });
}

The first part makes the function return when either the operator or the second operand is null. Because there is nothing to calculate if one of them is missing.

The second part is about actually performing the calculation. I guess every operator is fairly simple except for the multiply (*) operator. This is due to the fact that we do not support float numbers. That's why we use ~/ which performs integer division. We also make sure that a division by zero is ruled out.

After the calculation we instantly prepare the next calculation by setting the first operand to the result of our current calculation and resetting everything else to null.

We need to wrap everything with setState(). Otherwise the widget will not rebuild which will result in the changes not affecting the UI.

We will have a look at the behavior of the clear button now:

clear() {
  setState(() {
    result = null;
    operator = null;
    secondOperand = null;
    firstOperand = null;
  });
}

It's as simple as resetting every variable to null.

Displaying the result

So far, we only display a "0" in the ResultDisplay. However, we want to display the calculation or the result depending on the current state.

ResultDisplay(
  text: _getDisplayText(),
)
...
String _getDisplayText() {
  if (result != null) {
    return '$result';
  }

  if (secondOperand != null) {
    return '$firstOperand$operator$secondOperand';
  }

  if (operator != null) {
    return '$firstOperand$operator';
  }

  if (firstOperand != null) {
    return '$firstOperand';
  }

  return '0';
}

Instead of providing '0' as the text property of the constructor of our ResultDisplay, we choose the return value of the _getDisplayText() method.

This method returns the result if it is not null. If the second operand is set, it displays the whole calculation. If the operator is set, it displays the first operand and the operator. If only the first operator is set, it displays it. Finally if even the first operand is null (e. g. at startup time or when the user has pressed the clean button), it displays '0'.

Proper sizing of the buttons

There is one thing left to do and that's having the UI being responsive instead of the buttons having a static size of 90.

class _CalculationState extends State<Calculation> {
  double width;

  int firstOperand;
  String operator;
  int secondOperand;
  int result;

  @override
  void didChangeDependencies() {
    width = MediaQuery.of(context).size.width;
    super.didChangeDependencies();
  }
  ...
  Widget _getButton({String text, Function onTap, Color backgroundColor = Colors.white, Color textColor = Colors.black}) {
    return CalculatorButton(
      label: text,
      onTap: onTap,
      size: width / 4 - 12,
      backgroundColor: backgroundColor,
      labelColor: textColor,
    );
  }

We add a member variable called width. This will hold the width of the screen. We use didChangeDependencies() in order to obtain the screen width and set the variable to its width value. didChangeDependencies() is called after initState(). We can not use initState() because we need the BuildContext to obtain the screen width which is not available yet.

To determine the size of a button we simply divide the screen width by four because we have four buttons in a row.

Final words

In this beginner tutorial we implemented a calculator that enables the user to do basic calculations. We extracted the responsibilities in separate widgets to keep the code readable.

Feel free to extend the example by things like floats support, addition operators like square root or a history of all calculations.

FULL CODE

StatelessWidget vs. StatefulWidget

flutter-clutter — Sat, 08 Aug 2020 11:31:11 +0000

Probably one of the most frequently asked questions of Flutter beginners is about the difference of StatelessWidget and StatefulWidget. Coming from other frameworks, this distinction is a new decision to make and when creating new widgets you can't get around it. In this article, the difference of both widget types will be examined and the answer to the question why stateful widgets cannot simply always be used will be given.

What is the difference?

The meaning of stateless is merely that all of the widget's properties are immutable. This leads to the fact that the only way to change them is a new instance of that widget. Now the confusing part: a stateful widget is immutable as well. However, the state object it's coupled with, is mutable and allows the rebuild of the widget whenever the state changes.

In other words: A StatelessWidget will never rebuild by itself, but it has the ability to do so from external. A StatefulWidget can trigger the rebuild by itself (e. g. by calling setState()).

As shown in the figure, the StatelessWidget only offers one public API to trigger a build which is the constructor, whereas the StatefulWidget has numerous triggers that cause a (re)build. didUpdateWidget() is called whenever configuration of the widget changes. This can for example be the case when the screen rotates.

Common misconception

I often read the difference between StatelessWidget and StatefulWidget is its ability to change. While this is technically correct (although not very precise) because the widget itself is immutable, it can cause confusion. Statements like these led me to a misunderstanding when I was starting to learn Flutter.

I had thoughts like: "Well, if I have a button whose color needs to change depending on external influences, I need to use a StatefulWidget for the button because change is not possible otherwise". Actually, the color was part of the constructor and the parent widget was responsible for the color change, making the parent widget stateful and the button stateless.

Therefore, for me the relevant question is not "can the widget change over time?" but rather "who is in charge of a potential change?".

What do I need state for?

One could ask: why the big attention? What's the significance of state anyways?

If you think about it, user interaction is nothing more than reading from and writing to the state. Let it be the local state of a screen or the state of the whole app. As a user, you interpret what's going on visually (which is a representation of the app's state) and interact with it through UI components (which then apply changes to the state). By the time your app gains complexity, managing state across all screens or widgets becomes more of a challenge. That's why it's a good idea to think about the way you want to manage your state early on.

Why the distinction?

A legit question to ask would be: if a stateful widget is virtually the same as a stateless widget (apart from a state object being tracked or not), why don't we just use stateful widgets everywhere and call it widget? No confusion for the developer and no need to decide which one to use in which situation. Besides, if one can always turn a stateless widget into a stateful one by wrapping a stateful widget around it, what's the point? Why do we need distinction in the first place?

To approach the answer to that question, let's have a look at the setState() method being located in the State class of the framework.

@protected
void setState(VoidCallback fn) {
  assert(fn != null);
  assert(() {
    ...
    return true;
  }());
  final dynamic result = fn() as dynamic;
  assert(() {
    ...
    return true;
  }());
  _element.markNeedsBuild();
}

Actually, apart from some assertions and storing the result from the provided callback, the only thing setState() does, is calling _element.markNeedsBuild().
Interesting, so can't we just call markNeedsBuild() from a stateless widget then and achieve the same functionality as calling setState() in a stateful widget?

class StatelessWidgetWithState extends StatelessWidget {
  @override
  Widget build(covariant TestState context) {
    return MaterialButton(
      onPressed: () {
        context.text = 'Overridden';
        context.markNeedsBuild();
      },
      child: Text(context.text),
    );
  }

  @override
  TestState createElement() => TestState(this);
}

By using covariant we were able to mimic the behavior in a stateless widget and indeed, this produces the same result like having set the context variable of a State inside the setState() method of a stateful widget.

What that shows is: StatelessWidgets and StatefulWidgets provide the same functionality (internally) but StatelessWidget hides most of it from the developer to provide a convenience class for widgets that are static.

Having a generic Widget class that reacts dynamically on the calls and keeps the caller from deciding between stateless and stateful would require some reflection. In the context of the Flutter framework, Dart's ability of mirroring is disabled, though.

To conclude: the inability of having a single base class that works for both stateful and statless widgets is a design decision of the Flutter developers that increases the convenience and prevents the developer from doing things he should not do. It is also a consequence of how Dart works and what restrictions to the language were put into the framework.

How do I decide when to use a StatefulWidget?

If the visuals of the widget only change depending on the parent widget and all of its state is defined in the constructor, use a StatelessWidget.

If there is an internal state (that could e. g. be a text color) that changes independent from the parent (e. g. a color changes when you tap it), use a StatefulWidget.

If you are in doubt, start with a StatelessWidget. Once you realize you're approaching its boundaries, you can easily switch to a StatefulWidget by using your IDEs shortcuts.

Does a StatelessWidget become stateful when it contains a StatefulWidget?

If you look at it on a more abstract level, you can say so. But in the world of Flutter where stateful and stateless are predefined terms it does not. The parent has no knowledge or responsibility of the child's state. The stateful child manages its state on its own.

What if every widget was stateless?

If we were to create a completely static app that allows for no interaction, we could theoretically implement every widget stateless. That would, however, also mean that we could not navigate because the MaterialApp, which we could not use because it is stateful, configures the top-level Navigator. Basically, we would be faced with a single-screen app that could display text and a little layouting.

The official docs say this about the topic:

Entire applications can be built with only StatelessWidgets, which are essentially functions that describe how arguments map to other functions, bottoming out in primitives that compute layouts or paint graphics. (Such applications can’t easily have state, so are typically non-interactive.) For example, the Icon widget is essentially a function that maps its arguments (color, icon, size) into layout primitives. Additionally, heavy use is made of immutable data structures, including the entire Widget class hierarchy as well as numerous supporting classes such as Rect and TextStyle. On a smaller scale, Dart’s Iterable API, which makes heavy use of the functional style (map, reduce, where, etc), is frequently used to process lists of values in the framework.

What if every widget was stateful?

Like it was said before: internally there is no big difference between stateful and stateless widgets. And strictly speaking, every widget is stateful. However, using stateful widgets wherever we can would create unnecessary boilerplate code with tons of widgets that are never rebuilt and states that are never initiated. In terms of performance, that would not make a big difference. Regarding readability and LOC it's probably not the most recommendable approach.

Examples

Let's have a look at some examples to make the above explanations more clear. We are going to implement three little widgets:

A widget using only its internal state
A widget that get its initial and final state handed in from its parent
A widget that uses both internal state and state being managed from its parent

Widget using only internal state

class StateOnlyWidget extends StatefulWidget {
  @override
  State<StatefulWidget> createState() {
    return _StateOnlyWidgetState();
  }
}

class _StateOnlyWidgetState extends State<StateOnlyWidget> {
  String text = 'Initial';

  @override
  Widget build(BuildContext context) {
    return ListView(
      children: <Widget>[
        RaisedButton(
          child: Text('Press'),
          onPressed: _changeText,
        ),
        Text(text)
      ],
    );
  }

  void _changeText() {
    setState(() {
      text = 'Overridden';
    });
  }
}

The text property is managed by the widget's state in this example. No parent widget knows about this property as it's not publicly available throughout the widget. Once the user presses the button, the setState() method is used to alter it.

Widget using only external state

class ExternalStateOnlyWidget extends StatelessWidget {
  ExternalStateOnlyWidget({
    @required this.textString,
    @required this.changeText
  });

  final String textString;
  final Function changeText;

  @override
  Widget build(BuildContext context) {
    @override
    Widget build(BuildContext context) {
      return ListView(
        children: <Widget>[
          RaisedButton(
            child: Text('Press'),
            onPressed: changeText,
          ),
          Text(textString)
        ],
      );
    }
  }
}

In this case, both the string describing the text and the behavior that is triggered when tapping the button are controlled by the parent and injected into the constructor of our widget.

Mix-and-match

class InternalAndExternalStateWidget extends StatefulWidget {
  InternalAndExternalStateWidget({
    @required this.buttonText,
  });

  final String buttonText;

  @override
  State<StatefulWidget> createState() {
    return _InternalAndExternalStateWidgetState();
  }
}

class _InternalAndExternalStateWidgetState extends State<InternalAndExternalStateWidget> {
  String text = 'Initial';

  @override
  Widget build(BuildContext context) {
    return ListView(
      children: <Widget>[
        RaisedButton(
          child: Text(widget.buttonText),
          onPressed: _changeText,
        ),
        Text(text)
      ],
    );
  }

  void _changeText() {
    setState(() {
      text = 'Overridden';
    });
  }
}

This is a mix-and-match approach where the displayed text string and the behavior on button tap are managed internally by the widget. The label of the button is injected by the parent widget.

Final words

Although the difference between StatelessWidget and StatefulWidget might be confusing for beginners, after having invested a few minutes, it's not that difficult anymore. The decision what kind of widget to use mainly depends on the question if the widget has its own internal state to manage. If you are in doubt, you can always start with a StatelessWidget first and convert later if it does not suit the use case.

After all, the distinction is merely a convenience functionality that removes the boilerplate when we use the stateless widget. Internally, both types are virtually the same.