/****************************************************************************
**
** Copyright (C) 2019 Luxoft Sweden AB
** Copyright (C) 2018 Pelagicore AG
** Contact: https://www.qt.io/licensing/
**
** This file is part of the Neptune 3 UI.
**
** $QT_BEGIN_LICENSE:FDL-QTAS$
** Commercial License Usage
** Licensees holding valid commercial Qt Automotive Suite licenses may use
** this file in accordance with the commercial license agreement provided
** with the Software or, alternatively, in accordance with the terms
** contained in a written agreement between you and The Qt Company.  For
** licensing terms and conditions see https://www.qt.io/terms-conditions.
** For further information use the contact form at https://www.qt.io/contact-us.
**
** GNU Free Documentation License Usage
** Alternatively, this file may be used under the terms of the GNU Free
** Documentation License version 1.3 as published by the Free Software
** Foundation and appearing in the file included in the packaging of
** this file. Please review the following information to ensure
** the GNU Free Documentation License version 1.3 requirements
** will be met: https://www.gnu.org/licenses/fdl-1.3.html.
** $QT_END_LICENSE$
**
****************************************************************************/

/*!
   \page neptune3ui-map-application.html
   \title Neptune 3 UI - Maps App
   \brief The Maps App for Neptune 3 UI

   In Neptune 3, a built-in application called "com.pelagicore.map" is included
   as the navigation application that uses MapBox GL plugin as the backend.

   \section1 Qt Location Mapbox GL Plugin Overview

   This geo services plugin allows applications to access Mapbox location-based
   services using the Qt Location API. The use of these services is governed by
   the Mapbox Terms of Service. An access token is required to use these services.
   Data is provided by OpenStreetMap and others.

   See \l{MapBox GL Plugin Documentation} for more information.

   The appearance and behavior of vector maps can be customized by creating custom
   map styles. This can be done with tools like Mapbox Studio. The style url is
   needed by the plugin to load the desired style of the map.

   \section2 Platform Support

   Qt Location Mapbox GL Plugin has the following support for platforms:

   \list
   \li Microsoft Windows (win32) – Supported, requires MinGW 5.0+
   \li Linux X11 – Supported, requires GCC 4.9+
   \li macOS – Supported
   \li Android – Supported
   \li Embedded Linux – Supported, requires GCC 4.9+
   \li iOS – Supported
   \li WinRT – Not supported
   \endlist

   \section1 Application Parameters

   There are parameters required by the Mapbox plugin, e.g. access token, url
   styles, cache directory.

   \section2 Access Token

   To use any of Mapbox’s tools, APIs, or SDKs, the user needs a Mapbox access
   token. Mapbox uses access tokens to associate requests to API resources with
   your account. Currently Neptune 3 is using a dedicated access token from QtAuto
   Mapbox account.

   \badcode
   Parameter name: "mapbox.access_token"
   Access token: pk.eyJ1IjoicXRhdXRvIiwiYSI6ImNqY20wbDZidzBvcTQyd3J3NDlkZ21jdjUifQ.4KYDlP7UmQEVPYffr6VuVQ
   \endcode

   \section2 Style URL

   Additionally, comma separated, Mapbox style URLs can be added to the available
   style URLs. Additional styles will be prepended to the supportedMapTypes
   property of the Map item.

   Neptune 3 has two different styles specified and being used. These two are
   used for Light and Dark theme as part of Neptune 3 feature in changing the
   UI theme.

   \badcode
   readonly property string defaultLightThemeId: "mapbox://styles/qtauto/cjcm1by3q12dk2sqnquu0gju9"
   readonly property string defaultDarkThemeId: "mapbox://styles/qtauto/cjcm1czb812co2sno1ypmp1r8"
   PluginParameter {
               name: "mapboxgl.mapping.additional_style_urls"
               value: [priv.defaultLightThemeId, priv.defaultDarkThemeId].join(",")
   }
   \endcode

   \section2 Cache Directory

   An absolute path to map tile cache directory is used as network disk cache.
   The default place for the cache is the QtLocation/mapboxgl subdirectory
   in the location returned by QStandardPaths::writableLocation(), called
   with QStandardPaths::GenericCacheLocation as a parameter. On systems that
   have no concept of a shared cache, the application-specific
   QStandardPaths::CacheLocation is used instead.

   This is an ambient cache, meaning it will get populated on the fly until
   it reaches the size limit, and when that happens, it will evict the least
   used tiles. This cache can also be used for storing offline tiles, but
   the offline database must be populated using the offline tool. The offline
   database will work alongside with the ambient cache in the same file.
   Make sure to comply with Mapbox Terms of Service before creating an offline
   database.

   \note The map tile cache file name must be "mapboxgl.db". When using the
   offline tool, the default output is "offline.db". For using the generated
   output from the offline tool, you must move this database file to the proper directory,
   and rename it as "mapboxgl.db". The offline tool also provides the "--output"
   parameter for specifying the name of the generated output.

   \note Currently, the offline map is only available for some specific area in
   Munich, Germany (detailed map is only available in light theme due to the
   allowed maximum size of the offline map cache).

   \badcode
   // Offline maps support
   PluginParameter { name: "mapboxgl.mapping.cache.directory";

   // needs to be an absolute filepath so strip the file:/// protocol;
   // several leading slashes don't matter
   value: mapPlugin.cacheDirUrl.toString().substring(mapPlugin.cacheDirUrl.indexOf(':')+1) }
   \endcode
*/