Skip To Content ArcGIS for Developers Sign In Dashboard

ArcGIS Runtime SDK for Qt

Control annotation sublayer visibility

Sample Viewer View Sample on GitHub

Use annotation sublayers to gain finer control of annotation layer subtypes.

Use case

Annotation, which differs from labels by having a fixed place and size, is typically only relevant at particular scales. Annotation sublayers allow for finer control of annotation by allowing properties (like visibility in the map and legend) to be set and others to be read (like name) on subtypes of an annotation layer.

An annotation dataset which marks valves as "Opened" or "Closed", might be set to display the "Closed" valves over a broader range of scales than the "Opened" valves, if the "Closed" data is considered more relevant by the map's author. Regardless, the user can be given a manual option to set visibility of annotation sublayers on and off, if required.

How to use the sample

Start the sample and take note of the visibility of the annotation. Zoom in and out to see the annotation turn on and off based on scale ranges set on the data.

Use the checkboxes to manually set "Open" and "Closed" annotation sublayers visibility to on or off.

How it works

  1. Load a MobileMapPackage that contains AnnotationSublayer.
  2. Get the sublayers from the map package's layers by calling sublayer::subLayerContents()[i].
  3. You can toggle the visibility of each sublayer manually using sublayer::setVisible().
  4. To determine if a sublayer is visible at the current scale of the MapView, use sublayer::isVisibleAtScale(), by passing in the map's current scale.

Relevant API

  • AnnotationLayer
  • AnnotationSublayer
  • LayerContent

Offline Data

Read more about how to set up the sample's offline data here.

Link Local Location
Gas Device Anno Mobile Map Package <userhome>/ArcGIS/Runtime/Data/mmpk/GasDeviceAnno.mmpk

About the data

The scale ranges were set by the map's author using ArcGIS Pro:

  • The "Open" annotation sublayer has its maximum scale set to 1:500 and its minimum scale set to 1:2000.
  • The "Closed" annotation sublayer has no minimum or maximum scales set, so will be drawn at all scales.


annotation, scale, text, utilities, visualization

Sample Code

import QtQuick 2.6
import QtQuick.Layouts 1.12
import QtQuick.Controls 2.2
import Esri.Samples 1.0

