MapView Class

Member Function Documentation

[protected] MapView::MapView(int width, int height)

Constructs a MapView with a certain width and height.

[override virtual] MapView::~MapView()

Destructor.

Esri::ArcGISRuntime::BackgroundGrid MapView::backgroundGrid() const

Returns the background grid that a Map is displayed on top of.

BackgroundGrid defines the color and context grid displayed in the MapView. If a map has been assigned, the Map displays on top of this background grid.

If the Map contains transparent areas, the BackgroundGrid may be visible within the Map::maxExtent and you may wish to define a BackgroundGrid::color appropriate to your map's symbology. If a Map has a Map::backgroundColor, the backgroundGrid is ignored.

The default BackgroundGrid color is gray with black grid lines.

See also setBackgroundGrid() and Map::backgroundColor.

Esri::ArcGISRuntime::CalloutData *MapView::calloutData() const

Gets the callout data from the map view.

The callout data that is returned can be modified, and then used with a view for display.

Views available for use with this and other models are available in the ArcGIS Maps SDK for Qt Toolkit. See the Toolkit API reference for details.

[since Esri::ArcGISRuntime 200.1] Esri::ArcGISRuntime::GeometryEditor *MapView::geometryEditor() const

Allows users to interactively create and edit geometries by interacting with the view.

After assigning a GeometryEditor to the MapView, a Geometry being edited by the GeometryEditor will be displayed using the context, orientation and spatial reference of the MapView.

It may be useful to transfer a GeometryEditor, with its partly edited Geometry, from one MapView to another MapView. For example, in a multi-view application, part-way through editing, a user may want to see and continue editing the partially edited geometry in a MapView using a different Basemap, rotation or SpatialReference (without changing the settings of their initial MapView).

A GeometryEditor can only be connected to one MapView at a time. If the same GeometryEditor is assigned to a second MapView without first detaching, then the previous MapView will automatically have its geometryEditor property changed to nullptr. The GeometryEditor will project the Geometry to the SpatialReference of the new MapView.

Starting or stopping Geometry editing using the GeometryEditor is independent of the GeometryEditor being attached to a MapView.

If editing the Geometry has already been started (using GeometryEditor::start()) then reassignment of the GeometryEditor will automatically:

• stop the editing, retain any changes, but undo can't be called on those changes.
• start the editing with the changed Geometry projected to the new MapView.

There is no difference between calling GeometryEditor::start(Esri::ArcGISRuntime::GeometryType) before or after the GeometryEditor is assigned to a MapView. GeometryEditor::stop does not detach the GeometryEditor from its current MapView.

If the SpatialReference of the MapView is changed (for example, by a different Map being connected to the MapView) then the GeometryEditor will automatically take the same actions:

• stop the editing, retain any changes, but undo can't be called on those changes.
• start the editing with the changed Geometry projected to the new MapView.

This function was introduced in Esri::ArcGISRuntime 200.1.

See also setGeometryEditor() and GeometryEditor.

Esri::ArcGISRuntime::Grid *MapView::grid() const

Gets the coordinate system grid to display on top of the MapView.

The Grid is a collection of horizontal and vertical lines which can be rendered over the top of a MapView to help show the location of the current Viewpoint. Supported grids include Military Grid Reference System (MGRSGrid), United States National Grid (USNGGrid), Universal Transverse Mercator (UTMGrid), and a grid of latitude and longitude lines (LatitudeLongitudeGrid). You can configure these grids by toggling their visibility and modifying their default layout and appearance. A grid will not display in the MapView until a MapView::map has been loaded.

The default value is nullptr.

See also setGrid().

bool MapView::isMagnifierEnabled() const

Returns true if the magnifier is enabled, otherwise false.

This method can't be called until a Map has been assigned to the MapView. If called before the map view is ready or the initialization of default magnifier fails, an ErrorType::CommonIllegalState error will occur.

bool MapView::isMagnifierMapPanningEnabled() const

Returns true if the MapView is panned automatically when the magnifier gets near the edge of the MapView, otherwise false.

The default value is true.

bool MapView::isRotationByPinchingEnabled() const

Gets whether the map view rotates using a two-finger twist gesture.

Rotation by pinching is disabled by default. Returns true if the map view rotates with a two-finger twist gestures.

