A map is a container for layers. Use a map together with a MapView to display layers of geographic data in 2D. More...
| Header: | #include <Map.h> |
| Since: | Esri::ArcGISRuntime 100.0 |
| Inherits: | Esri::ArcGISRuntime::GeoModel and Esri::ArcGISRuntime::JsonSerializable |
Public Functions
| Map(QObject *parent = nullptr) | |
| Map(const QUrl &url, QObject *parent = nullptr) | |
| Map(Esri::ArcGISRuntime::Basemap *basemap, QObject *parent = nullptr) | |
| Map(Esri::ArcGISRuntime::Item *item, QObject *parent = nullptr) | |
| Map(const Esri::ArcGISRuntime::SpatialReference &spatialReference, QObject *parent = nullptr) | |
| Map(Esri::ArcGISRuntime::BasemapStyle basemapStyle, QObject *parent = nullptr) | |
| virtual | ~Map() override |
| QColor | backgroundColor() const |
| Esri::ArcGISRuntime::IndoorPositioningDefinition * | indoorPositioningDefinition() const |
| Esri::ArcGISRuntime::Envelope | maxExtent() const |
| double | maxScale() const |
| double | minScale() const |
| QFuture<QList<Esri::ArcGISRuntime::UtilityNamedTraceConfiguration *>> | namedTraceConfigurationsFromUtilityNetworkAsync(Esri::ArcGISRuntime::UtilityNetwork *utilityNetwork, QObject *parent = nullptr) |
| Esri::ArcGISRuntime::OfflineSettings * | offlineSettings() const |
| double | referenceScale() const |
| QFuture<void> | saveAsAsync(Esri::ArcGISRuntime::Portal *portal, const QString &title, const QStringList &tags, bool forceSaveToSupportedVersion, const Esri::ArcGISRuntime::PortalFolder &folder = PortalFolder(), const QString &description = QString(), const QByteArray &thumbnailBytes = QByteArray()) |
| QFuture<void> | saveAsync(bool forceSaveToSupportedVersion) |
| void | setBackgroundColor(const QColor &backgroundColor) |
| void | setMaxExtent(const Esri::ArcGISRuntime::Envelope &maxExtent) |
| void | setMaxScale(double scale) |
| void | setMinScale(double scale) |
| void | setReferenceScale(double scale) |
| Esri::ArcGISRuntime::UtilityNetworkListModel * | utilityNetworks() const |
Reimplemented Public Functions
| virtual QString | toJson() const override |
| virtual QJsonObject | unknownJson() const override |
| virtual QJsonObject | unsupportedJson() const override |
Static Public Members
| Esri::ArcGISRuntime::Map * | fromJson(const QString &json, QObject *parent = nullptr) |
Detailed Description
Map contains layers of mapping data and information such as basemaps, popups, renderers, and labels which define the map's capabilities. You can access Map content directly or visualize the map in a MapView.
In an MVC architecture, Map represents the model and MapView represents the view. Map specifies how the geographic data is organized, and MapView renders the data on the screen and allows users to interact with it.
A map can contain a basemap and one or more operational layers:
- A basemap is a map layer that helps orient the user of the map. Typically it sits behind operational layers and shows roads and parcel boundaries to give context to operational layers. Basemaps can also contain layers which are drawn over the top operational layers such as label layers.
- An operational layer provides content that is of unique interest to the app and the task at hand, such as data about earthquakes, traffic, or weather. Its content might change frequently.
You can create a map from an existing web map using its URL or PortalItem. Alternatively, you can get a map directly from a MobileMapPackage::maps collection. Map properties will be hydrated when the map is loaded.
If you create a new map, the spatial reference of the first layer you add, which is typically the first layer in the Basemap, defines the spatial reference of the entire map,
See Maps 2D for more information about maps. A map specifies how the geographic data is organized, and a map view renders the data and allows users to interact with it.
Conceptually, a map's geographic content is derived from its basemap and operational layers.
A basemap provides a background of geographical context for the content you want to display in the map. It is used for locational reference and provides a framework on which you can overlay operational layers. Thus, the basemap serves as a foundation and provides a framework for working with information geographically. Its content is typically geographic features that are static and do not change frequently, such as streets, parcel boundaries, or rivers.
Operational layers provide content of unique interest to the application and the task at hand. Their content might change frequently, such as earthquake reports, traffic, or weather.
If operational layers are added to an existing map before the map is loaded, the map's original list of operational layers is overridden to only contain the added layers. To keep the map's original operational layers and also add new ones, wait until the map is done loading before adding operational layers. You can wait for the doneLoading signal to be emitted before adding the new operational layers.
The map has a spatial reference that specifies how the geographic content from its basemap and operational layers are aligned when combined together.
If you create a new map, the spatial reference of the first layer you add, which is typically the first layer in the Basemap, defines the spatial reference of the entire map.
Once the map has obtained a spatial reference it cannot be changed, even by changing the basemap.
Note: All web maps have a version number that corresponds to the last time the web map was opened and saved. ArcGIS Maps SDK only supports web maps that are version 2.0 and greater. If you try to load a web map that is older than 2.0, it will fail to load with an error indicating that the web map version is not supported. To upgrade the version of the web map, simply open and save the web map in the ArcGIS Online or ArcGIS Enterprise portal map viewer.
Example:
Create a map from a web map stored in ArcGIS Online:
auto* portalItem = new PortalItem(UrlUtility::url("portalItemHousingWithMortgages"), this); Map* map = new Map(portalItem, this);
Relevant samples:
- Set initial map area: Display a map with a predefined initial extent.
- ArcGIS map image layer (URL): Display a layer from an ArcGIS map image layer service.
- ArcGIS tiled layer (tile cache): Load an offline copy of a tiled map service as a basemap.
- ArcGIS tiled layer (URL): Load an ArcGIS tiled layer from a URL.
- Change basemap: Change a map's basemap. A basemap is beneath all layers on a `Map` and is used to provide visual reference for the operational layers.
- Change viewpoint: Set the map view to a new viewpoint.
- Configure basemap style parameters: Apply basemap style parameters customization for a basemap, such as displaying all labels in a specific language or displaying every label in their corresponding local language.
- Control time extent using time slider: This sample demonstrates how to use the time slider from the toolkit to visualize temporal data by applying a specific time extent.
- Create and save map: Create and save a map as an ArcGIS `PortalItem` (i.e. web map).
- Display annotation: Display annotation from a feature service URL.
- Display device location with autopan modes: Display your current position on the map, as well as switch between different types of auto pan modes.
- Display draw status: Get the draw status of your map view or scene view to know when all layers in the map or scene have finished drawing.
- Display layer view draw state: Determine if a layer is currently being viewed.
- Display map: Display a map with an imagery basemap.
- Display overview map: Include an overview or inset map as an additional map view to show the wider context of the primary view.
- Download a preplanned map area: Take a map offline using a preplanned map area.
- Feature layer rendering mode (map): Render features statically or dynamically by setting the feature layer rendering mode.
- Manage operational layers: Add, remove, and reorder operational layers in a map.
- Map loaded: Determine the map's load status which can be: `NotLoaded`, `FailedToLoad`, `Loading`, `Loaded`, `Unknown`.
- Map reference scale: Set the map's reference scale and which feature layers should honor the reference scale.
- Map rotation: Rotate a map.
- Min-Max scale: Restrict zooming between specific scale ranges.
- Open map (URL): Display a web map.
- OpenStreetMap layer: Add OpenStreetMap as a basemap layer.
- Raster function (file): Apply a raster function to a local raster file and display the output with a raster layer.
- Reverse geocode: Use an online service to find the address for a tapped point.
- Set initial map location: Display a basemap centered at an initial location and scale.
- Set map spatial reference: Specify a map's spatial reference.
- Set max extent: Set a max extent on the map.
- Show device location using indoor positioning: Show your device's real-time location while inside a building by using signals from indoor positioning beacons.
- Show magnifier: Tap and hold on a map to show a magnifier.
- Show popup: Show predefined popups from a web map.
- Token authentication: Access a web map that is secured with ArcGIS token-based authentication.
- WMS layer (URL): Display a WMS layer using a WMS service URL.
See also GeoModel::operationalLayers, GeoModel::basemap, JsonSerializable, and Loadable.
Member Function Documentation
[explicit] Map::Map(QObject *parent = nullptr)
Default constructor that creates a map.
- parent - The optional parent QObject.
See also GeoModel::load and SpatialReference.
[explicit] Map::Map(const QUrl &url, QObject *parent = nullptr)
Creates a map with the URL to a web map.
- url - URL of a web map on ArcGIS Online or ArcGIS Enterprise portal.
- parent - The optional parent QObject.
If the specified URL is a portal item URL, the underlying PortalItem is created and can be accessed through item. The URL can be a URL to web map JSON content or the URL of a portal item.
Examples of supported URL formats:
- The web map viewer page, for example: https://www.arcgis.com/apps/mapviewer/index.html?webmap=55ebf90799fa4a3fa57562700a68c405
- The web map viewer page (classic), for example: https://www.arcgis.com/home/webmap/viewer.html?webmap=55ebf90799fa4a3fa57562700a68c405
- The web map item details page, for example: https://www.arcgis.com/home/item.html?id=55ebf90799fa4a3fa57562700a68c405
- The REST sharing API data page, for example: https://www.arcgis.com/sharing/rest/content/items/55ebf90799fa4a3fa57562700a68c405/data
- The REST sharing API page (with or without the query parameter f=json), for example: https://www.arcgis.com/sharing/rest/content/items/55ebf90799fa4a3fa57562700a68c405?f=json
{PortalItem::PortalItem(const QUrl&, QObject*)}, {Esri::ArcGISRuntime::GeoModel::item} {GeoModel::item}
See also PortalItem and Esri::ArcGISRuntime::PortalItem::PortalItem(const QUrl&, QObject*).
[explicit] Map::Map(Esri::ArcGISRuntime::Basemap *basemap, QObject *parent = nullptr)
Creates a map with a Basemap.
- basemap - A basemap object.
- parent - The optional parent QObject.
[explicit] Map::Map(Esri::ArcGISRuntime::Item *item, QObject *parent = nullptr)
Creates a map with a portal item of type PortalItemType::WebMap.
- item - A web map PortalItem.
- parent - The optional parent QObject.
The PortalItem automatically loads when the Map loads. If the loaded Item is not a portal item of type PortalItemType::WebMap, the map fails to load.
[explicit] Map::Map(const Esri::ArcGISRuntime::SpatialReference &spatialReference , QObject *parent = nullptr)
Creates a map with the specified spatial reference.
- spatialReference - A spatial reference object.
- parent - The optional parent QObject.
[explicit, since Esri::ArcGISRuntime 100.10] Map::Map(Esri::ArcGISRuntime::BasemapStyle basemapStyle , QObject *parent = nullptr)
Constructor that creates a map with a basemap style.
- basemapStyle - The basemap style.
- parent - The optional parent QObject.
This function was introduced in Esri::ArcGISRuntime 100.10.
See also BasemapStyle.
[override virtual] Map::~Map()
Destructor.
[since Esri::ArcGISRuntime 100.7] QColor Map::backgroundColor () const
The background color of the map.
This value specifies the color to be displayed behind the map. This color will be displayed in transparent areas of the map and areas where there is no basemap or operational data.
When a map is set on a MapView, changes to backgroundColor will take immediate effect.
The default value is an invalid QColor. In this case, the MapView::backgroundGrid specifies the background color.
This function was introduced in Esri::ArcGISRuntime 100.7.
See also setBackgroundColor().
[static] Esri::ArcGISRuntime::Map *Map::fromJson (const QString &json, QObject *parent = nullptr)
Creates this Map from its JSON representation.
Returns a Map created using the data in the json parameter and an optional parent.
See also JsonSerializable.
[since Esri::ArcGISRuntime 200.4] Esri::ArcGISRuntime::IndoorPositioningDefinition *Map::indoorPositioningDefinition () const
Returns the information needed to create an IndoorsLocationDataSource.
For a map to be IPS-enabled, one of the following must be true:
- A reference to an indoor positioning data service is defined in the web map properties.
- It contains an "ips_positioning" feature table.
If this map is IPS-aware it will return an IndoorPositioningDefinition that contains the information needed to create an IndoorsLocationDataSource. If this map is not IPS-aware then this property is nullptr.
This function was introduced in Esri::ArcGISRuntime 200.4.
[since Esri::ArcGISRuntime 100.14] Esri::ArcGISRuntime::Envelope Map::maxExtent () const
Returns the extent that constrains the display to a specific region.
The max extent is initialized when the map loads or when you set it explicitly. This value limits panning in the MapView to a specific area of the map.
If the max extent is empty when the map loads, or you set it to empty, max extent is calculated from the union of the full extent of all basemap layers. If there is no basemap, it is set as the full extent of the map's first operational layer.
If the GeoModel::initialViewpoint is not set, the max extent is used as the initial viewpoint. If the GeoModel::initialViewpoint is set, but is outside of the max extent, the max extent takes precedence and the display will initially show the max extent.
This function was introduced in Esri::ArcGISRuntime 100.14.
See also setMaxExtent().
double Map::maxScale () const
Returns the maximum scale for the map.
A value of zero indicates that there is no maximum scale and the user can zoom in indefinitely. The default value is 0.0.
See also setMaxScale().
double Map::minScale () const
Returns the minimum scale of the map.
A value of zero indicates that there is no minimum scale and the user can zoom out indefinitely. The default value is 0.0.
See also setMinScale().
[since Esri::ArcGISRuntime 200.4] QFuture<QList<Esri::ArcGISRuntime::UtilityNamedTraceConfiguration *>> Map::namedTraceConfigurationsFromUtilityNetworkAsync (Esri::ArcGISRuntime::UtilityNetwork *utilityNetwork , QObject *parent = nullptr)
Returns a list of all the UtilityNamedTraceConfiguration objects referenced by UtilityNetwork's map.
- utilityNetwork - The UtilityNetwork.
- parent - The optional parent QObject.
An empty collection is returned if the UtilityNetwork does not belong to the map or if the map does not contain any UtilityNamedTraceConfiguration objects.
This method returns a QFuture for the asynchronous operation. Use future.then() to continue processing when the operation completes. Use future.onFailed() to handle exceptions of type ErrorException.
See Working with QFuture for further details.
This function was introduced in Esri::ArcGISRuntime 200.4.
See also UtilityNamedTraceConfiguration.
[since Esri::ArcGISRuntime 100.5] Esri::ArcGISRuntime::OfflineSettings *Map::offlineSettings () const
Returns the offline settings configured by the author of an online web map (if appropriate).
Offline settings optimize the data that is delivered during download and synchronization. For example, they can control feature and attachment delivery or define whether the map's basemap is created using a tile package already on the device.
This property is nullptr unless the map represents an online web map and the author has configured the offline settings.
This function was introduced in Esri::ArcGISRuntime 100.5.
[since Esri::ArcGISRuntime 100.5] double Map::referenceScale () const
Returns the reference scale of the map.
The reference scale is the scale at which feature symbols and text will appear at their authored size. If the viewing scale is different from the reference scale, then the symbology and text graphics will be scaled to keep the same size on the map. Only those layers for which scaleSymbols is true will be scaled. For example, FeatureLayer::setScaleSymbols.
The default value is 0.0. Zero reference scale means that no reference scale is set and all symbology and text graphics will be drawn at their default screen size.
Updates to the reference scale will redraw other layers that use the reference scale, and may redraw other layers that depend on them. For example, dynamic labels may need to re-position to avoid overlaps.
This function was introduced in Esri::ArcGISRuntime 100.5.
See also setReferenceScale().
[since Esri::ArcGISRuntime 200.2] QFuture<void> Map::saveAsAsync (Esri::ArcGISRuntime::Portal *portal, const QString &title, const QStringList &tags, bool forceSaveToSupportedVersion , const Esri::ArcGISRuntime::PortalFolder &folder = PortalFolder(), const QString &description = QString(), const QByteArray &thumbnailBytes = QByteArray())
Starts an asynchronous task to save the map to a portal as a portalItem.
- portal - The portal to save the PortalItem to.
- title - A title for the map.
- tags - A list of tags to associate with the map.
- forceSaveToSupportedVersion - Whether the map should be saved to the supported web map version that the API supports (see system requirements). This may cause data loss as unknown data is not saved. If
true, unknown data will be removed and the map will be saved. Iffalse, the asynchronous operation will fail if the map contains unknown data that will not be saved. This flag can be used to provide a warning to users that some map data may be lost when the map is saved. - folder - An optional PortalFolder belonging to the current user in which to save the map. If not specified the map will be saved in the user's root folder.
- description - An optional description for the map.
- thumbnailBytes - Optional bytes for the thumbnail image.
Updates the map content data on the portal, and updates the portal item properties stored on the portal to match those stored within the map's PortalItem object.
If the portal is not loaded, it will be loaded automatically. If the portal requires a credential that has not been supplied, it should be loaded before calling this function.
The map must be loaded to call this function. Calling this function will not force the map to start loading.
Canceling the QFuture will not stop this operation from completing, though the QFuture will report that it is canceled and the completion handler will not be called.
See Working with QFuture for further details.
This function was introduced in Esri::ArcGISRuntime 200.2.
[since Esri::ArcGISRuntime 200.2] QFuture<void> Map::saveAsync (bool forceSaveToSupportedVersion )
Saves this map back to the item it originated from.
- forceSaveToSupportedVersion - A Boolean value indicating whether the map should be saved to the supported web map version that the API supports (see system requirements). This may cause data loss as unknown data is not saved. If
true, unknown data will be removed and the map will be saved. Iffalse, the asynchronous operation will fail if the map contains unknown data that will not be saved. This flag can be used to provide a warning to users that some map data may be lost when the map is saved.
The map must have a valid item property and if the operation was successful the item will be updated with the map. A map has a valid item property if it was created using either Map(Esri::ArcGISRuntime::Item*, QObject*) or Map(const QUrl&, QObject*), or has been previously saved as a new item.
Canceling the QFuture will not stop this operation from completing, though the QFuture will report that it is canceled and the completion handler will not be called.
See Working with QFuture for further details.
This function was introduced in Esri::ArcGISRuntime 200.2.
[since Esri::ArcGISRuntime 100.7] void Map::setBackgroundColor (const QColor &backgroundColor )
Sets the background color to backgroundColor.
To clear the background color, pass a default constructed (invalid) QColor.
This function was introduced in Esri::ArcGISRuntime 100.7.
See also backgroundColor().
[since Esri::ArcGISRuntime 100.14] void Map::setMaxExtent (const Esri::ArcGISRuntime::Envelope &maxExtent )
Sets the maxExtent to maxExtent.
This function was introduced in Esri::ArcGISRuntime 100.14.
See also maxExtent.
void Map::setMaxScale (double scale)
Sets the maxScale to scale.
See also maxScale.
void Map::setMinScale (double scale)
Sets the minScale to scale.
See also minScale.
[since Esri::ArcGISRuntime 100.5] void Map::setReferenceScale (double scale)
Sets the referenceScale to scale.
This function was introduced in Esri::ArcGISRuntime 100.5.
See also referenceScale.
[override virtual] QString Map::toJson () const
Reimplements: JsonSerializable::toJson() const.
Returns this Map instance represented as a JSON String.
See also JsonSerializable.
[override virtual] QJsonObject Map::unknownJson () const
Reimplements: JsonSerializable::unknownJson() const.
Returns the unknown data from the source JSON.
Unknown JSON is a QJsonObject of values not defined in the ArcGIS specification used to create this object but found in the source JSON. If the object is written back to JSON, any unknown JSON data is not persisted. The ArcGIS specification may be for a web map, web scene, REST API, and so on.
[override virtual] QJsonObject Map::unsupportedJson () const
Reimplements: JsonSerializable::unsupportedJson() const.
Returns the unsupported data from the source JSON.
Unsupported JSON is a QJsonObject of values defined in the ArcGIS specification used to create this object but not currently used in this API. If the object is written back to JSON, any unsupported JSON data is persisted. The ArcGIS specification may be from a web map, web scene, REST API, and so on.
[since Esri::ArcGISRuntime 100.10] Esri::ArcGISRuntime::UtilityNetworkListModel *Map::utilityNetworks () const
Returns the utility networks in the map.
This collection of UtilityNetwork is specific to this map.
A Map created with a web map portal item that has utility networks will pre-populate this collection.
When this Map is used to create a UtilityNetwork, the UtilityNetwork that was created will be added to this collection.
Only a UtilityNetwork that is not loaded may be added to this collection. An attempt to add a UtilityNetwork that is loaded or loading will throw an error.
An attempt to add to this collection, a UtilityNetwork that is already part of a Map::utilityNetworks(), will throw an error.
An attempt to add a nullptr UtilityNetwork to this collection will throw an error.
This function was introduced in Esri::ArcGISRuntime 100.10.