The Settings class stores the initial configuration for Map. More...

#include <QMapLibre/Settings>

Public Types
enum	GLContextMode : bool { UniqueGLContext , SharedGLContext }

enum	MapMode { Continuous = 0 , Static }

enum	ConstrainMode { NoConstrain = 0 , ConstrainHeightOnly , ConstrainWidthAndHeight }

enum	ViewportMode { DefaultViewport = 0 , FlippedYViewport }

enum	ProviderTemplate { NoProvider = 0 , MapLibreProvider , MapTilerProvider , MapboxProvider }

using	ResourceTransformFunction = std::function<std::string(const std::string &)>
	Resource transformation callback type.

Public Member Functions
	Settings (ProviderTemplate provider=NoProvider)
	Default constructor.

	Settings (const Settings &s)
	Copy constructor.

	Settings (Settings &&s) noexcept
	Move constructor.

Settings &	operator= (const Settings &s)
	Copy assignment operator.

Settings &	operator= (Settings &&s) noexcept
	Move assignment operator.

GLContextMode	contextMode () const
	Get the OpenGL context mode.

void	setContextMode (GLContextMode)
	Set the OpenGL context mode.

MapMode	mapMode () const
	Get the map mode.

void	setMapMode (MapMode)
	Set the map mode.

ConstrainMode	constrainMode () const
	Get the constrain mode.

void	setConstrainMode (ConstrainMode)
	Set the map constrain mode.

ViewportMode	viewportMode () const
	Get the viewport mode.

void	setViewportMode (ViewportMode)
	Set the viewport mode.

unsigned	cacheDatabaseMaximumSize () const
	Get the cache database maximum size.

void	setCacheDatabaseMaximumSize (unsigned)
	Set the maximum allowed cache database size in bytes.

QString	cacheDatabasePath () const
	Get the cache database path.

void	setCacheDatabasePath (const QString &path)
	Set the cache database path.

QString	assetPath () const
	Get the asset path.

void	setAssetPath (const QString &path)
	Set the asset path.

QString	apiKey () const
	Get the API key.

void	setApiKey (const QString &key)
	Set the API key.

QString	apiBaseUrl () const
	Get the API base URL.

void	setApiBaseUrl (const QString &url)
	Set the API base url.

QString	localFontFamily () const
	Get the local font family.

void	setLocalFontFamily (const QString &family)
	Set the local font family.

QString	clientName () const
	Get the client name.

void	setClientName (const QString &name)
	Set the client name.

QString	clientVersion () const
	Get the client version.

void	setClientVersion (const QString &version)
	Set the client version.

ResourceTransformFunction	resourceTransform () const
	Get resource transformation callback used to transform requested URLs.

void	setResourceTransform (const ResourceTransformFunction &transform)
	Sets the resource transform callback.

void	setProviderTemplate (ProviderTemplate providerTemplate)
	Reset all settings based on the given template.

void	setStyles (const Styles &styles)
	Set the map styles.

const Styles &	styles () const
	Get map styles set by user.

Styles	providerStyles () const
	All predefined provider styles.

Coordinate	defaultCoordinate () const
	Get the default coordinate.

void	setDefaultCoordinate (const Coordinate &coordinate)
	Set the default coordinate.

double	defaultZoom () const
	Get the default zoom level.

void	setDefaultZoom (double zoom)
	Set the default zoom level.

bool	customTileServerOptions () const
	Check whether the tile server options have been set by the user.

const mbgl::TileServerOptions &	tileServerOptions () const
	Get the provider tile server options.

Detailed Description

The Settings class stores the initial configuration for Map.

Settings is used to configure Map at the moment of its creation. Once created, the Settings of a Map can no longer be changed.

Cache-related settings are shared between all Map instances using the same cache path. The first map to configure cache properties such as size will force the configuration to all newly instantiated Map objects using the same cache in the same process.

Member Typedef Documentation

◆ ResourceTransformFunction

using QMapLibre::Settings::ResourceTransformFunction = std::function<std::string(const std::string &)>

Resource transformation callback type.

This callback is used to transform the requested resource URLs before they are requested from internet. This can be used add or remove custom parameters, or reroute certain requests to other servers or endpoints.

See also: resourceTransform(); setResourceTransform()

Member Enumeration Documentation

◆ ConstrainMode

enum QMapLibre::Settings::ConstrainMode

This enum determines if the map wraps.

See also: constrainMode()

Enumerator
NoConstrain	The map will wrap on the horizontal axis. Since it doesn't make sense to wrap on the vertical axis in a Web Mercator projection, the map will scroll and show some empty space.
ConstrainHeightOnly	The map will wrap around the horizontal axis, like a spinning globe. This is the recommended constrain mode.
ConstrainWidthAndHeight	The map won't wrap and panning is restricted to the boundaries of the map.

◆ GLContextMode

enum QMapLibre::Settings::GLContextMode : bool

This enum sets the expectations for the OpenGL state.

See also: contextMode()

Enumerator
UniqueGLContext	The OpenGL context is only used by Map, so it is not reset before each rendering. Use this mode if the intention is to only draw a fullscreen map.
SharedGLContext	The OpenGL context is shared and the state will be marked dirty - which invalidates any previously assumed GL state. The embedder is responsible for clearing up the viewport prior to calling Map::render. The embedder is also responsible for resetting its own GL state after Map::render has finished, if needed.

◆ MapMode

enum QMapLibre::Settings::MapMode

This enum sets the map rendering mode

See also: mapMode()

Enumerator

Continuous

The map will render as data arrives from the network and react immediately to state changes.

This is the default mode and the preferred when the map is intended to be interactive.

Static

The map will no longer react to state changes and will only be rendered when Map::startStaticRender is called. After all the resources are loaded, the Map::staticRenderFinished signal is emitted.

This mode is useful for taking a snapshot of the finished rendering result of the map into a QImage.

◆ ProviderTemplate

enum QMapLibre::Settings::ProviderTemplate

This enum sets the default configuration for a specific provider.

See also: setProviderTemplate()

Enumerator
NoProvider	No template is set. This is the default value.
MapLibreProvider	The template for MapLibre-hosted vector tiles and styles.
MapTilerProvider	The template for MapTiler-hosted vector tiles and styles.
MapboxProvider	The template for Mapbox-hosted vector tiles and styles.

◆ ViewportMode

enum QMapLibre::Settings::ViewportMode

This enum flips the map vertically.

See also: viewportMode()

Enumerator
DefaultViewport	The map is rendered in its native orientation.
FlippedYViewport	The map is rendered upside down.

Constructor & Destructor Documentation

◆ Settings()

QMapLibre::Settings::Settings ( ProviderTemplate provider = NoProvider )

explicit

Default constructor.

Parameters

provider The provider template to use.

Constructs a Settings object with the default values. The default configuration is not valid for initializing a Map, but a provider template can be provided.

Member Function Documentation

◆ apiBaseUrl()

QString QMapLibre::Settings::apiBaseUrl ( ) const

nodiscard

Get the API base URL.

Returns: The API base URL as QString.

Only works if a provider template is set. Otherwise, it returns an empty string.

See also: setProviderTemplate()

◆ apiKey()

QString QMapLibre::Settings::apiKey ( ) const

nodiscard

Get the API key.

Returns: The API key as QString.

By default, it is taken from the environment variable MLN_API_KEY or empty if the variable is not set.

◆ assetPath()

QString QMapLibre::Settings::assetPath ( ) const

nodiscard

Get the asset path.

Returns: The asset path as QString.

Returns the asset path, which is the root directory from where the asset:// scheme gets resolved in a style. asset:// can be used for loading a resource from the disk in a style rather than fetching it from the network.

By default, it is set to the value returned by QCoreApplication::applicationDirPath().

◆ cacheDatabaseMaximumSize()

unsigned QMapLibre::Settings::cacheDatabaseMaximumSize ( ) const

nodiscard

Get the cache database maximum size.

Returns: The cache database maximum size.

Returns the cache database maximum hard size in bytes. The database will grow until the limit is reached. Setting a maximum size smaller than the current size of an existing database results in undefined behavior

By default, it is set to 50 MB.

◆ cacheDatabasePath()

QString QMapLibre::Settings::cacheDatabasePath ( ) const

nodiscard

Get the cache database path.

Returns: The cache database path as QString.

Returns the cache database path. The cache is used for storing recently used resources like tiles and also an offline tile database pre-populated by the Offline Tool.

By default, it is set to :memory: meaning it will create an in-memory cache instead of a file on disk.

◆ clientName()

QString QMapLibre::Settings::clientName ( ) const

nodiscard

Get the client name.

Returns: The client name as QString.

Returns an empty string if no client name is set.

◆ clientVersion()

QString QMapLibre::Settings::clientVersion ( ) const

nodiscard

Get the client version.

Returns: The client version as QString.

Returns an empty string if no client version is set.

◆ constrainMode()

Settings::ConstrainMode QMapLibre::Settings::constrainMode ( ) const

nodiscard

Get the constrain mode.

Returns: The constrain mode.

Returns the constrain mode. This is used to limit the map to wrap around the globe horizontally.

By default, it is set to Settings::ConstrainHeightOnly.

◆ contextMode()

Settings::GLContextMode QMapLibre::Settings::contextMode ( ) const

nodiscard

Get the OpenGL context mode.

Returns: The OpenGL context mode.

Returns the OpenGL context mode. This is specially important when mixing with other OpenGL draw calls.

By default, it is set to Settings::SharedGLContext.

◆ customTileServerOptions()

bool QMapLibre::Settings::customTileServerOptions ( ) const

nodiscard

Check whether the tile server options have been set by the user.

Returns: true if the tile server options have been set by the user.

◆ defaultCoordinate()

Coordinate QMapLibre::Settings::defaultCoordinate ( ) const

nodiscard

Get the default coordinate.

Returns: The default coordinate.

◆ defaultZoom()

double QMapLibre::Settings::defaultZoom ( ) const

nodiscard

Get the default zoom level.

Returns: The default zoom level.

◆ localFontFamily()

QString QMapLibre::Settings::localFontFamily ( ) const

nodiscard

Get the local font family.

Returns: The local font family as QString.

Returns an empty string if no local font family is set.

◆ mapMode()

Settings::MapMode QMapLibre::Settings::mapMode ( ) const

nodiscard

Get the map mode.

Returns: The map mode.

Returns the map mode. Static mode will emit a signal for rendering a map only when the map is fully loaded. Animations like style transitions and labels fading won't be seen.

The Continuous mode will emit the signal for every new change on the map and it is usually what you expect for a interactive map.

By default, it is set to Settings::Continuous.

◆ providerStyles()

Styles QMapLibre::Settings::providerStyles ( ) const

nodiscard

All predefined provider styles.

Returns: The provider styles.

Returns all styles that are defined in provider settings template.

◆ resourceTransform()

Settings::ResourceTransformFunction QMapLibre::Settings::resourceTransform ( ) const

nodiscard

Get resource transformation callback used to transform requested URLs.

Returns: The resource transformation callback.

◆ setApiBaseUrl()

void QMapLibre::Settings::setApiBaseUrl ( const QString & url )

Set the API base url.

Parameters

url	The API base URL.

The API base URL is the URL that the mapbox:// protocol will be resolved to. It defaults to https://api.mapbox.com but can be changed, for instance, to a tile cache server address.

◆ setApiKey()

void QMapLibre::Settings::setApiKey ( const QString & key )

Set the API key.

Parameters

key	The API key.

MapTiler-hosted and Mapbox-hosted vector tiles and styles require an API key or access token.

◆ setAssetPath()

void QMapLibre::Settings::setAssetPath ( const QString & path )

Set the asset path.

Parameters

path	The asset path.

◆ setCacheDatabaseMaximumSize()

void QMapLibre::Settings::setCacheDatabaseMaximumSize ( unsigned size )

Set the maximum allowed cache database size in bytes.

Parameters

size	The maximum allowed cache database size in bytes.

◆ setCacheDatabasePath()

void QMapLibre::Settings::setCacheDatabasePath ( const QString & path )

Set the cache database path.

Parameters

path	The cache database path.

Setting the path to :memory: will create an in-memory cache.

◆ setClientName()

void QMapLibre::Settings::setClientName ( const QString & name )

Set the client name.

Parameters

name	The client name.

◆ setClientVersion()

void QMapLibre::Settings::setClientVersion ( const QString & version )

Set the client version.

Parameters

version The client version.

◆ setConstrainMode()

void QMapLibre::Settings::setConstrainMode ( ConstrainMode mode )

Set the map constrain mode.

Parameters

mode	The constrain mode.

◆ setContextMode()

void QMapLibre::Settings::setContextMode ( GLContextMode mode )

Set the OpenGL context mode.

Parameters