bool MapView::isZoomByPinchingEnabled() const

Gets whether the map view zooms with a pinch gesture.

The default is true. Returns true if the map view zooms with a pinch gesture.

Esri::ArcGISRuntime::LocationDisplay *MapView::locationDisplay() const

Returns the location display manages and renders the device's current location on a MapView using a data source, such as a GPS sensor.

The device location is displayed as a blue, round symbol that is automatically refreshed by regular updates from the LocationDisplay::dataSource. Although the LocationDisplay::dataSource uses the device's location data source by default, you can configure it to use data sources such as NMEA, route tracker, indoors, and simulated data sources. For more information, see AbstractLocationDataSource.

Once the map has been assigned and loaded, call LocationDisplay::start to initiate location updates from the AbstractLocationDataSource.

Use the LocationDisplay::autoPanMode enumerations to build navigation or compass style apps. For example, adopt LocationDisplayAutoPanMode::Navigation to build an app that pans the MapView so that the current location symbol is shown near the bottom of the screen and the MapView is aligned with the direction of travel. You can also customize the symbols that display the device's location, its heading, the accuracy of the signal and the acquiring signal.

QPointF MapView::locationToScreen(const Esri::ArcGISRuntime::Point &mapPoint) const

Converts a location in map coordinates to screen coordinates relative to the upper-left corner of the map view.

• mapPoint - A location defined within the spatial reference of the map view.

The screen coordinates are in device-independent pixels (DIP) relative to the upper-left corner at position 0,0. The screen coordinates returned may lie outside the current map view bounds. For example, if a map of the world is zoomed in to the extent of Africa, a map location within South America would result in a screen coordinate that is outside the screens bounds.

If the WrapAroundMode is enabled on the map view, this method returns the closest screen location matching the specified map location. If the map coordinate is in the visible area the method will return that screen coordinate, otherwise it will return the screen coordinate from the frame closest to the visible area.

To call this method, assign a map to the map view, ensure that it is loaded and the draw status is DrawStatus::Completed.

Esri::ArcGISRuntime::Map *MapView::map() const

Returns the map that the MapView is displaying.

If you assign a Map to a MapView, the map, its Basemap, and collection of operational layers automatically start to load. When loading completes, the layers and basemap are rendered in the map view.

To validate the content of a map before you display it, call GeoModel::load to load the Map into your app before you assign it to a MapView.

See also setMap().

double MapView::mapRotation() const

Returns the rotation angle of the Map in degrees from its north-south direction.

If the map has been rotated in a clockwise direction, the rotation value is negative. If it has been rotated in a counterclockwise direction, the value is positive. For example, if the rotation value is -90, the top of the MapView will display an eastern part of the Map. Users can interactively rotate the map using the map view's keyboard, mouse or touch rotation gestures. You can rotate the map programmatically using methods that set the Viewpoint, such as MapView::setViewpointRotationAsync or GeoView::setViewpointAsync.

Users can interactively rotate the map using the map view's keyboard, mouse or touch rotation gestures. You can rotate the map programmatically using methods that set the Viewpoint, such as setViewpointRotationAsync(double) or GeoView::setViewpoint(const Esri::ArcGISRuntime::Viewpoint&).

See also GeoView::setViewpoint().

[virtual protected] void MapView::mapRotationChangedEvent()

Override this method to perform custom logic when the mapRotation changes.

double MapView::mapScale() const

Returns the scale of the MapView.

The scale represents the relationship between a distance in the MapView (on the screen) and the corresponding distance on the ground. For example, a scale of 100,000 indicates that one centimeter on the MapView display equates to one kilometer on the ground. Users can interactively change the scale using the map view's zooming gestures. You can set the scale programmatically using methods that set the Viewpoint, such as MapView::setViewpointScaleAsync.

Users can interactively change the scale using the map view's zooming gestures. You can set the scale programmatically using methods that set the Viewpoint, such as setViewpointScale(double).

The value is NaN until the load status of the Map is LoadStatus::Loaded and the draw status of the GeoView is DrawStatus::Completed.

[virtual protected] void MapView::mapScaleChangedEvent()

Override this method to perform custom logic when the mapScale changes.

