Skip To Content ArcGIS for Developers Sign In Dashboard

Map QML Type

A map which can be displayed on the screen using a map view. More...

Import Statement: import Esri.ArcGISRuntime 100.6
Since: Esri.ArcGISRuntime 100.0
Inherits:

Object

Properties

Signals

Methods

  • void cancelLoad()
  • void load()
  • void retryLoad()
  • void save(bool forceSaveToSupportedVersion)
  • void saveAs(Portal portal, string title, list<string> tags, bool forceSaveToSupportedVersion, PortalFolder folder, string description, url thumbnailImage)

Detailed Description

A map represents the model in an MVC architecture and a map view represents the view. A map specifies how the geographic data is organized, and a map view renders the data and allows users to interact with it.

A map derives its geographic content from its basemap and operational layers. A basemap provides a geographical context for the content you want to display on the map. It is a background locational reference where you can overlay your operational layers. The basemap content is typically geographic features that do not change frequently, such as streets, parcel boundaries, or rivers. Operational layers provide application content for the task at hand. Their content might change frequently with updates from earthquake, traffic, or weather reports.

The map has a spatial reference that specifies how the geographic content from its basemap and operational layers are aligned when combined together. The first layer that is added to the map will set the spatial reference.

Once the map's spatial reference is set, it cannot be changed, even by changing the basemap.

You can initialize the map in several different ways: creating from an ArcGISItem (a web map); a URL to a PortalItem, creating from a basemap (either your own, or an Esri-provided basemap); or by defining the spatial reference. Each method of initialization is mutually exclusive. For example, you should not set both the item and basemap properties. Doing so will print a warning message at the console.

In the event that any combination of item, initUrl, basemap, and spatialReference properties are set when the map initializes, the software chooses how to initialize the map depending on which properties are set. The precedence order for these properties is as follows.

The spatialReference, initUrl and item properties can only be set at map initialization time. For example, if a map is created using a basemap, and later the item property is set in a JavaScript function, nothing will happen because the map was already initialized with the basemap.

This QML type supports the following default properties. A default property may be declared inside another declared object without being assigned explicitly to a property.

TypeDefault Property
Basemapbasemap
LayeroperationalLayers (appends to model)
Bookmarkbookmarks (appends to model)
ViewpointinitialViewpoint
ArcGISItemitem
SpatialReferencespatialReference
FeatureTabletables (appends to model) since Esri.ArcGISRuntime 100.1
LoadSettingsloadSettings (since Esri.ArcGISRuntime 100.2)

The code for creating a map that contains the Esri World Imagery as the basemap and a FeatureLayer can be as simple as the following:

Map {
    id: map

    BasemapImagery { }

    FeatureLayer {
    ...
    }
}

If operational layers are added to an existing map by nesting them inside the map's declaration, then 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's loadStatus property is Enums.LoadStatusLoaded before adding operational layers. You can declare new operational layers outside the map's declaration, and use a signal handler for the loadStatusChanged signal to add the new operational layers.

Example:

Create a map from a web map stored in ArcGIS Online:

// construct an item
var itemUrl = "https://arcgis.com/sharing/rest/content/items/2d6fa24b357d427f9c737774e7b0f977";
var newItem = ArcGISRuntimeEnvironment.createObject("PortalItem", { url: itemUrl });

// construct a map from an item
var newMap = ArcGISRuntimeEnvironment.createObject("Map", { item: newItem });

// add the map to the map view
mapView.map = newMap;

Note: All web maps have a version number that corresponds to the last time the web map was opened and saved. ArcGIS Runtime 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.

See also JsonSerializable and Loadable.

Property Documentation

autoFetchLegendInfos : bool

Whether legend infos are automatically fetched by the map's operational layers.

Set to true (default is false) to have legend infos fetched automatically when the LegendInfoListModel is instantiated.


[default] basemap : Basemap

The basemap of the map.


[default] bookmarks : BookmarkListModel

Returns the list model for bookmarks in the Map (read-only).


error : Error

Returns the error object (read-only).

See also Loadable and Error.


initUrl : url

The URL used to initialize the map.

This property can only be set one time.

Note: Assigning the item property will not automatically make the initUrl property valid.

Note: Assigning this property will not create an item for use with the save methods that require a item.

The initUrl can be one of three possible types that refer to a PortalItem

  • The item details page : http://www.myPortal.com/home/item.html?id=12345678901234567890123456789012
  • The map view page : http://www.myPortal.com/home/webmap/viewer.html?webmap=12345678901234567890123456789012
  • The sharing data url : http://www.myPortal.com/sharing/rest/content/items/12345678901234567890123456789012/data

[default] initialViewpoint : Viewpoint

The initial Viewpoint.


[default] item : ArcGISItem

Returns the item that was used to instantiate this map.

This can only be assigned one time.

If the item is provided to the map, some of the save methods are available.

See also save and saveAs.


json : jsobject

JSON that can be used to instantiate the Map.


legendInfos : LegendInfoListModel

Returns the list model containing legend infos for the map's operational layers (read-only).


loadError : Error

Returns the load error (read-only).

Note: load errors are also reported on the error property and emit the errorChanged signal.

See also Loadable.


[default] loadSettings : LoadSettings

The load settings properties that can be used to make changes to how feature layers, which are loaded by this map, are rendered.

This QML property was introduced in Esri.ArcGISRuntime 100.2.


loadStatus : Enums.LoadStatus

Returns the load status (read-only).

See also Loadable and Enums.LoadStatus.


maxScale : double

The maximum scale of the map.

Setting this to zero means that there is no maximum scale, and the user can zoom in indefinitely.

The default value is 0.0.


minScale : double

The minimum scale of the map.

Setting this to zero means that there is no minimum scale, and the user can zoom out indefinitely.

The default value is 0.0.


offlineSettings : OfflineSettings

The offline use settings, configured by the author of an online web map (if appropriate).

These settings will only be populated when this map represents an online web map and the author has chosen to set them. The properties can be used to inform how a map should be taken offline.

If no online settings were provided, or if this map does not represent an online web map, this property will be null.

This QML property was introduced in Esri.ArcGISRuntime 100.5.


[default] operationalLayers : LayerListModel

Returns the list model for operational layers in the Map (read-only).


referenceScale : double

The reference scale of the map.

The reference scale is the scale at which feature symbols and text will appear at their default 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 which scaleSymbols is true will be scaled.

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.

Negative or NaN values have no meaning, and will be rejected.

This QML property was introduced in Esri.ArcGISRuntime 100.5.


saveStatus : Enums.TaskStatus

The save status of one of the asynchronous save operations.

Check this status when the saveStatusChanged signal emits.

See also Enums.TaskStatus.


[default] spatialReference : SpatialReference

The spatial reference.

This property can only be set one time.


[default] tables : FeatureTableListModel

Returns the list model for tables in the Map (read-only).

This QML property was introduced in Esri.ArcGISRuntime 100.1.


transportationNetworks : list<TransportationNetworkDataset>

Returns a list of TransportationNetworkDataset objects representing the transportation networks in the map (read-only).


unknownJson : jsobject

Returns the unknown JSON from the source JSON.

See also JsonSerializable.


unsupportedJson : jsobject

Returns the unsupported data from the source JSON.

See also JsonSerializable.


version : string

Returns the version of this map (read-only).


Signal Documentation

autoFetchLegendInfosChanged()

Emitted when the autoFetchLegendInfos property changes.


basemapChanged()

Emitted when the basemap property of this Map changes.


bookmarksChanged()

Emitted when the bookmarks property of this Map changes.

This property may be populated after the map loads.


initUrlChanged()

Emitted when the initUrl property of this Map changes.


initialViewpointChanged()

Emitted when the initialViewpoint property of this Map changes.


itemChanged()

Emitted when the item property of this Map changes.


legendInfosChanged()

Emitted when the legendInfos property changes.


loadErrorChanged()

Emitted when the loadError property of this Map changes.

Note: load errors are also reported on the error property and emit the errorChanged signal.

See also Loadable and Object.


loadSettingsChanged()

Emitted when the loadSettings property of this Map changes.

This QML signal was introduced in Esri.ArcGISRuntime 100.2.


loadStatusChanged()

Emitted when the loadStatus property of this Map changes.

See also Loadable.


maxScaleChanged()

Emitted when the maxScale property of this Map changes.

This property may be populated after the map loads.


minScaleChanged()

Emitted when the minScale property of this Map changes.

This property may be populated after the map loads.


offlineSettingsChanged()

Emitted when the offlineSettings property of this Map changes.

This property may be populated after the map loads.

This QML signal was introduced in Esri.ArcGISRuntime 100.5.


operationalLayersChanged()

Emitted when the operationalLayers property of this Map changes.

This property may be populated after the map loads.


saveStatusChanged()

Emitted when the saveStatus property of this Map changes.


spatialReferenceChanged()

Emitted when the spatialReference property of this Map changes.


tablesChanged()

Emitted when the tables property of this Map changes.

This property may be populated after the map loads.

This QML signal was introduced in Esri.ArcGISRuntime 100.1.


transportationNetworksChanged()

Emitted when the transportationNetworks property of this Map changes.


versionChanged()

Emitted when the version property of this Map changes.

This property may be populated after the map loads.


Method Documentation

void cancelLoad()

See also Loadable.


void load()

See also Loadable.


void retryLoad()

See also Loadable.


void save(bool forceSaveToSupportedVersion)

Saves any changes that have been made to the map.

The map must have been created by supplying the item property, or saved using saveAs to associate it with a PortalItem object.

  • 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. If false, 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.

Updates the map content data on the portal and also 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 which has not been supplied, it should be loaded before calling this method.

The Map must be loaded to call this method. Calling this method will not force the map to start loading. If the map is not already associated with a PortalItem, calling save will produce an error.


void saveAs(Portal portal, string title, list<string> tags, bool forceSaveToSupportedVersion, PortalFolder folder, string description, url thumbnailImage)

Saves the map to a portal as a portalItem.

  • portal - The Portal to save the item to.
  • title - A title for the map.
  • tags - A string 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. If false, 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.
  • thumbnailImage - An optional thumbnail image. This can only be a local image resource or a local path to an image. Any online resources will not be loaded.

Updates the map content data on the portal and also 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 which has not been supplied, it should be loaded before calling this method.

The Map must be loaded to call this method. Calling this method will not force the map to start loading.



Feedback on this topic?