Skip to content

Commit

Permalink
Prepare release 3.0.0
Browse files Browse the repository at this point in the history
  • Loading branch information
@Lyokone
Lyokone committed Mar 26, 2020
1 parent bde4465 commit aaaf6c6
Show file tree
Hide file tree
Showing 10 changed files with 239 additions and 137 deletions.
19 changes: 19 additions & 0 deletions LICENSE
View file
@@ -0,0 +1,19 @@
Copyright (c) 2017, Guillaume Bernos.

Permission is hereby granted, free of charge, to any person obtaining a copy of
this software and associated documentation files (the "Software"), to deal in
the Software without restriction, including without limitation the rights to
use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies
of the Software, and to permit persons to whom the Software is furnished to do
so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.
83 changes: 55 additions & 28 deletions README.md
View file
@@ -1,38 +1,62 @@
# Flutter Location Plugin
# Flutter Location Plugin

[![pub package](https://img.shields.io/pub/v/location.svg)](https://pub.dartlang.org/packages/location) ![Cirrus CI - Task and Script Build Status](https://img.shields.io/cirrus/github/Lyokone/flutterlocation?task=test)
[![codecov](https://codecov.io/gh/Lyokone/flutterlocation/branch/master/graph/badge.svg)](https://codecov.io/gh/Lyokone/flutterlocation)

This plugin for [Flutter](https://flutter.io)
handles getting location on Android and iOS. It also provides callbacks when location is changed.

<p align="center">
<img src="https://raw.githubusercontent.com/Lyokone/flutterlocation/master/src/demo_readme.gif" alt="Demo App" style="margin:auto" width="372" height="686">
<img src="https://raw.githubusercontent.com/Lyokone/flutterlocation/master/location/src/demo_readme.gif" alt="Demo App" style="margin:auto" width="372" height="686">
</p>

## :sparkles: New experimental feature :sparkles:
To get location updates even your app is closed, you can see [this wiki post](https://github.com/Lyokone/flutterlocation/wiki/Background-Location-Updates).


## Getting Started

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

```yaml
dependencies:
location: ^2.5.0
location: ^3.0.0
```

### Android

With Flutter 1.12, all the dependencies are automatically added to your project.
If your project was created before Flutter 1.12, you may need to follow [this](https://github.com/flutter/flutter/wiki/Upgrading-pre-1.12-Android-projects).

### iOS

And to use it in iOS, you have to add this permission in Info.plist :

```xml
NSLocationWhenInUseUsageDescription
NSLocationAlwaysUsageDescription
```

### Web

Nothing to do, the plugin works directly out of box.

### macOS

Ensure that the application is properly "sandboxed" and that the location is enabled. You can do this in Xcode with the following steps:

1. In the project navigator, click on your application's target. This should bring up a view with tabs such as "General", "Capabilities", "Resource Tags", etc.
1. Click on the "Capabilities" tab. This will give you a list of items such as "App Groups", "App Sandbox" and so on. Each item will have an "On/Off" button.
1. Turn on the "App Sandbox" item and press the ">" button on the left to show the sandbox stuff.
1. In the "App Data" section, select "Location".

Add this permission in Info.plist :

```xml
NSLocationWhenInUseUsageDescription
NSLocationAlwaysUsageDescription
```

## Usage

Then you just have to import the package with

```dart
import 'package:location/location.dart';
```
Expand Down Expand Up @@ -66,6 +90,7 @@ _locationData = await location.getLocation();
```

You can also get continuous callbacks when your position is changing:

```dart
location.onLocationChanged().listen((LocationData currentLocation) {
// Use current location
Expand All @@ -75,19 +100,21 @@ location.onLocationChanged().listen((LocationData currentLocation) {
Be sure to check the example project to get other code samples.

## Public Methods Summary
| Return |Description|
|--------|-----|
| Future\<PermissionStatus> | **requestPermission()** <br>Request the Location permission. Return a PermissionStatus to know if the permission has been granted. |
| Future\<PermissionStatus> | **hasPermission()** <br>Return a PermissionStatus to know the state of the location permission. |
| Future\<bool> | **serviceEnabled()** <br>Return a boolean to know if the Location Service is enabled or if the user manually deactivated it. |
| Future\<bool> | **requestService()** <br>Show an alert dialog to request the user to activate the Location Service. On iOS, will only display an alert due to Apple Guidelines, the user having to manually go to Settings. Return a boolean to know if the Location Service has been activated (always `false` on iOS). |
| Future\<bool> | **changeSettings(LocationAccuracy accuracy = LocationAccuracy.HIGH, int interval = 1000, double distanceFilter = 0)** <br>Will change the settings of futur requests. `accuracy`will describe the accuracy of the request (see the LocationAccuracy object). `interval` will set the desired interval for active location updates, in milliseconds (only affects Android). `distanceFilter` set the minimum displacement between location updates in meters. |
| Future\<LocationData> | **getLocation()** <br>Allow to get a one time position of the user. It will try to request permission if not granted yet and will throw a `PERMISSION_DENIED` error code if permission still not granted. |
| Stream\<LocationData> | **onLocationChanged()** <br>Get the stream of the user's location. It will try to request permission if not granted yet and will throw a `PERMISSION_DENIED` error code if permission still not granted. |


| Return | Description |
| ------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| Future\<PermissionStatus> | **requestPermission()** <br>Request the Location permission. Return a PermissionStatus to know if the permission has been granted. |
| Future\<PermissionStatus> | **hasPermission()** <br>Return a PermissionStatus to know the state of the location permission. |
| Future\<bool> | **serviceEnabled()** <br>Return a boolean to know if the Location Service is enabled or if the user manually deactivated it. |
| Future\<bool> | **requestService()** <br>Show an alert dialog to request the user to activate the Location Service. On iOS, will only display an alert due to Apple Guidelines, the user having to manually go to Settings. Return a boolean to know if the Location Service has been activated (always `false` on iOS). |
| Future\<bool> | **changeSettings(LocationAccuracy accuracy = LocationAccuracy.HIGH, int interval = 1000, double distanceFilter = 0)** <br>Will change the settings of futur requests. `accuracy`will describe the accuracy of the request (see the LocationAccuracy object). `interval` will set the desired interval for active location updates, in milliseconds (only affects Android). `distanceFilter` set the minimum displacement between location updates in meters. |
| Future\<LocationData> | **getLocation()** <br>Allow to get a one time position of the user. It will try to request permission if not granted yet and will throw a `PERMISSION_DENIED` error code if permission still not granted. |
| Stream\<LocationData> | **onLocationChanged** <br>Get the stream of the user's location. It will try to request permission if not granted yet and will throw a `PERMISSION_DENIED` error code if permission still not granted. |

You should try to manage permission manually with `requestPermission()` to avoid error, but plugin will try handle some cases for you.

## Objects

```dart
class LocationData {
final double latitude; // Latitude, in degrees
Expand All @@ -101,27 +128,27 @@ class LocationData {
}
enum LocationAccuracy {
POWERSAVE, // To request best accuracy possible with zero additional power consumption,
LOW, // To request "city" level accuracy
BALANCED, // To request "block" level accuracy
HIGH, // To request the most accurate locations available
NAVIGATION // To request location for navigation usage (affect only iOS)
enum LocationAccuracy {
powerSave, // To request best accuracy possible with zero additional power consumption,
low, // To request "city" level accuracy
balanced, // To request "block" level accuracy
high, // To request the most accurate locations available
navigation // To request location for navigation usage (affect only iOS)
}
// Status of a permission request to use location services.
enum PermissionStatus {
/// The permission to use location services has been granted.
GRANTED,
granted,
// The permission to use location services has been denied by the user. May have been denied forever on iOS.
DENIED,
denied,
// The permission to use location services has been denied forever by the user. No dialog will be displayed on permission request.
DENIED_FOREVER
deniedForever
}
```
Note: you can convert the timestamp into a `DateTime` with: `DateTime.fromMillisecondsSinceEpoch(locationData.time.toInt())`
```

Note: you can convert the timestamp into a `DateTime` with: `DateTime.fromMillisecondsSinceEpoch(locationData.time.toInt())`

## Feedback

Expand Down
153 changes: 89 additions & 64 deletions location/CHANGELOG.md
View file
@@ -1,127 +1,152 @@
## [3.0.0] 26th March 2020

- Add Web and macOS as new supported platforms (huge thanks to long1eu)
- [BREAKING] Enums are now following Dart guidelines.
- [BREAKING] _onLocationChanged_ is now a getter to follow Dart guidelines.

## [2.5.4] 11st March 2020
* Update documentation
* Fix: Airplane mode was preventing location from being requested
* Fix: Not crashing when activity is not set on Android

- Update documentation
- Fix: Airplane mode was preventing location from being requested
- Fix: Not crashing when activity is not set on Android

## [2.5.3] 26th February 2020
* Improve code coverage
* Update documentation

- Improve code coverage
- Update documentation

## [2.5.2] 25th February 2020
* Fix crash on pre-1.12 projects
* Align PermissionStatus on iOS with Android

- Fix crash on pre-1.12 projects
- Align PermissionStatus on iOS with Android

## [2.5.1] 23rd February 2020
* Fix SDK version

- Fix SDK version

## [2.5.0] 23rd February 2020
* [BREAKING] The `requestPermission` and `hasPermission` are now returning PermissionStatus enum.
* Upgrade to Android Embedding V2 (follow https://github.com/flutter/flutter/wiki/Upgrading-pre-1.12-Android-projects if the plugin isn't working after upgrade)
* Resolve getLocation when service is disabled thanks to nicowernli
* Update example app
* Fix bugs leading to non returning code
* `getLocation` now throws properly
* `pub.dev` now states that the plugin is not compatible with Flutter Web (yet)

- [BREAKING] The `requestPermission` and `hasPermission` are now returning PermissionStatus enum.
- Upgrade to Android Embedding V2 (follow https://github.com/flutter/flutter/wiki/Upgrading-pre-1.12-Android-projects if the plugin isn't working after upgrade)
- Resolve getLocation when service is disabled thanks to nicowernli
- Update example app
- Fix bugs leading to non returning code
- `getLocation` now throws properly
- `pub.dev` now states that the plugin is not compatible with Flutter Web (yet)

## [2.4.0] 14th February 2020
* Align timestamp in Android and iOS, previously the iOS timestamp was in seconds instead of milliseconds. Thanks to 781flyingdutchman.

- Align timestamp in Android and iOS, previously the iOS timestamp was in seconds instead of milliseconds. Thanks to 781flyingdutchman.

## [2.3.7] 08th January 2020
* Fix bug where requestPermission is called after the user has already denied the system location dialog, then this method call would never return.

- Fix bug where requestPermission is called after the user has already denied the system location dialog, then this method call would never return.

## [2.3.6] 07th January 2020
* Fix ClassCastException errors on some Android phones when requesting Location status.

- Fix ClassCastException errors on some Android phones when requesting Location status.

## [2.3.5] 10th April 2019
* Fix incompatibily with headless plugins thanks to ehhc
* Fix error with iOS when permission already given
* Add Google maps example

- Fix incompatibily with headless plugins thanks to ehhc
- Fix error with iOS when permission already given
- Add Google maps example

## [2.3.4] 8th April 2019
* Fix error on Android 21 API thanks to noordawod
* Update Google API version

- Fix error on Android 21 API thanks to noordawod
- Update Google API version

## [2.3.3] 31th March 2019
* Align altitude on Sea Level when available on Android (matching iOS altitude).

- Align altitude on Sea Level when available on Android (matching iOS altitude).

## [2.3.2] 27th March 2019
* Remove GPS limitation on Android

- Remove GPS limitation on Android

## [2.3.1] 25th March 2019
* Fixes README
* Fixes requestPermission not responding the correct result on iOS

- Fixes README
- Fixes requestPermission not responding the correct result on iOS

## [2.3.0] 22nd March 2019
* Update example App with proper cancel
* Add possibility to set accuracy, interval and minimum notification ditance of the requests.
* Add LocationAccuracy object

- Update example App with proper cancel
- Add possibility to set accuracy, interval and minimum notification ditance of the requests.
- Add LocationAccuracy object

## [2.2.0] 19th March 2019
* Actually updating locatino when using getLocation (not only relying on LastLocation)
* Add timestamp to LocationData
* Add serviceEnabled method to check whether Location Service is enabled.
* Add requestService method to ask the user to activate the location service.
* Fix continuous callback heading

- Actually updating locatino when using getLocation (not only relying on LastLocation)
- Add timestamp to LocationData
- Add serviceEnabled method to check whether Location Service is enabled.
- Add requestService method to ask the user to activate the location service.
- Fix continuous callback heading

## [2.1.0] 16th Match 2019
* iOS permission should be closer to Android permission behaviour thanks to PerrchicK
* Adding requestPermission(), to manually request permission
* Several feature fixed for less crash when using the plugin
* Code Cleanup
* Update Readme and add a warning for the location bug in iOS simulator

- iOS permission should be closer to Android permission behaviour thanks to PerrchicK
- Adding requestPermission(), to manually request permission
- Several feature fixed for less crash when using the plugin
- Code Cleanup
- Update Readme and add a warning for the location bug in iOS simulator

## [2.0.0] 25th January 2019
* Code cleanup
* BREAKING CHANGE: Change Dart API to return structured data rather than a map.

- Code cleanup
- BREAKING CHANGE: Change Dart API to return structured data rather than a map.

## [1.4.0] 21st August 2018
* Add lazy permission request thanks to yathit
* Add hasPermission() thanks to vagrantrobbie
* Bug correction thanks to jalpedersen
* Add more examples

- Add lazy permission request thanks to yathit
- Add hasPermission() thanks to vagrantrobbie
- Bug correction thanks to jalpedersen
- Add more examples

## [1.3.4] 4th June 2018
* Fix crash for Android API pre 27 thanks to matthewtsmith.

- Fix crash for Android API pre 27 thanks to matthewtsmith.

## [1.3.3] 30th May 2018
* Correct implementation of iOS plugin to match Android behaviour. No need to call getLocation
to get permissions for location callbacks.

- Correct implementation of iOS plugin to match Android behaviour. No need to call getLocation
to get permissions for location callbacks.

## [1.3.2] 30th May 2018
* Change implementation to api in build.gradle in order to solve incompatibilities between
GMS versions thanks to luccascorrea

- Change implementation to api in build.gradle in order to solve incompatibilities between
GMS versions thanks to luccascorrea

## [1.3.1] 29th May 2018
* Added speed and speed_accuracy (only Android truly discover speed accuracy, so its always 0 for now on iOS)
* Solved a crash

- Added speed and speed_accuracy (only Android truly discover speed accuracy, so its always 0 for now on iOS)
- Solved a crash

## [1.3.0] 27th May 2018
* Make it compatible with Firebase thanks to quangIO
* Resolve runtime error exception thanks to jharrison902
* Update gitignore thanks to bcko

- Make it compatible with Firebase thanks to quangIO
- Resolve runtime error exception thanks to jharrison902
- Update gitignore thanks to bcko

## [1.2.0] 5th April 2018
* Permissions denied on Android handled thanks to g123k
* Dart 2 update thanks to efortuna

- Permissions denied on Android handled thanks to g123k
- Dart 2 update thanks to efortuna

## [1.1.6] - 19th Octobre 2017.

* iOS code from Swift to Objective-C thanks to fluff
- iOS code from Swift to Objective-C thanks to fluff

## [1.1.1] - 20th July 2017.

* Fixes for iOS result's format.

- Fixes for iOS result's format.

## [1.1.0] - 17th July 2017.

* Added permission check for Android 6+ (thanks netdur). Still no callback when permissions granted
so aiming SDK 21 is safer.
- Added permission check for Android 6+ (thanks netdur). Still no callback when permissions granted
so aiming SDK 21 is safer.

## [1.0.0] - 7th July 2017.

* Initial Release.
- Initial Release.

0 comments on commit aaaf6c6

Please sign in to comment.