Esri::ArcGISRuntime::Point MapView::screenToLocation(double screenX, double screenY) const

Converts screen coordinates relative to the upper-left corner of the map view to a location in map coordinates.

To use this method, assign a map to the map view. Ensure that it is loaded and the draw status is DrawStatus::Completed.

• screenX - The screen's x-coordinate to convert to map coordinate.
• screenY - The screen's y-coordinate to convert to map coordinate.

void MapView::setBackgroundGrid(const Esri::ArcGISRuntime::BackgroundGrid &backgroundGrid)

Sets the backgroundGrid to backgroundGrid.

See also backgroundGrid.

[since Esri::ArcGISRuntime 200.1] void MapView::setGeometryEditor(Esri::ArcGISRuntime::GeometryEditor *geometryEditor)

Sets the geometryEditor to geometryEditor.

This function was introduced in Esri::ArcGISRuntime 200.1.

See also geometryEditor.

void MapView::setGrid(Esri::ArcGISRuntime::Grid *grid)

Sets the grid to grid.

See also grid.

void MapView::setMagnifierEnabled(bool magnifierEnabled)

Sets the magnifierEnabled to magnifierEnabled.

See also isMagnifierEnabled.

void MapView::setMagnifierMapPanningEnabled(bool magnifierMapPanningEnabled)

Sets the allowMagnifierToPanMap to magnifierMapPanningEnabled.

See also isMagnifierMapPanningEnabled.

void MapView::setMap(Esri::ArcGISRuntime::Map *map)

Sets the map to map.

See also map.

void MapView::setRotationByPinchingEnabled(bool rotationByPinching)

Sets whether the map view rotates using a two-finger twist gesture.

Rotation by pinching is disabled by default.

• rotationByPinching - Whether the map view rotates with a two-finger twist gesture.

See also isRotationByPinchingEnabled().

[since Esri::ArcGISRuntime 200.2] QFuture<bool> MapView::setViewpointAsync(const Esri::ArcGISRuntime::Viewpoint &viewpoint, float durationSeconds, Esri::ArcGISRuntime::AnimationCurve curve)

Animates the display to the new viewpoint using the provided animation curve. The AnimationCurve defines the animation easing function.

• viewpoint - The visible area to display in the view.
• durationSeconds - The time for the transition animation to complete, in seconds.
• curve - The type of animation curve.

This method returns a QFuture for the asynchronous operation. Use future.then() to continue processing when the operation completes. Use future.onFailed() to handle exceptions of type ErrorException.

See Working with QFuture for further details.

This function was introduced in Esri::ArcGISRuntime 200.2.

[since Esri::ArcGISRuntime 200.2] QFuture<bool> MapView::setViewpointCenterAsync(const Esri::ArcGISRuntime::Point &center)

Centers the map view at the provided center point.

• center - The location at which to center the map view.

This method returns a QFuture for the asynchronous operation. Use future.then() to continue processing when the operation completes. Use future.onFailed() to handle exceptions of type ErrorException.

See Working with QFuture for further details.

This function was introduced in Esri::ArcGISRuntime 200.2.

[since Esri::ArcGISRuntime 200.2] QFuture<bool> MapView::setViewpointCenterAsync(const Esri::ArcGISRuntime::Point &center, double scale)

Centers the map view at the provided center point and zooms to the given scale.

• center - The location at which to center the map view.
• scale - The scale at which the map is displayed.

This method returns a QFuture for the asynchronous operation. Use future.then() to continue processing when the operation completes. Use future.onFailed() to handle exceptions of type ErrorException.

See Working with QFuture for further details.

This function was introduced in Esri::ArcGISRuntime 200.2.

[since Esri::ArcGISRuntime 200.2] QFuture<bool> MapView::setViewpointGeometryAsync(const Esri::ArcGISRuntime::Geometry &boundingGeometry)

Zooms and pans the map view to the extent of the provided geometry.

• boundingGeometry - The geometry to zoom to.

This method returns a QFuture for the asynchronous operation. Use future.then() to continue processing when the operation completes. Use future.onFailed() to handle exceptions of type ErrorException.

See Working with QFuture for further details.

This function was introduced in Esri::ArcGISRuntime 200.2.

