Version 3 (JaffaKetchup#11)

* 1/3 Progress? * Finished adding circle and rectangle and basic refactoring and comment addition * Finished Regions API Migration * Addition of background download * Example fixed * Moved to @OverRide API instead on Extension Methods * Create FUNDING.yml * Added requestIgnoreBatteryOptimizations() * Add Package Analyzer Action * Ready for prerelease 3.0.0-dev.1 * Improved some code comments and docs Renamed some files to more accurately fit purpose * Update issue templates (JaffaKetchup#13) * Better Documentation * Ready for release v3 * Change to v3 in pubspec.yaml

Author: JaffaKetchup

.github/FUNDING.yml

@@ -0,0 +1 @@
+ko_fi: JaffaKetchup

.github/ISSUE_TEMPLATE/bug-report.md

@@ -1,27 +1,27 @@
 ---
 name: Bug Report
 about: Create a bug report to help us improve
-title: ''
+title: "[BUG]"
 labels: bug
 assignees: JaffaKetchup
 
 ---
 
-**Bug description**
+**What is the bug?**
 A clear and concise description of what the bug is.
 
-**Expected behavior**
-A clear and concise description of what you expected to happen.
+**What do you expect to happen?**
+A clear and concise description of what you expected to happen, compared to what actually happened, in detail.
 
 **Reproduction**
-Steps to reproduce the behavior:
+Steps to reproduce the behaviour:
 1. Go to '...'
 2. Click on '....'
 3. Scroll down to '....'
 4. See error
 
 **Screenshots and recordings**
-If applicable, add screenshots to help explain your problem.
+To help us solve this issue quicker, attach screenshots and recordings if you can.
 
 **Additional context**
 Add any other context about the problem here. Does the issue only happen on certain platforms, for example?

.github/ISSUE_TEMPLATE/question-help.md

@@ -0,0 +1,17 @@
+---
+name: Question/Help
+about: Ask for clarification or get help for a certain feature
+title: "[QUESTION]"
+labels: question
+assignees: JaffaKetchup
+
+---
+
+**What is the main problem?**
+A clear and concise description of what the problem is. Eg. How do I use this function?
+
+**Give more detail about what you need help with or what your question is**
+Eg. How do I use this function to do this thing that I'm trying to do
+
+**Is there a potential for this question to turn into a feature request?**
+If you're question can't be answered easily, do you want an inbuilt way to do what you want? How necessary is this to you (will it disrupt your whole app, or is it just a quality of life feature)?

.github/workflows/main.yml

@@ -0,0 +1,28 @@
+name: Run Dart Package Analyzer
+on: [push, pull_request, workflow_dispatch]
+
+jobs:
+
+ package-analysis:
+
+ runs-on: ubuntu-latest
+
+ steps:
+ - uses: actions/checkout@v2
+
+ - uses: axel-op/dart-package-analyzer@v3
+ id: analysis
+ with:
+ githubToken: ${{ secrets.GITHUB_TOKEN }}
+
+ - name: Check Scores
+ env:
+ TOTAL: ${{ steps.analysis.outputs.total }}
+ TOTAL_MAX: ${{ steps.analysis.outputs.total_max }}
+ run: |
+ PERCENTAGE=$(( $TOTAL * 100 / $TOTAL_MAX ))
+ if (( $PERCENTAGE < 50 ))
+ then
+ echo Total score percentage below 50 percent. Improve the score!
+ exit 1
+ fi

CHANGELOG.md

@@ -1,5 +1,31 @@
 # Changelog
 
+## [3.0.0] - 2021/07/04
+
+* Last quick fixes
+* Publish to pub.dev
+* Use AlarmManager for background tasks to resolve issues
+
+## [3.0.0-dev.2] - 2021/07/01
+
+* Move to more appropriate date system for changelog
+* Rewritten documentation
+* Improved examples
+* Improved easy shape chooser
+
+## [3.0.0-dev.1] - 30/06/2021
+
+* Huge refactoring to make methods easier to use and more flexible
+* Addition of circle region
+* Refactoring of square region
+* Removal of tuple from main methods
+* Addition of ability to exclude pure sea tiles
+* Addition of multiple caching tables
+* Performance improvements
+* Add donation method
+* Add GitHub actions
+* Added easy shape chooser
+
 ## [2.0.2] - 04/06/2021
 
 * Publish to pub.dev

README.md

@@ -1,76 +1,138 @@
 # flutter_map_tile_caching
 
-A plugin for the [`flutter_map`](https://pub.dev/packages/flutter_map) library. Adds full tile caching functionality and methods to download areas of tiles.
+A plugin for the [`flutter_map`](https://pub.dev/packages/flutter_map) library to provide an easy way to cache tiles and download map regions for offline use.
 
 [![Pub](https://img.shields.io/pub/v/flutter_map_tile_caching.svg)](https://pub.dev/packages/flutter_map_tile_caching) [![likes](https://badges.bar/flutter_map_tile_caching/likes)](https://pub.dev/packages/flutter_map_tile_caching/score) [![pub points](https://badges.bar/flutter_map_tile_caching/pub%20points)](https://pub.dev/packages/flutter_map_tile_caching/score)
 [![GitHub stars](https://img.shields.io/github/stars/JaffaKetchup/flutter_map_tile_caching.svg?style=social&label=Stars)](https://GitHub.com/JaffaKetchup/flutter_map_tile_caching/stargazers/) [![GitHub issues](https://img.shields.io/github/issues/JaffaKetchup/flutter_map_tile_caching.svg?style=social&label=Issues)](https://GitHub.com/JaffaKetchup/flutter_map_tile_caching/issues/) [![GitHub PRs](https://img.shields.io/github/issues-pr/JaffaKetchup/flutter_map_tile_caching.svg?style=social&label=Pull%20Requests)](https://GitHub.com/JaffaKetchup/flutter_map_tile_caching/pulls/)
 
-## Example
-
-To view the example, copy the `main.dart` file inside the `example` directory, and run it inside your own new project. You'll need to add this package (see below) and `flutter_map` to your dependencies.
+[![ko-fi](https://ko-fi.com/img/githubbutton_sm.svg)](https://ko-fi.com/N4N151INN)
 
 ## Installation
 
-To install this plugin, add the below code snippet to your `pubspec.yaml` file:
+To install this plugin, use the normal installation method:
 
-```yaml
-  flutter_map_tile_caching:
+```shell
+ > flutter pub add flutter_map_tile_caching
 ```
 
-followed by `^`, then the most recent available pub.dev version (without the 'v') (currently [![Pub](https://img.shields.io/pub/v/flutter_map_tile_caching.svg)](https://pub.dev/packages/flutter_map_tile_caching)).
-If you urgently need the most recent version of this package that hasn't been published to pub.dev yet, use this code snippet instead (please note that this method is not recommended):
+If you urgently need the most recent version of this package that hasn't been published to pub.dev yet, use this code snippet instead in your pubspec.yaml (please note that this method is not recommended):
 
 ```yaml
  flutter_map_tile_caching:
  git:
  url: https://github.com/JaffaKetchup/flutter_map_tile_caching
 ```
 
-## Usage
-
-Use it like any other package. You'll have access to all the things listed below.
+After installing the package, import it into the neccessary files in your project:
 
 ```dart
 import 'package:flutter_map_tile_caching/flutter_map_tile_caching.dart';
 ```
 
-### New Tile Provider
+### Android
+
+A few more steps are required on Android due to the background download functionality, unfortunately even if you do not intend to use the functionality. This is due to the way the dependency used to perform background downloading works.
+For these steps please go here: [background_fetch Installation Instructions For Android](https://github.com/transistorsoft/flutter_background_fetch/blob/master/help/INSTALL-ANDROID.md).
+
+### iOS
+
+A few more steps are required on iOS due to the background download functionality, even though this functionality is unfortunately currently blocked on iOS. This is due to the way the dependency used to perform background downloading works.
+For these steps please go here: [background_fetch Installation Instructions For iOS](https://github.com/transistorsoft/flutter_background_fetch/blob/master/help/INSTALL-IOS.md).
+You should not need to follow the instructions for `BackgroundFetch.scheduleTask`, but do so if you recieve build errors - the custom task identifiers asked for in the last step is exactly 'backgroundTileDownload'.
+Please note that this library has not been tested on iOS devices, so issues may arize. Please leave an issue if they do, and I'll try my best to debug and solve them.
+
+## Example
+
+To view the example project, just clone the .zip file in the example folder and unzip it to a local directory. You should be able to run it instantly on Android - iOS will require extra setup. Beware, this solution may be older than the latest example.
+
+For the latest example, but no other code or build settings, just clone the main.dart file in the example folder to a local project, and import this library and `flutter_map` in the pubspec.yaml file.
+
+Alternatively, if you just want to see how it works in real life, you can run the example app on an Android device by installing the APK file found in the 'example' directory.
+
+## Functionality
+
+This library provides 3 main functionalities and 4 main APIs:
+
+- Automatic Tile Caching (`TileProvider` API & Caches API)
+- Region Downloading (`TileProvider` API, Regions API, Downloading API & Caches API)
+ - Easy Shape Chooser (Regions API)
+
+These all work together to give you all you need to implement fully offline maps in your Flutter app.
+
+## [API Details](https://pub.dev/documentation/flutter_map_tile_caching/latest/flutter_map_tile_caching/flutter_map_tile_caching-library.html)
+
+You can see every class, method, extension and enumerable in the [Dart auto generated docs (dartdoc)](https://pub.dev/documentation/flutter_map_tile_caching/latest/flutter_map_tile_caching/flutter_map_tile_caching-library.html). This contains everything available and a description on how to use them. You can also check the example for how all of these things fit together. However, for simplicity for new users to this project, the main/most useful/most common parts are below, and these can be looked up in the docs using the search functionality:
+
+#### `StorageCachingTileProvider()`
+
+Use this as the tile provider for your `FlutterMap()` to automatically cache tiles as your users pan (aka. browse) over them. Use the same 'instance' throughout your script to avoid duplicate conflicts.
+Read more about the caching behaviour below.
+
+#### `downloadRegion()` and it's background counterpart
+
+Use this to download large areas of a map before the user visits somewhere (for example before a hike in the wilderness).
+A region can currently be a rectangular region or a circular region. More types are planned for the future.
+Read more about the caching behaviour below.
+
+#### Easy Shape Chooser
+
+Use this as a 'layer' on your map to allow the user an easy way to select an area for downloading. Use the same 'instance' throughout your script to avoid duplicate conflicts.
+A region can currently be a rectangular region or a circular region. More types are planned for the future.
+This will be worked on in the future to bring better functionality.
+
+### Migrate to v3 from v2
+
+Unfortunately, because so much has changed, the best way to migrate is to rewrite the appropriate areas of your project with the new features.
+I've tried to make v3 super easy to understand and use, even with all the new functionality, so I hope you don't find this too hard.
+I cannot foresee another update as big as this any time in the future, so hopefully future major releases shouldn't need 'migrating' as such. I'm always planning functionality however!
+
+## Offline/Caching Behaviour
+
+Because this is an offline first package, it may act a little differently to how you expect. Both areas that interact with caching are detailed below:
+
+### Whilst Browsing
+
+'Browsing' in this library means panning, zooming and rotating through the map.
 
-This plugin adds the new tile provider: `StorageCachingTileProvider(...)`.
-This takes the optional `cachedValidDuration` `Duration` argument which defaults to a duration of 31 days.
+When a new tile is browsed, and the user is online, the tile will be fetched from the server and cached with a record of when it's expiry date is (dictated by the `cachedValidDuration` on the tile provider).
+If this tile is browsed again, and the user is online, the tile will still be taken from cache, even if the user is online, unless the tile has expired, in which case it will be refetched and cached again. This is known as 'cache-first' caching.
+If this tile is browsed again, but the user is not online, the tile will be taken from cache, even if the tile has expired. The network request will still be made, however, and it will fail silently.
+If the user is not online, and the tile has not been cached yet, the request will fail with an error to the console, but the app will carry on working as normal.
 
-When new tiles are loaded, this tile provider will cache them in a database cache. When these tiles are requested again, the tile will be taken from cache if it is younger than it's `cachedValidDuration`, otherwise the tile will be requested again. However, if the request fails (eg. there is no Internet connection), the tile should still be taken from cache.
+### When Downloading Regions
 
-### New Classes, Methods & Functions
+Whilst using the `downloadRegion()` function (or it's background counterpart (see below)), every tile in the region will always be cached, even if the tile has been cached before but it hasn't expired.
+Every tile downloaded will then act like it has been browsed (see above).
 
-This plugin adds the new classes: `StorageCachingTileProvider` & `TileStorageCachingManager`.
+## Background Region Downloading
 
-#### `StorageCachingTileProvider`
+Instead of downloading in the foreground (on the main thread), there is an option on Android to start a download in the background.
 
-You can call `loadTiles(...)` on `StorageCachingTileProvider(...)`, and pass in the appropriate bounds and min/max zoom levels. This will download and precache all the tiles in the specified area for all the specified zoom levels. It can be listened to for a `Tuple3<int, int, int>`, with the number of downloaded tiles, number of errored tiles (eg. tiles that couldn't be downloaded due to lack of Internet connection), and the total number of tiles to be downloaded, in that order. The `maxCachedTilesAmount` can be cached at once, which defaults to 20000.
+This has several major advantages including better core app performace, ability to continue whilst the user is interacting with other app components, and (potential) ability to continue even whilst the user is in other apps or the device is locked.
 
-You can call `approximateTileAmount(...)` on `StorageCachingTileProvider`, and pass in the appropriate bounds and min/max zoom levels. This will return an `int` which is the approximate number of tiles within the specified area.
+The background download functionality is buggy and does not function as expected all the time on platforms other than Android, so that functionality has been disabled on all platforms except Android. This might change in the future, but there is no gurantee.
 
-#### `TileStorageCachingManager`
+To have full background functionality including not being throttled by the system and being guaranteed to run even if the app is 'minimized', request the ignore battery optimizations permission by calling `requestIgnoreBatteryOptimizations()` before starting a background task. This will display a system interruption prompt to the user to allow or deny the permission. The background task will still run if the permission is denied, but only if the user is in the app - elsewhere, downloading is not guaranteed to be running.
 
-You can call `cacheDbSize` on `TileStorageCachingManager`. This will return a `Future<int>` which is the size of the caching database in bytes. Divide by 1049000 to get the number of megabytes.
+## Limitations, Accuracy & Testing
 
-You can call `cachedTilesAmount` on `TileStorageCachingManager`. This will return a `Future<int>` which is the total number of tiles currently cached.
+This package does not support the web platform (due to the usage of `dart:io` and the `sqflite` package).
 
-You can call `maxCachedTilesAmount` on `TileStorageCachingManager`. This will return a `Future<int>` which is the maximum number of tiles allowed to be cached at any one time.
+The circle region functions get less accurate the larger the radius of the circle. To prevent interruptive errors, the values of the calculation have been clamped to a valid minimum and maximum, but this causes side effects. To prevent these side effects, only use circles smaller than the average size of a European country, and be cautious when using circles around extremes (the equator, the longitudes of 180 or -180, and the latiudes of -90 or 90). If selecting a large region or working around the aformentioned extremes, use rectangular regions instead. A fix for this may appear in the future
 
-You can call `kDefaultMaxTileAmount` on `TileStorageCachingManager`. This will return an `int` which is the default maximum number of tiles allowed to be cached at any one time. This might differ to `maxCachedTilesAmount` if `changeMaxTileAmount(...)` has ever been called.
+This package has only been tested on Android devices (one real Android 8, one Android 8 emulator, and one Android 11 emulator).
 
-You can call `changeMaxTileAmount(...)` on `TileStorageCachingManager`, and pass in the new max tile amount to change `maxCachedTilesAmount`.
+## Supporting Me
 
-You can call `cleanCache()` on `TileStorageCachingManager`. This will clear all the cached tiles from the database forever, without warning.
+A donation through my Ko-Fi page would be infinitly appriciated:
+[![ko-fi](https://ko-fi.com/img/githubbutton_sm.svg)](https://ko-fi.com/N4N151INN)
 
-## Limitations
+but, if you can't or won't, a star on GitHub and a like on pub.dev would also go a long way!
 
-This package does not support the web platform (due to the usage of `dart:io`) and the code has not been tested on desktop platforms.
+Every donation gives me fuel to continue my open-source projects and lets me know that I'm doing a good job.
 
 ## Credits
 
-This code was originally created by [bugDim88](https://github.com/bugDim88), and improved upon by multiple people. You can see the original pull request here: [pull request #564 on fleaflet/flutter_map](https://github.com/fleaflet/flutter_map/pull/564). JaffaKetchup seperated the code into this external package on behalf of [bugDim88](https://github.com/bugDim88) & other contributors to keep the base package small. All credit therefore goes to [bugDim88](https://github.com/bugDim88) and the other contributors.
+The basis of this library was originally coded by [bugDim88](https://github.com/bugDim88), and improved upon by multiple people. You can see the original pull request here: [pull request #564 on fleaflet/flutter_map](https://github.com/fleaflet/flutter_map/pull/564).
 
-If this package is beneficial to you, please leave a star on GitHub and a like on pub.dev!
+Since v2 here, other contributors have also been involved, who can be seen in GitHub. The only old part remaining that that coder coded is the database manager script (with all the SQL in it), but the aforementioned main coder still inspired the rest of this project and is therefore the 'founder'. Thanks to you, bugDim88!