;

Map QML Type

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

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

GeoModel

Properties

Signals

Methods

  • bool cancelTask(string taskId)
  • string namedTraceConfigurationsFromUtilityNetwork(UtilityNetwork utilityNetwork)
  • 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 geographic 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, spatialReference, and initBasemapStyle 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, item, and initBasemapStyle 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

    initBasemapStyle: Enums.BasemapStyleArcGISImagery

    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

backgroundColor : color

The background color of the map.

This value determines the color to be displayed behind the map. This color will be displayed in transparent areas of the map as well as areas where there is no basemap or operational data.

When a map is set on a MapView, changes to backgroundColor will immediately take effect.

The default value is null. In this case, the MapView::backgroundGrid is used to determine the background color to display. To clear the background color, pass an empty string ("")to this property.

This property was introduced in Esri.ArcGISRuntime 100.7.


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 several possible types that refer to a PortalItem:

  • the URL of a webmap opened in the portal's map viewer web application (classic or new). Examples:
    • https://www.arcgis.com/home/webmap/viewer.html?webmap=8bf7167d20924cbf8e25e7b11c7c502c or
    • https://www.arcgis.com/apps/mapviewer/index.html?webmap=8bf7167d20924cbf8e25e7b11c7c502c
  • the URL of the webmap item details web page. Example: https://www.arcgis.com/home/item.html?id=c6a2c53ead68432586cc9ac9ec366055
  • the REST Sharing API URL of the webmap item (with or without the query parameter f=json). Example: https://www.arcgis.com/sharing/rest/content/items/c6a2c53ead68432586cc9ac9ec366055?f=json
  • The REST Sharing API URL of the webmap item data. Example: https://www.arcgis.com/sharing/rest/content/items/c6a2c53ead68432586cc9ac9ec366055/data

See also PortalItem, PortalItem::portal, and GeoModel::item.


json : jsobject

JSON that can be used to instantiate the Map.


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.


namedTraceConfigurationsFromUtilityNetworkStatus : Enums.TaskStatus

The current status of the asynchronous namedTraceConfigurationsFromUtilityNetwork(UtilityNetwork) operation (read-only).

This property was introduced in Esri.ArcGISRuntime 100.11.


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 property was introduced in Esri.ArcGISRuntime 100.5.


queryNamedTraceConfigurationsResults : list<UtilityNamedTraceConfiguration>

The result returned when the asynchronous namedTraceConfigurationsFromUtilityNetwork(UtilityNetwork) operation completes (read-only).

This property was introduced in Esri.ArcGISRuntime 100.11.


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 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.


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.


utilityNetworks : UtilityNetworkListModel

The utility networks in the Map (read-only).

This collection of UtilityNetwork is specific to this map.

A Map created with a webmap portal item with 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 utilityNetworks, will throw an error.

An attempt to add a null UtilityNetwork to this collection will throw an error.

This property was introduced in Esri.ArcGISRuntime 100.10.


Signal Documentation

backgroundColorChanged()

Emitted when the backgroundColor property of this Map changes.

Note: The corresponding handler is onBackgroundColorChanged.

This signal was introduced in Esri.ArcGISRuntime 100.7.


maxScaleChanged()

Emitted when the maxScale property of this Map changes.

This property may be populated after the map loads.

Note: The corresponding handler is onMaxScaleChanged.


minScaleChanged()

Emitted when the minScale property of this Map changes.

This property may be populated after the map loads.

Note: The corresponding handler is onMinScaleChanged.


namedTraceConfigurationsFromUtilityNetworkStatusChanged()

Emitted when the namedTraceConfigurationsFromUtilityNetworkStatus property changes.

Note: The corresponding handler is onNamedTraceConfigurationsFromUtilityNetworkStatusChanged.

This signal was introduced in Esri.ArcGISRuntime 100.11.


offlineSettingsChanged()

Emitted when the offlineSettings property of this Map changes.

This property may be populated after the map loads.

Note: The corresponding handler is onOfflineSettingsChanged.

This signal was introduced in Esri.ArcGISRuntime 100.5.


referenceScaleChanged()

Emitted when the referenceScale property of this Map changes.

Note: The corresponding handler is onReferenceScaleChanged.

This signal was introduced in Esri.ArcGISRuntime 100.5.


saveStatusChanged()

Emitted when the saveStatus property of this Map changes.

Note: The corresponding handler is onSaveStatusChanged.


tablesChanged()

Emitted when the tables property of this Map changes.

This property may be populated after the map loads.

Note: The corresponding handler is onTablesChanged.

This signal was introduced in Esri.ArcGISRuntime 100.1.


void utilityNetworksChanged()

Emitted when the utilityNetworks property changes.

Note: The corresponding handler is onUtilityNetworksChanged.

This signal was introduced in Esri.ArcGISRuntime 100.10.


Method Documentation

bool cancelTask(string taskId)

Cancel the task with the ID taskId.

Returns false if the task cannot be cancelled or there is no task with the specified id taskId.

See also Cancelable.


string namedTraceConfigurationsFromUtilityNetwork(UtilityNetwork utilityNetwork)

Returns a list of all the UtilityNamedTraceConfiguration objects referenced by UtilityNetwork's Map.

An empty list will be returned if the UtilityNetwork does not belong to the Map or if the Map does not contain any UtilityNamedTraceConfiguration objects. If the UtilityNetwork is not loaded, an error will be returned.

Returns a string representing the task ID of the asynchronous task.

This method was introduced in Esri.ArcGISRuntime 100.11.

See also UtilityNamedTraceConfiguration.


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.


Your browser is no longer supported. Please upgrade your browser for the best experience. See our browser deprecation post for more details.