[since Esri::ArcGISRuntime 200.2] QFuture<bool> MapView::setViewpointGeometryAsync(const Esri::ArcGISRuntime::Geometry &boundingGeometry, double paddingInDips)

Zooms and pans the map view to the extent of the provided geometry with additional padding.

• boundingGeometry - The geometry to zoom to.
• paddingInDips - The minimum amount of padding around the bounding geometry in pixels.

This method returns a QFuture for the asynchronous operation. Use future.then() to continue processing when the operation completes. Use future.onFailed() to handle exceptions of type ErrorException.

See Working with QFuture for further details.

This function was introduced in Esri::ArcGISRuntime 200.2.

[since Esri::ArcGISRuntime 200.2] QFuture<bool> MapView::setViewpointRotationAsync(double angleDegrees)

Rotates the map view to the provided angle.

• angleDegrees - The degrees to rotate to (in counterclockwise direction).

The angle will be normalized between 0 and 360 degrees.

This method returns a QFuture for the asynchronous operation. Use future.then() to continue processing when the operation completes. Use future.onFailed() to handle exceptions of type ErrorException.

See Working with QFuture for further details.

This function was introduced in Esri::ArcGISRuntime 200.2.

[since Esri::ArcGISRuntime 200.2] QFuture<bool> MapView::setViewpointScaleAsync(double scale)

Zooms the map view to the provided scale around its current center point.

• scale - The scale to zoom to. For example, 50000 is a scale of 1:50,000.

This method returns a QFuture for the asynchronous operation. Use future.then() to continue processing when the operation completes. Use future.onFailed() to handle exceptions of type ErrorException.

See Working with QFuture for further details.

This function was introduced in Esri::ArcGISRuntime 200.2.

void MapView::setWrapAroundMode(Esri::ArcGISRuntime::WrapAroundMode wrapAroundMode)

Sets the wrapAroundMode to wrapAroundMode.

See also wrapAroundMode.

void MapView::setZoomByPinchingEnabled(bool zoomByPinching)

Sets whether the map view zooms with a pinch gesture.

By default, zooming the map view with a pinch gesture is enabled.

• zoomByPinching - Whether the map view zooms with a pinch gesture.

See also isZoomByPinchingEnabled().

double MapView::unitsPerDIP() const

Returns the size of each device-independent pixel (DIP) in map units.

The represents the spatial resolution of the MapView. The value changes according to the scale (it decreases as the user zooms in, for example).

The value is NaN until the load status of the Map is LoadStatus::Loaded and the draw status of the GeoView is DrawStatus::Completed.

Esri::ArcGISRuntime::Polygon MapView::visibleArea() const

Returns the map view's visible area.

The visible area represents the portion of the Map that is visible in the MapView. When a new Map is assigned to a MapView, the default value of the visible area is set from the GeoModel::initialViewpoint.

Users can interactively navigate the map to change the visible area, or you can programmatically change this using methods that set the Viewpoint, such as GeoView::setViewpoint(const Esri::ArcGISRuntime::Viewpoint&).

The visible area polygon always contains one ring with four vertices, each representing a corner of the map. It is a Polygon and not an Envelope because the map may be rotated and each corner of the map may contain unique x-y coordinates. Note that the visible area excludes the portion of the map obscured by the map view's attribution bar. As a result, the edges and center of the visible area may not coincide with the bounds and center of the MapView.

Esri::ArcGISRuntime::WrapAroundMode MapView::wrapAroundMode() const

Returns whether continuous panning across the international date line is enabled.

By default, the MapView attempts to wrap the Map across the international date line for a continuous panning user experience. The eastern and western hemispheres wrap to form a continuous map, giving the impression that the map is endless.

You can apply wraparound to a MapView if certain conditions are met, as described in WrapAroundMode::EnabledWhenSupported. To remove the wraparound behavior set the value to WrapAroundMode::Disabled.

If wraparound is enabled, geometries returned from visibleArea may have coordinates outside the domain of the spatial reference of the map. Before using such geometries to perform spatial queries, address finding, or as feature geometries in a geodatabase, normalize them to lie within the spatial reference domain using GeometryEngine::normalizeCentralMeridian(const Esri::ArcGISRuntime::Geometry&).

The default value is WrapAroundMode::EnabledWhenSupported.

See also setWrapAroundMode().