ArcGIS Runtime SDK for Qt

Display a grid

A grid is a collection of horizontal and vertical lines which can be rendered over the top of your map view to help show the location of the current view point.

You can add the following types of grid to your map view:

  • Latitude and longitude grid - also known as a graticule
  • USNG - United States National Grid
  • MGRS - Military Grid Reference System
  • UTM - a grid showing top level UTM zones

Add a grid to your map view

To add a grid to your map view, first create an instance of the type of grid you want to display (such as a UTM grid) and set the grid property on the map view to the new grid instance.

// create a grid for showing Latitude and Longitude (Meridians and Parallels)
LatitudeLongitudeGrid* latlonGrid = new LatitudeLongitudeGrid(this);
m_mapView->setGrid(latlonGrid);

Controlling the label and grid visibility

The grid visibility can be controlled by using the grid's visible property.

m_mapView->grid()->setVisible(m_gridVisibility);

In addition, you can control the visibility of the labels on your grid using the label visible property.

m_mapView->grid()->setLabelsVisible(m_gridLabelVisibility);

Change the position of the grid labels

You can change the default positioning of the labels on your grid by changing the label position property to one of the following values:

  • Geographic
  • Bottom left
  • Bottom right
  • Top left
  • Top right
  • Center
  • All sides

For example, you could specify that the grid labeling be placed geographically. This will result in labels which are anchored to a geographical position on the map view.

// update the label positioning to geographic
m_mapView->grid()->setLabelPosition(GridLabelPosition::Geographic);

Alternatively, you may choose to position the labels so they are always on the top and right sides of your map view.

// update the label positioning to top right
m_mapView->grid()->setLabelPosition(GridLabelPosition::TopRight);

If you are positioning your labels against the top, bottom, left or right sides of your map views, you can set the offset distance between the label and the edge of the map by setting the label offset property.

Label positioning works in ways appropriate for different types of grids.

  • The latitude longitude grid respects the label position property.
  • MGRS and USNG grids define zonal resolution levels: the first level uses UTM zones; the second uses 100 km squares, each positioned in the center of the zone. As zooming continues, the UTM and 100 km identifiers are concatenated and positioned according to the label position property.
  • The UTM grid has a single level showing grid zones using identifiers like 30U or 11S. These labels are not affected by the label position property.

Changing the style of the grid lines and labels

The default styling of the grid line and labels is designed to be easily visible against most of the standard base maps, however you can optionally set your own styling against any given level of resolution of the grid. You can set the same styling for all levels of grid resolution, or use a different styling for various levels.

Before you can apply a new line or label style, you need to find the number of grid resolution levels for the type of grid you are displaying. This is found by querying the level count property.

// find the number of resolution levels in the grid
int gridLevels = m_mapView->grid()->levelCount();

The example below shows how to style your grid so it has purple lines and white labels with a blue halo.

Styling grid lines and grid labels is done by applying line symbols and text symbols, respectively. The characteristics of the symbols are used to style the lines and label. First, you first need to create line and text symbols to apply to your grid.

Then you can loop through each of the grid levels and apply the symbols to style your grid.

for (int level = 0; level < gridLevels; level++)
{
  const float width = 1 + level;
  SimpleLineSymbol* lineSym = new SimpleLineSymbol(SimpleLineSymbolStyle::Solid, QColor(color), width, this);
  m_mapView->grid()->setLineSymbol(level, lineSym);
}
for (int level = 0; level < gridLevels; level++)
{
  constexpr float size = 14.0f;
  TextSymbol* textSym = new TextSymbol("text", QColor(color), size, HorizontalAlignment::Left, VerticalAlignment::Bottom, this);
  textSym->setHaloColor(QColor("white"));
  textSym->setHaloWidth(2.0 + level);
  m_mapView->grid()->setTextSymbol(level, textSym);
}

Some of the grid types have additional properties to allow you to set the units of measure or the format of the labels. For example, the latitude longitude grid has a label style property which allows you to choose whether to label your grids using decimal degrees or formatted degrees, minutes and seconds.

// format the labels to display in degrees, minutes and seconds
static_cast<LatitudeLongitudeGrid*>(m_mapView->grid())->setLabelFormat(LatitudeLongitudeGridLabelFormat::DegreesMinutesSeconds);
Tip:

To work with any of these types of coordinates separately from a grid, you can use CoordinateFormatter to convert between a Point and a string formatted to contain any of these coordinate notations.

Supported spatial references for grid

The grids are supported to work in spatial references which are continuously pannable or some polar spatial references.

You can check the is pannable property on your spatial reference class to see if is pannable. Examples of continuously pannable spatial references include WGS84 (WKID 4326) and Web Mercator Auxiliary Sphere (WKID 102113, 102100, or 3857).

The following polar spatial references are also supported:

  • North pole Azimuthal Equidistant (WKID 102016)
  • North pole gnomic (WKID 102034)
  • North pole lambert equal area (WKID 102017)
  • North pole orthographic (WKID 102035)
  • North pole stereographic (WKID 102018)
  • NSIDE EASE North (WKID 3408)
  • NSIDC Sea Ice polar stereographic north (WKID 3411)
  • WGS 1984 NSIDC Sea Ice Polar Stereographic North (WKID 3413)
  • UPS North (WKID 32661)
  • South pole Azimuthal Equidistant (WKID 102019)
  • South pole gnomic (WKID 102036)
  • South pole lambert equal area (WKID 102020)
  • South pole orthographic (WKID 102037)
  • South pole stereographic (WKID 102021)
  • NSIDE EASE South (WKID 3409)
  • NSIDC Sea Ice polar stereographic South (WKID 3412)
  • UPS South (WKID 32761)
  • WGS1984 Antartic polar stereographic (WKID 3031)