Item {
    // add a mapView component
    MapView {
        id: view
        anchors.fill: parent

        Rectangle {
            id: checkBoxBackground
            anchors {
                left: parent.left
                margins: 2
            width: childrenRect.width
            height: childrenRect.height
            color: "white"
            opacity: .75
            radius: 5

            ColumnLayout {
                spacing: 0
                Row {
                    CheckBox {
                        id: openBox
                        checked: true
                        onCheckStateChanged: controlAnnotationSublayerVisibilityModel.openLayerVisible();

                    Text {
                        id: openBoxText
                        text: controlAnnotationSublayerVisibilityModel.openLayerText
                        anchors.verticalCenter: openBox.verticalCenter
                        color: scale.color

                Row {
                    CheckBox {
                        id: closedBox
                        checked: true
                        onCheckStateChanged: controlAnnotationSublayerVisibilityModel.closedLayerVisible();

                    Text {
                        id: closedBoxText
                        text: controlAnnotationSublayerVisibilityModel.closedLayerText
                        anchors.verticalCenter: closedBox.verticalCenter

        Rectangle {
            id: currentScale
            anchors {
                bottom: view.attributionTop
                horizontalCenter: parent.horizontalCenter
            width: childrenRect.width
            height: childrenRect.height

            Text {
                id: scale
                text: "Current map scale: 1:%1".arg(Math.round(controlAnnotationSublayerVisibilityModel.mapScale))
                color: controlAnnotationSublayerVisibilityModel.visibleAtCurrentExtent ? "black" : "grey"
                padding: 2

    // Declare the C++ instance which creates the scene etc. and supply the view
    ControlAnnotationSublayerVisibilitySample {
        id: controlAnnotationSublayerVisibilityModel
        mapView: view
#ifdef PCH_BUILD
#include "pch.hpp"
#endif // PCH_BUILD

#include "ControlAnnotationSublayerVisibility.h"

#include "Map.h"
#include "MapQuickView.h"
#include "MobileMapPackage.h"
#include "AnnotationLayer.h"
#include "AnnotationSublayer.h"

#include <QDir>
#include <QtCore/qglobal.h>

#ifdef Q_OS_IOS
#include <QStandardPaths>
#endif // Q_OS_IOS

using namespace Esri::ArcGISRuntime;

// helper method to get cross platform data path
QString defaultDataPath()
  QString dataPath;

  dataPath = "/sdcard";
#elif defined Q_OS_IOS
  dataPath = QStandardPaths::writableLocation(QStandardPaths::DocumentsLocation);
  dataPath = QDir::homePath();

  return dataPath;
} // namespace

// sample MMPK location
const QString sampleFileAnno {"/ArcGIS/Runtime/Data/mmpk/GasDeviceAnno.mmpk"};

ControlAnnotationSublayerVisibility::ControlAnnotationSublayerVisibility(QObject* parent /* = nullptr */):
  const QString dataPath = defaultDataPath() + sampleFileAnno;

  // connect to the Mobile Map Package instance to know when errors occur
  connect(MobileMapPackage::instance(), &MobileMapPackage::errorOccurred,
          [](Error error)
    if (error.isEmpty())

    qDebug() << QString("Error: %1 %2").arg(error.message(), error.additionalMessage());

  // Load the MMPK

ControlAnnotationSublayerVisibility::~ControlAnnotationSublayerVisibility() = default;

void ControlAnnotationSublayerVisibility::init()
  // Register the map view for QML
  qmlRegisterType<MapQuickView>("Esri.Samples", 1, 0, "MapView");
  qmlRegisterType<ControlAnnotationSublayerVisibility>("Esri.Samples", 1, 0, "ControlAnnotationSublayerVisibilitySample");

MapQuickView* ControlAnnotationSublayerVisibility::mapView() const
  return m_mapView;

// Set the view (created in QML)
void ControlAnnotationSublayerVisibility::setMapView(MapQuickView* mapView)
  if (!mapView || mapView == m_mapView)

  m_mapView = mapView;

  connect(m_mapView, &MapQuickView::mapScaleChanged, this, [this]()
    m_mapScale = m_mapView->mapScale();
    emit mapScaleChanged();

    if (!m_annotationSubLayerOpen)

    m_visibleAtCurrentExtent = m_annotationSubLayerOpen->isVisibleAtScale(m_mapScale);

  emit mapViewChanged();

// create map package
void ControlAnnotationSublayerVisibility::createMapPackage(const QString& path)
  //! [open mobile map package cpp snippet]
  // instatiate a mobile map package
  m_mobileMapPackage = new MobileMapPackage(path, this);

  // wait for the mobile map package to load
  connect(m_mobileMapPackage, &MobileMapPackage::doneLoading, this, [this](Error error)
    if (!error.isEmpty())
      qDebug() << QString("Package load error: %1 %2").arg(error.message(), error.additionalMessage());

    if (!m_mobileMapPackage || !m_mapView || m_mobileMapPackage->maps().isEmpty())

    // The package contains a list of maps that could be shown in the UI for selection.
    // For simplicity, obtain the first map in the list of maps.
    // set the map on the map view to display

    m_layerListModel = mapView()->map()->operationalLayers();
    for (Layer* layer : *m_layerListModel)
      if (layer->layerType() == LayerType::AnnotationLayer)
        m_annoLayer = layer;
        connect(m_annoLayer, &Layer::doneLoading, this, [this](Error error)
          if (!error.isEmpty())
            qDebug() << QString("Package load error: %1 %2").arg(error.message(), error.additionalMessage());

          m_annotationSubLayerClosed = dynamic_cast<AnnotationSublayer*>(m_annoLayer->subLayerContents()[0]);
          m_annotationSubLayerOpen = dynamic_cast<AnnotationSublayer*>(m_annoLayer->subLayerContents()[1]);
          m_closedLayerText = m_annotationSubLayerClosed->name();
          m_openLayerText = QString("%1 (1:%2 - 1:%3)").arg(m_annotationSubLayerOpen->name()).arg(m_annotationSubLayerOpen->maxScale()).arg(m_annotationSubLayerOpen->minScale());
          emit openLayerTextChanged();
          emit closedLayerTextChanged();

  //! [open mobile map package cpp snippet]

void ControlAnnotationSublayerVisibility::openLayerVisible()
  if (!m_annotationSubLayerOpen)


void ControlAnnotationSublayerVisibility::closedLayerVisible()
  if (!m_annotationSubLayerClosed)


namespace Esri
namespace ArcGISRuntime
class Map;
class MapQuickView;
class MobileMapPackage;
class AnnotationSublayer;
class LayerListModel;
class Layer;

#include <QObject>

class ControlAnnotationSublayerVisibility : public QObject

  Q_PROPERTY(Esri::ArcGISRuntime::MapQuickView* mapView READ mapView WRITE setMapView NOTIFY mapViewChanged)
  Q_PROPERTY(QString openLayerText MEMBER m_openLayerText NOTIFY openLayerTextChanged)
  Q_PROPERTY(QString closedLayerText MEMBER m_closedLayerText NOTIFY closedLayerTextChanged)
  Q_PROPERTY(double mapScale MEMBER m_mapScale NOTIFY mapScaleChanged())
  Q_PROPERTY(bool visibleAtCurrentExtent MEMBER m_visibleAtCurrentExtent NOTIFY visibleAtCurrentExtentChanged())

  explicit ControlAnnotationSublayerVisibility(QObject* parent = nullptr);

  static void init();

  Q_INVOKABLE void openLayerVisible();
  Q_INVOKABLE void closedLayerVisible();

  void mapViewChanged();
  void openLayerTextChanged();
  void closedLayerTextChanged();
  void mapScaleChanged();
  void visibleAtCurrentExtentChanged();

  Esri::ArcGISRuntime::MapQuickView* mapView() const;
  void setMapView(Esri::ArcGISRuntime::MapQuickView* mapView);
  void createMapPackage(const QString& path);

  Esri::ArcGISRuntime::Map* m_map = nullptr;
  Esri::ArcGISRuntime::MapQuickView* m_mapView = nullptr;
  Esri::ArcGISRuntime::MobileMapPackage* m_mobileMapPackage = nullptr;
  Esri::ArcGISRuntime::AnnotationSublayer* m_annotationSubLayerOpen = nullptr;
  Esri::ArcGISRuntime::AnnotationSublayer* m_annotationSubLayerClosed = nullptr;
  Esri::ArcGISRuntime::LayerListModel* m_layerListModel = nullptr;
  Esri::ArcGISRuntime::Layer* m_annoLayer = nullptr;

  QString m_openLayerText;
  QString m_closedLayerText;
  bool m_visibleAtCurrentExtent;
  double m_mapScale = 0.0;