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

Returns a geometry editor that allows users to interactively create and edit geometries by interacting with the view.

This function was introduced in Esri::ArcGISRuntime 200.1.

See also setGeometryEditor().

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 exception will occur.

bool MapView::isMagnifierMapPanningEnabled() const

Gets whether panning the map with the magifier is enabled. Returns true if panning the map with the magnifier is enabled.

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

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.

After the MapView::map has been assigned and loaded, call LocationDisplay::start() to initiate location updates from the AbstractLocationDataSource.

Use the LocationDisplayAutoPanMode 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 mapPoint within the map view's spatial reference to a screen coordinate.

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

Gets 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, load the Map into your app before you assign it to a MapView.

See also setMap().

double MapView::mapRotation() const

Gets 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::setViewpointRotation or GeoView::setViewpoint.

[virtual protected] void MapView::mapRotationChangedEvent()

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

double MapView::mapScale() const

Gets 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::setViewpointScale.

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 map view's background grid to backgroundGrid.

The background grid determines the color and context grid of a map view when no MapView::map has been set.

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 MapView::backgroundGrid is ignored.

The default BackgroundGrid color is gray with black grid lines.

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 map view's grid to grid.

See also grid().

void MapView::setMagnifierEnabled(bool magnifierEnabled)

Sets whether the magnifier is enabled.

• magnifierEnabled true to enable the magnifier.

See also isMagnifierEnabled().

void MapView::setMagnifierMapPanningEnabled(bool magnifierMapPanningEnabled)

Sets whether panning the map with the magnifier is enabled. If true, MapView is panned automatically when the magnifier gets near the edge of the MapView.

• magnifierMapPanningEnabled true to enable map panning with the magnifier.

See also isMagnifierMapPanningEnabled().

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

Sets the map.

• map - The map to associate with this map view.

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 100.12] void MapView::setSketchEditor(Esri::ArcGISRuntime::SketchEditor *sketchEditor)

Sets the map view's sketch editor to sketchEditor.

This function was introduced in Esri::ArcGISRuntime 100.12.

See also sketchEditor().

Esri::ArcGISRuntime::TaskWatcher MapView::setViewpointAnimated(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.

Returns a TaskWatcher for the asynchronous task.

Esri::ArcGISRuntime::TaskWatcher MapView::setViewpointCenter(const Esri::ArcGISRuntime::Point &center)

Set the viewpoint asynchronously with a center point.

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

Returns a TaskWatcher for the asynchronous task.

Esri::ArcGISRuntime::TaskWatcher MapView::setViewpointCenter(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.

Returns a TaskWatcher for the asynchronous task.

Esri::ArcGISRuntime::TaskWatcher MapView::setViewpointGeometry(const Esri::ArcGISRuntime::Geometry &boundingGeometry)

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

• boundingGeometry - The geometry to zoom to.

Returns a TaskWatcher for the asynchronous task.

Esri::ArcGISRuntime::TaskWatcher MapView::setViewpointGeometry(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.

Returns a TaskWatcher for the asynchronous task.

Esri::ArcGISRuntime::TaskWatcher MapView::setViewpointRotation(double angleDegrees)

Rotates the map view to the provided angle.

The angle will be normalized between 0 and 360 degrees.

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

Returns a TaskWatcher for the asynchronous task.

Esri::ArcGISRuntime::TaskWatcher MapView::setViewpointScale(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.

Returns a TaskWatcher for the asynchronous task.

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

Sets the WrapAroundMode.

• wrapAroundMode - The WrapAroundMode to set.

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

Esri::ArcGISRuntime::SketchEditor *MapView::sketchEditor() const

Returns a sketch editor that allows users to interactively sketch geometries on the view.

Returns the sketch editor associated with this map view if it exists.

See also setSketchEditor().

double MapView::unitsPerDIP() const

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

This represents the spatial resolution of the MapView. The value changes according to the MapView::mapScale (decreasing 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

Gets the current visible area of the map view.

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.

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

Gets the current WrapAroundMode, indicating if continuous panning across the international date line is enabled (true).

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 mode is enabled, geometries returned from MapView::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. The default value is WrapAroundMode::EnabledWhenSupported.

See also setWrapAroundMode().