diff --git a/geolocator_platform_interface/CHANGELOG.md b/geolocator_platform_interface/CHANGELOG.md index a7d475370..feac73793 100644 --- a/geolocator_platform_interface/CHANGELOG.md +++ b/geolocator_platform_interface/CHANGELOG.md @@ -2,6 +2,10 @@ - Updated `flutter_lints` to version `^5.0.0`. +## 4.2.7 + +- Clarifies the documentation of `Position.heading` to explain that it carries the course over ground (direction of travel, from `Location.getBearing()` on Android and `CLLocation.course` on iOS), which is distinct from compass heading. The field keeps the `heading` name for backward compatibility. Resolves [#1187](https://github.com/Baseflow/flutter-geolocator/issues/1187). + ## 4.2.6 - Updates documentation `isMocked` to bring it in line with the functionality. `isMocked` for iOS 15 and higher depends on the result from isSimulatedBySoftware. diff --git a/geolocator_platform_interface/lib/src/models/position.dart b/geolocator_platform_interface/lib/src/models/position.dart index 2121bb1d5..51121f588 100644 --- a/geolocator_platform_interface/lib/src/models/position.dart +++ b/geolocator_platform_interface/lib/src/models/position.dart @@ -50,10 +50,22 @@ class Position { /// 0.0. final double accuracy; - /// The heading in which the device is traveling in degrees. + /// The course over ground (direction of travel) in degrees. /// - /// The heading is not available on all devices. In these cases the value is - /// 0.0. + /// This reports the direction in which the device is *moving* across the + /// ground, in degrees clockwise relative to true north (0.0 to 360.0). It is + /// derived from the platform's GPS-based value: `Location.getBearing()` on + /// Android and `CLLocation.course` on iOS. + /// + /// This is distinct from compass heading: it does *not* report the direction + /// the device is physically pointing (the magnetometer/compass reading). A + /// stationary device has no meaningful course over ground. + /// + /// The field is named `heading` for backward compatibility; despite the name + /// it carries the course-over-ground value described above. + /// + /// The course is not available on all devices, and may be unavailable while + /// the device is not moving. In these cases the value is 0.0. final double heading; /// The estimated heading accuracy of the position in degrees. diff --git a/geolocator_platform_interface/pubspec.yaml b/geolocator_platform_interface/pubspec.yaml index 152201786..bc128cf24 100644 --- a/geolocator_platform_interface/pubspec.yaml +++ b/geolocator_platform_interface/pubspec.yaml @@ -3,7 +3,7 @@ description: A common platform interface for the geolocator plugin. repository: https://github.com/baseflow/flutter-geolocator/tree/main/geolocator_platform_interface # NOTE: We strongly prefer non-breaking changes, even at the expense of a # less-clean API. See https://flutter.dev/go/platform-interface-breaking-changes -version: 4.2.6 +version: 4.2.7 dependencies: