Qt 5.13 | Qt Location | QML Types | Plugin QML Type

Qt 5.13.2 Reference Documentation

# Plugin QML Type

The Plugin type describes a Location based services plugin. More...

Import Statement: | import QtLocation 5.13
Since: | QtLocation 5.5

- List of all members, including inherited members

## Properties

- allowExperimental : bool
- availableServiceProviders : stringlist
- isAttached : bool
- locales : stringlist
- name : string
- parameters : list<PluginParameter>
- preferred : stringlist
- required : enumeration

## Methods

- bool supportsGeocoding(features)
- bool supportsMapping(features)
- bool supportsNavigation(features)
- bool supportsPlaces(features)
- bool supportsRouting(features)

## Detailed Description

The Plugin type is used to declaratively specify which available GeoServices plugin should be used for various tasks in the Location API. Plugins are used by Map, RouteModel, and GeocodeModel types, as well as a variety of others.

Plugins recognized by the system have a name property, a simple string normally indicating the name of the service that the Plugin retrieves data from. They also have a variety of features, which can be test for using the supportsRouting(), supportsGeocoding(), supportsMapping(), supportsPlaces() and supportsNavigation() methods.

When a Plugin object is created, it is "detached" and not associated with any actual service plugin. Once it has received information via setting its name, preferred, or required properties, it will choose an appropriate service plugin to attach to. Plugin objects can only be attached once; to use multiple plugins, create multiple Plugin objects.

### Example Usage

The following snippet shows a Plugin object being created with the required and preferred properties set. This Plugin will attach to the first found plugin that supports both mapping and geocoding, and will prefer plugins named "here" or "osm" to any others.

      Plugin {
          id: plugin
          preferred: ["here", "osm"]
          required: Plugin.AnyMappingFeatures | Plugin.AnyGeocodingFeatures
      }

## Property Documentation

allowExperimental : bool

This property indicates if experimental plugins can be used.

availableServiceProviders : stringlist

This property holds a list of all available service plugins' names. This can be used to manually enumerate the available plugins if the control provided by name and required is not sufficient for your needs.

isAttached : bool

This property indicates if the Plugin item is attached to a geoservice provider plugin.

locales : stringlist

This property contains an ordered list of preferred plugin locales. If the first locale cannot be accommodated, then the backend falls back to using the second, and so on. By default the locales property contains the system locale.

The locales are specified as strings which have the format "language[_script][_country]" or "C", where:

- language is a lowercase, two-letter, ISO 639 language code,
- script is a titlecase, four-letter, ISO 15924 script code,
- country is an uppercase, two- or three-letter, ISO 3166 country code (also "419" as defined by United Nations),
- the "C" locale is identical in behavior to English/UnitedStates as per QLocale

If the first specified locale cannot be accommodated, the Plugin falls back to the next and so forth. Some Plugin backends may not support a set of locales which are rigidly defined. An arbitrary example is that some Place's in France could have French and English localizations, while certain areas in America may only have the English localization available. In the above scenario, the set of supported locales is context dependent on the search location.

If the Plugin cannot accommodate any of the preferred locales, the manager falls back to using a supported language that is backend specific.

For Plugin's that do not support locales, the locales list is always empty.

The following code demonstrates how to set a single and multiple locales:

      //single locale
      Plugin {
          locales: "en_US"
      }

      //multiple locales
      Plugin {
          locales: ["fr_FR","en_US"]
      }

name : string

This property holds the name of the plugin. Setting this property will cause the Plugin to only attach to a plugin with exactly this name. The value of required will be ignored.

[default] parameters : list<PluginParameter>

This property holds the list of plugin parameters.

preferred : stringlist

This property contains an ordered list of preferred plugin names, which will be checked for the required features set in required before any other available plugins are checked.

required : enumeration

This property contains the set of features that will be required by the Plugin object when choosing which service plugin to attach to. If the name property is set, this has no effect.

Any of the following values or a bitwise combination of multiple values may be set:

- Plugin.NoFeatures
- Plugin.GeocodingFeature
- Plugin.ReverseGeocodingFeature
- Plugin.RoutingFeature
- Plugin.MappingFeature
- Plugin.AnyPlacesFeature

## Method Documentation

bool supportsGeocoding(features)

This method returns a boolean indicating whether the specified set of features are supported by the geo service provider plugin. `True` is returned if all specified features are supported; otherwise `false` is returned.

The features parameter can be any flag combination of:

Feature | Description
--- | ---
Plugin.NoGeocodingFeatures | No geocoding features are supported.
Plugin.OnlineGeocodingFeature | Online geocoding is supported.
Plugin.OfflineGeocodingFeature | Offline geocoding is supported.
Plugin.ReverseGeocodingFeature | Reverse geocoding is supported.
Plugin.LocalizedGeocodingFeature | Supports returning geocoding results with localized addresses.
Plugin.AnyGeocodingFeatures | Matches a geo service provider that provides any geocoding features.

bool supportsMapping(features)

This method returns a boolean indicating whether the specified set of features are supported by the geo service provider plugin. True is returned if all specified features are supported; otherwise false is returned.

The features parameter can be any flag combination of:

Feature | Description
--- | ---
Plugin.NoMappingFeatures | No mapping features are supported.
Plugin.OnlineMappingFeature | Online mapping is supported.
Plugin.OfflineMappingFeature | Offline mapping is supported.
Plugin.LocalizedMappingFeature | Supports returning localized map data.
Plugin.AnyMappingFeatures | Matches a geo service provider that provides any mapping features.

bool supportsNavigation(features)

This method returns a boolean indicating whether the specified set of features are supported by the geo service provider plugin. True is returned if all specified features are supported; otherwise false is returned.

The features parameter can be any flag combination of:

Feature | Description
--- | ---
Plugin.NoNavigationFeatures | No navigation features are supported.
Plugin.OnlineNavigationFeature | Online navigation is supported.
Plugin.OfflineNavigationFeature | Offline navigation is supported.
Plugin.AnyNavigationFeatures | Matches a geo service provider that provides any navigation features.

bool supportsPlaces(features)

This method returns a boolean indicating whether the specified set of features are supported by the geo service provider plugin. True is returned if all specified features are supported; otherwise false is returned.

The features parameter can be any flag combination of:

Feature | Description
--- | ---
Plugin.NoPlacesFeatures | No places features are supported.
Plugin.OnlinePlacesFeature | Online places is supported.
Plugin.OfflinePlacesFeature | Offline places is supported.
Plugin.SavePlaceFeature | Saving categories is supported.
Plugin.RemovePlaceFeature | Removing or deleting places is supported.
Plugin.PlaceRecommendationsFeature | Searching for recommended places similar to another place is supported.
Plugin.SearchSuggestionsFeature | Search suggestions is supported.
Plugin.LocalizedPlacesFeature | Supports returning localized place data.
Plugin.NotificationsFeature | Notifications of place and category changes is supported.
Plugin.PlaceMatchingFeature | Supports matching places from two different geo service providers.
Plugin.AnyPlacesFeatures | Matches a geo service provider that provides any places features.

bool supportsRouting(features)

This method returns a boolean indicating whether the specified set of features are supported by the geo service provider plugin. True is returned if all specified features are supported; otherwise false is returned.

The features parameter can be any flag combination of:

Feature | Description
--- | ---
Plugin.NoRoutingFeatures | No routing features are supported.
Plugin.OnlineRoutingFeature | Online routing is supported.
Plugin.OfflineRoutingFeature | Offline routing is supported.
Plugin.LocalizedRoutingFeature | Supports returning routes with localized addresses and instructions.
Plugin.RouteUpdatesFeature | Updating an existing route based on the current position is supported.
Plugin.AlternativeRoutesFeature | Supports returning alternative routes.
Plugin.ExcludeAreasRoutingFeature | Supports specifying a areas which the returned route must not cross.
Plugin.AnyRoutingFeatures | Matches a geo service provider that provides any routing features.