Merge remote-tracking branch 'origin/5.12' into dev

 Conflicts:
	.qmake.conf

Change-Id: I0724ca9ffbb8099f698b090a4fdd993fad2c2302

1 files changed, 49 insertions, 9 deletions

diff --git a/src/positioning/qgeopositioninfosource.cpp b/src/positioning/qgeopositioninfosource.cpp
index cafb4f8a..2e126175 100644
--- a/src/positioning/qgeopositioninfosource.cpp
+++ b/src/positioning/qgeopositioninfosource.cpp
@@ -241,8 +241,10 @@ int QGeoPositionInfoSource::updateInterval() const
     If \a methods includes a method that is not supported by the source, the
     unsupported method will be ignored.
 
-    If \a methods does not include any methods supported by the source, the
-    preferred methods will be set to the set of methods which the source supports.
+    If \a methods does not include a single method available/supported by the source, the
+    preferred methods will be set to the set of methods which the source has available.
+    If the source has no method availabe (e.g. because its Location service is turned off
+    or it does not offer a Location service), the passed \a methods are accepted as they are.
 
     \b {Note:} When reimplementing this method, subclasses must call the
     base method implementation to ensure preferredPositioningMethods() returns the correct value.
@@ -251,9 +253,13 @@ int QGeoPositionInfoSource::updateInterval() const
 */
 void QGeoPositionInfoSource::setPreferredPositioningMethods(PositioningMethods methods)
 {
-    d->methods = methods & supportedPositioningMethods();
-    if (d->methods == 0) {
-        d->methods = supportedPositioningMethods();
+    if (supportedPositioningMethods() != QGeoPositionInfoSource::NoPositioningMethods) {
+        d->methods = methods & supportedPositioningMethods();
+        if (d->methods == 0) {
+            d->methods = supportedPositioningMethods();
+        }
+    } else { // avoid that turned of Location service blocks any changes to d->methods
+        d->methods = methods;
     }
 }
 
@@ -355,9 +361,40 @@ QStringList QGeoPositionInfoSource::availableSources()
 /*!
     \fn virtual PositioningMethods QGeoPositionInfoSource::supportedPositioningMethods() const = 0;
 
-    Returns the positioning methods available to this source.
-
-    \sa setPreferredPositioningMethods()
+    Returns the positioning methods available to this source. Availability is defined as being usable
+    at the time of calling this function. Therefore user settings like turned off location service or
+    limitations to Satellite-based position providers are reflected by this function. Runtime notifications
+    when the status changes can be obtained via \l supportedPositioningMethodsChanged().
+
+    Not all platforms distinguish the different positioning methods or communicate the current user
+    configuration of the device. The following table provides an overview of the current platform situation:
+
+    \table
+    \header
+        \li Platform
+        \li Brief Description
+    \row
+        \li Android
+        \li Individual provider status and general Location service state are known and communicated
+            when location service is active.
+    \row
+        \li GeoClue
+        \li Hardcoced to always return AllPositioningMethods.
+    \row
+        \li GeoClue2
+        \li Individual providers are not distinguishable but disabled Location services reflected.
+    \row
+        \li iOS/tvOS
+        \li Hardcoced to always return AllPositioningMethods.
+    \row
+        \li macOS
+        \li Hardcoced to always return AllPositioningMethods.
+    \row
+        \li Windows (UWP)
+        \li Individual providers are not distinguishable but disabled Location services reflected.
+    \endtable
+
+    \sa supportedPositioningMethodsChanged(), setPreferredPositioningMethods()
 */
 
 
@@ -479,7 +516,10 @@ QStringList QGeoPositionInfoSource::availableSources()
 /*!
     \fn void QGeoPositionInfoSource::supportedPositioningMethodsChanged()
 
-    This signal is emitted after the supportedPositioningMethods change.
+    This signal is emitted when the supported positioning methods changed. The cause for a change could be
+    a user turning Location services on/off or restricting Location services to certain types (e.g. GPS only).
+    Note that changes to the supported positioning methods cannot be detected on all platforms.
+    \l supportedPositioningMethods() provides an overview of the current platform support.
 
     \since Qt 5.12
 */