Allow specification of locale preferences

The manager now accepts a list of locales.  If the first locale
cannot be accommodate, the manager falls back to the next.

For those managers that do support locales, the default set of locales
contains just the global default locale.

Change-Id: Iaf6511e18e22fe3c8bd6a8a0ee6077c2827d664c
Reviewed-by: Aaron McCarthy <aaron.mccarthy@nokia.com>

4 files changed, 41 insertions, 15 deletions

diff --git a/src/location/places/qplacemanager.cpp b/src/location/places/qplacemanager.cpp
index 37946e09..ecd568f1 100644
--- a/src/location/places/qplacemanager.cpp
+++ b/src/location/places/qplacemanager.cpp
@@ -350,21 +350,38 @@ QList<QPlaceCategory> QPlaceManager::childCategories(const QString &parentId) co
 }
 
 /*!
-    Returns the locale of the manager.
-    The locale is used as a hint to determine
-    what language place data should be returned in.
+    Returns a list of prefered locales. The locales are used as a hint to the manager for what language
+    place and category details should be returned in.
+
+    If the first specified locale cannot be accommodated, the manager falls back to the next and so forth.
+
+    Support for locales may vary from provider to provider.  For those that do support it,
+    by default, the global default locale is set as the manager's only locale.  If the manager
+    has no locales assigned to it, it impliclty uses the global default locale.
+    For managers that do not support locales, the locale list is always empty.
 */
-QLocale QPlaceManager::locale() const
+QList<QLocale> QPlaceManager::locales() const
 {
-    return d->locale();
+    return d->locales();
 }
 
 /*!
-    Sets the \a locale of the manager.
+    Convenience function which sets the manager's list of preferred locales
+    to a single \a locale.
 */
 void QPlaceManager::setLocale(const QLocale &locale)
 {
-    d->setLocale(locale);
+    QList<QLocale> locales;
+    locales << locale;
+    d->setLocales(locales);
+}
+
+/*!
+    Set the list of preferred \a locales.
+*/
+void QPlaceManager::setLocales(const QList<QLocale> &locales)
+{
+    d->setLocales(locales);
 }
 
 /*!
diff --git a/src/location/places/qplacemanager.h b/src/location/places/qplacemanager.h
index a6358a5c..97e068f7 100644
--- a/src/location/places/qplacemanager.h
+++ b/src/location/places/qplacemanager.h
@@ -113,8 +113,9 @@ public:
     QPlaceCategory category(const QString &categoryId) const;
     QList<QPlaceCategory> childCategories(const QString &parentId = QString()) const;
 
-    QLocale locale() const;
+    QList<QLocale> locales() const;
     void setLocale(const QLocale &locale);
+    void setLocales(const QList<QLocale> &locale);
 
     ManagerFeatures supportedFeatures() const;
 
diff --git a/src/location/places/qplacemanagerengine.cpp b/src/location/places/qplacemanagerengine.cpp
index 652cba0a..ac0fcfd7 100644
--- a/src/location/places/qplacemanagerengine.cpp
+++ b/src/location/places/qplacemanagerengine.cpp
@@ -239,16 +239,24 @@ QPlaceManagerEnginePrivate::~QPlaceManagerEnginePrivate()
 */
 
 /*!
-    \fn QLocale QPlaceManagerEngine ::locale() const
+    \fn QList<QLocale> QPlaceManagerEngine::locales() const
 
-    Returns the locale of the manager engine. The locale is used as a hint to determine
-    what language place data should be returned in.
+/*!
+    Returns a list of prefered locales. The locales are used as a hint to the manager engine for what language
+    place and category details should be returned in.
+
+    If the first specified locale cannot be accommodated, the manager engine falls back to the next and so forth.
+
+    Support for locales may vary from provider to provider.  For those that do support it,
+    by default, the global default locale is set as the manager engine's only locale.  If the
+    manager engine has no locales assigned to it, it impliclty uses the global default locale.
+    For engines that do not support locales, the locale list is always empty.
 */
 
 /*!
-    \fn void QPlaceManagerEngine::setLocale(const QLocale &locale)
+    \fn void QPlaceManagerEngine::setLocales(const QList<QLocale> &locales)
 
-    Sets the \a locale of the manager engine.
+    Set the list of preferred \a locales.
 */
 
 /*!
diff --git a/src/location/places/qplacemanagerengine.h b/src/location/places/qplacemanagerengine.h
index 568d5999..a0a01124 100644
--- a/src/location/places/qplacemanagerengine.h
+++ b/src/location/places/qplacemanagerengine.h
@@ -85,8 +85,8 @@ public:
 
     virtual QList<QPlaceCategory> childCategories(const QString &parentId) const = 0;
 
-    virtual QLocale locale() const = 0;
-    virtual void setLocale(const QLocale &locale) = 0;
+    virtual QList<QLocale> locales() const = 0;
+    virtual void setLocales(const QList<QLocale> &locales) = 0;
 
     virtual QUrl constructIconUrl(const QPlaceIcon &icon, const QSize &size, QPlaceIcon::IconFlags flags) = 0;
     virtual QPlaceManager::ManagerFeatures supportedFeatures() const = 0;