From d5b78f9d5b3d48b2ef6a414578e93132361f59f7 Mon Sep 17 00:00:00 2001 From: aki1770-del Date: Mon, 8 Jun 2026 18:10:16 +0900 Subject: [PATCH] docs: clarify that Position.heading carries course over ground (#1187) Position.heading is named "heading" but actually carries course over ground (direction of travel), not compass heading. Update the dartdoc to explain this; keep the heading name for backward compatibility. The value comes from Location.getBearing() on Android and CLLocation.course on iOS. Bump geolocator_platform_interface to 4.2.7 and add a CHANGELOG entry, as requested by the maintainer in #1187. --- geolocator_platform_interface/CHANGELOG.md | 4 ++++ .../lib/src/models/position.dart | 18 +++++++++++++++--- geolocator_platform_interface/pubspec.yaml | 2 +- 3 files changed, 20 insertions(+), 4 deletions(-) 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: