Layer types

A map view is basically an empty canvas onto which one or more map layers are drawn. A wide variety of predefined layers are provided by the API.

Most layers display content from GIS server web services, such as ArcGIS Server services. These layers fall into two broad categories, dynamic layers and tiled layers.

Dynamic layers rely on web services that generate map images on the fly when requested by a client. Tiled layers rely on web services that provide map images previously generated based on a tiling scheme. Tiled layers provide better performance than dynamic layers because map images do not need to generate when requested by the client. Instead, map images are readily available and only need to be transferred to the client.

A graphics layer is a special type of dynamic layer. It does not rely on any web service for its content. Its content contains graphics that are added to the layer.

Add layers to the map

To add a layer to a map view, do the following:

  1. Instantiate the layer. If the layer relies on a web service, provide the service's URL.
  2. Add the layer to the map view using the addLayer method.
    QString layerUrl = "";
    m_tiledLayer = new EsriRuntimeQt::ArcGISTiledMapServiceLayer(layerUrl, this);

By default, the layer is added on top of any existing layers. Layers are drawn in a bottom-up order. This means that a layer can potentially obscure the contents of other layers beneath it. Tiled map service layers are intended to be basemaps. If you plan to use them in your map, add them as the first layer before any other layer type is added.


Once the layer successfully loads, its content begins appearing on the map.

Map's spatial reference

The first layer you add to a map is the basemap layer. It dictates the map's initial extent and also the map's overall spatial reference. Any tiled layers you subsequently add to a map must also be in this spatial reference; otherwise, their content will not display. However, dynamic layers can be in any spatial reference, because they automatically reproject their content when necessary into the map's spatial reference. Tiled basemaps cannot be reprojected this way.


The map remains blank if the basemap layer fails to load. This is because the map does not get assigned a spatial reference and cannot combine map content from other layers into a common frame. You must handle this scenario appropriately. If the basemap layer is central to the map, you can try to reload the layer and inform the user if it fails again. However, if the basemap layer is not critical, you can remove it from the map, in which case, the next layer becomes the basemap layer.