mode	The OpenGL context mode.

◆ setDefaultCoordinate()

void QMapLibre::Settings::setDefaultCoordinate ( const Coordinate & coordinate )

Set the default coordinate.

Parameters

coordinate The default coordinate.

◆ setDefaultZoom()

void QMapLibre::Settings::setDefaultZoom ( double zoom )

Set the default zoom level.

Parameters

zoom	The default zoom level.

◆ setLocalFontFamily()

void QMapLibre::Settings::setLocalFontFamily ( const QString & family )

Set the local font family.

Parameters

family The local font family.

Rendering Chinese/Japanese/Korean (CJK) ideographs and precomposed Hangul Syllables requires downloading large amounts of font data, which can significantly slow map load times. Use the localFontFamily setting to speed up map load times by using locally available fonts instead of font data fetched from the server.

◆ setMapMode()

void QMapLibre::Settings::setMapMode ( MapMode mode )

Set the map mode.

Parameters

mode	The map mode.

◆ setProviderTemplate()

void QMapLibre::Settings::setProviderTemplate ( ProviderTemplate providerTemplate )

Reset all settings based on the given template.

Parameters

providerTemplate The provider template.

MapLibre can support servers with different resource path structure. Some of the most common servers like Maptiler and Mapbox are defined in the library. This function will re-initialise all settings based on the default values of specific service provider defaults.

See also: apiBaseUrl(); providerStyles()

◆ setResourceTransform()

void QMapLibre::Settings::setResourceTransform ( const ResourceTransformFunction & transform )

Sets the resource transform callback.

Parameters

transform The resource transformation callback.

When given, resource transformation callback will be used to transform the requested resource URLs before they are requested from internet. This can be used add or remove custom parameters, or reroute certain requests to other servers or endpoints.

◆ setStyles()

void QMapLibre::Settings::setStyles ( const Styles & styles )

Set the map styles.

Parameters

styles The map styles.

The styles are a list type Style (wrapped in the helper Styles). Each style is a pair of URL and name/label.

◆ setViewportMode()

void QMapLibre::Settings::setViewportMode ( ViewportMode mode )

Set the viewport mode.

Parameters

mode	The viewport mode.

◆ styles()

const Styles & QMapLibre::Settings::styles ( ) const

nodiscard

Get map styles set by user.

Returns: The map styles.

The styles are a list of type Style (wrapped in the helper Styles). Each style is a pair of URL and name/label.

◆ tileServerOptions()

const mbgl::TileServerOptions & QMapLibre::Settings::tileServerOptions ( ) const

nodiscard

Get the provider tile server options.

Warning: Mainly for internal use.

◆ viewportMode()

Settings::ViewportMode QMapLibre::Settings::viewportMode ( ) const

nodiscard

Get the viewport mode.

Returns: The viewport mode.

Returns the viewport mode. This is used to flip the vertical orientation of the map as some devices may use inverted orientation.

By default, it is set to Settings::DefaultViewport.

Public Types

Public Member Functions

Detailed Description

Member Typedef Documentation

◆ ResourceTransformFunction

Member Enumeration Documentation

◆ ConstrainMode

◆ GLContextMode

◆ MapMode

◆ ProviderTemplate

◆ ViewportMode

Constructor & Destructor Documentation

◆ Settings()

Member Function Documentation

◆ apiBaseUrl()

◆ apiKey()

◆ assetPath()

◆ cacheDatabaseMaximumSize()

◆ cacheDatabasePath()

◆ clientName()

◆ clientVersion()

◆ constrainMode()

◆ contextMode()

◆ customTileServerOptions()

◆ defaultCoordinate()

◆ defaultZoom()

◆ localFontFamily()

◆ mapMode()

◆ providerStyles()

◆ resourceTransform()

◆ setApiBaseUrl()

◆ setApiKey()

◆ setAssetPath()

◆ setCacheDatabaseMaximumSize()

◆ setCacheDatabasePath()

◆ setClientName()

◆ setClientVersion()

◆ setConstrainMode()

◆ setContextMode()

◆ setDefaultCoordinate()

◆ setDefaultZoom()

◆ setLocalFontFamily()

◆ setMapMode()

◆ setProviderTemplate()

◆ setResourceTransform()

◆ setStyles()

◆ setViewportMode()

◆ styles()

◆ tileServerOptions()

◆ viewportMode()