Map QML Type

MapView to display layers of geographic data in 2D."> Map QML Type | ArcGISQtQml
  • Esri.ArcGISRuntime
  • Map
  • A map is a container for layers. Use a map together with a MapView to display layers of geographic data in 2D. More...

    Import Statement: import Esri.ArcGISRuntime
    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

    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.

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

    See Maps 2D for more information about maps.

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

    See also JsonSerializable and Loadable.

    Property Documentation

    [since Esri.ArcGISRuntime 100.7] backgroundColor : color

    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 take immediate effect.

    The default value is null. In this case, the MapView::backgroundGrid specifies the background color.

    This property was introduced in Esri.ArcGISRuntime 100.7.


    json : jsobject

    JSON that can be used to instantiate the Map.


    [since Esri.ArcGISRuntime 100.14] maxExtent : Envelope

    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 null when the map loads, or you set it to null, the 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 property was introduced in Esri.ArcGISRuntime 100.14.


    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.


    [read-only, since Esri.ArcGISRuntime 100.11] namedTraceConfigurationsFromUtilityNetworkStatus : Enums.TaskStatus

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

    This property was introduced in Esri.ArcGISRuntime 100.11.


    [read-only, since Esri.ArcGISRuntime 100.5] offlineSettings : OfflineSettings

    Offline settings configured by the author of an online web map (if appropriate) (read-only).

    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 null unless the map represents an online web map and the author has configured the offline settings.

    This property was introduced in Esri.ArcGISRuntime 100.5.


    [read-only, since Esri.ArcGISRuntime 100.11] queryNamedTraceConfigurationsResults : list<UtilityNamedTraceConfiguration>

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

    This property was introduced in Esri.ArcGISRuntime 100.11.


    [since Esri.ArcGISRuntime 100.5] referenceScale : double

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

    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.

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

    This property was introduced in Esri.ArcGISRuntime 100.5.


    [read-only] 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.


    [read-only] unknownJson : jsobject

    Returns the unknown JSON from the source JSON.

    Unknown JSON is a jsobject 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.

    See also JsonSerializable.


    [read-only] unsupportedJson : jsobject

    Returns the unsupported data from the source JSON.

    Unsupported JSON is a jsobject 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.

    See also JsonSerializable.


    [read-only, since Esri.ArcGISRuntime 100.10] utilityNetworks : UtilityNetworkListModel

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

    This collection of UtilityNetwork is specific to this map.

    A Map created with a web map 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

    [since Esri.ArcGISRuntime 100.7] 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.


    [since Esri.ArcGISRuntime 100.14] maxExtentChanged()

    Emitted when the maxExtent property changes.

    Note: The corresponding handler is onMaxExtentChanged.

    This signal was introduced in Esri.ArcGISRuntime 100.14.


    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.


    [since Esri.ArcGISRuntime 100.11] namedTraceConfigurationsFromUtilityNetworkStatusChanged()

    Emitted when the namedTraceConfigurationsFromUtilityNetworkStatus property changes.

    Note: The corresponding handler is onNamedTraceConfigurationsFromUtilityNetworkStatusChanged.

    This signal was introduced in Esri.ArcGISRuntime 100.11.


    [since Esri.ArcGISRuntime 100.5] 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.


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


    [since Esri.ArcGISRuntime 100.1] 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.


    Method Documentation

    bool cancelTask(string taskId)

    Cancel the task with the ID taskId.

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

    See also Cancelable.


    [since Esri.ArcGISRuntime 100.11] 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.