A user interface control that displays two-dimensional (2D) geographic content defined by a Map. More...
| Header: | #include <MapView.h> |
| Since: | Esri::ArcGISRuntime 100.0 |
| Inherits: | Esri::ArcGISRuntime::GeoView |
| Inherited By: | Esri::ArcGISRuntime::MapGraphicsView and Esri::ArcGISRuntime::MapQuickView |
Public Functions
| virtual | ~MapView() override |
| Esri::ArcGISRuntime::BackgroundGrid | backgroundGrid() const |
| Esri::ArcGISRuntime::CalloutData * | calloutData() const |
| Esri::ArcGISRuntime::GeometryEditor * | geometryEditor() const |
| bool | isMagnifierEnabled() const |
| bool | isMagnifierMapPanningEnabled() const |
| bool | isRotationByPinchingEnabled() const |
| bool | isZoomByPinchingEnabled() const |
| Esri::ArcGISRuntime::LocationDisplay * | locationDisplay() const |
| QPointF | locationToScreen(const Esri::ArcGISRuntime::Point &mapPoint) const |
| Esri::ArcGISRuntime::Map * | map() const |
| double | mapRotation() const |
| double | mapScale() const |
| Esri::ArcGISRuntime::Point | screenToLocation(double screenX, double screenY) const |
| void | setBackgroundGrid(const Esri::ArcGISRuntime::BackgroundGrid &backgroundGrid) |
| void | setGeometryEditor(Esri::ArcGISRuntime::GeometryEditor *geometryEditor) |
| void | setMagnifierEnabled(bool magnifierEnabled) |
| void | setMagnifierMapPanningEnabled(bool magnifierMapPanningEnabled) |
| void | setMap(Esri::ArcGISRuntime::Map *map) |
| void | setRotationByPinchingEnabled(bool rotationByPinching) |
| QFuture<bool> | setViewpointAsync(const Esri::ArcGISRuntime::Viewpoint &viewpoint, float durationSeconds, Esri::ArcGISRuntime::AnimationCurve curve) |
| QFuture<bool> | setViewpointCenterAsync(const Esri::ArcGISRuntime::Point ¢er) |
| QFuture<bool> | setViewpointCenterAsync(const Esri::ArcGISRuntime::Point ¢er, double scale) |
| QFuture<bool> | setViewpointGeometryAsync(const Esri::ArcGISRuntime::Geometry &boundingGeometry) |
| QFuture<bool> | setViewpointGeometryAsync(const Esri::ArcGISRuntime::Geometry &boundingGeometry, double paddingInDips) |
| QFuture<bool> | setViewpointRotationAsync(double angleDegrees) |
| QFuture<bool> | setViewpointScaleAsync(double scale) |
| void | setWrapAroundMode(Esri::ArcGISRuntime::WrapAroundMode wrapAroundMode) |
| void | setZoomByPinchingEnabled(bool zoomByPinching) |
| double | unitsPerDIP() const |
| Esri::ArcGISRuntime::Polygon | visibleArea() const |
| Esri::ArcGISRuntime::WrapAroundMode | wrapAroundMode() const |
Protected Functions
| MapView(int width, int height) | |
| virtual void | mapRotationChangedEvent() |
| virtual void | mapScaleChangedEvent() |
Detailed Description
A MapView is a user interface that displays Map layers and graphics in 2D. It controls the area (extent) of the Map that is visible and supports user interactions such as pan and zoom. A map view also provides access to the underlying layer data in a map.
To display a Map, add a MapView control to your app and assign the map to it. This loads the map and its content, such as a Basemap and collection of operational layers, and displays this content on screen.
User interactions such as pan, zoom, rotate, and identify or selection are supported in the MapView using touch, mouse, keyboard or pen/pencil. If required, you can override keys, clicks, and gestures to provide a specific user experience.
The visible area (Viewpoint) of the MapView is defined by the visible extent the map. To determine the current visible area or the center point and scale of a MapView, call GeoView::currentViewpoint(Esri::ArcGISRuntime::ViewpointType). Make sure that any user-initiated or programmatic navigation is complete before getting the current Viewpoint by calling GeoView::isNavigating.
You can programmatically set the visible area by specifying a viewpoint. For example, setViewpointGeometryAsync(const Esri::ArcGISRuntime::Geometry&) sets the visible area to the extent of a provided geometry, and setViewpointCenterAsync(const Esri::ArcGISRuntime::Point&) centers the map view at a given point. Any geometries passed to these methods are automatically projected to match the SpatialReference of the map view's Map, if required.
In an MVC architecture, the MapView represents the View tier. The Model tier is represented by the Map object which can provide a collection of operational layers and a Basemap. You can only set one Map per MapView, but you can swap the map with another when the application is running.
See Map view for more information.
Relevant samples:
- Set initial map area: Display a map with a predefined initial extent.
- ArcGIS tiled layer (URL): Load an ArcGIS tiled layer from a URL.
- Change basemap: Change a map's basemap. A basemap is beneath all layers on a `Map` and is used to provide visual reference for the operational layers.
- Change viewpoint: Set the map view to a new viewpoint.
- Configure basemap style parameters: Apply basemap style parameters customization for a basemap, such as displaying all labels in a specific language or displaying every label in their corresponding local language.
- Control time extent using time slider: This sample demonstrates how to use the time slider from the toolkit to visualize temporal data by applying a specific time extent.
- Create and edit geometries: Use the Geometry Editor to create new point, multipoint, polyline, or polygon geometries or to edit existing geometries by interacting with a map view.
- Cut geometry: Cut a geometry along a polyline.
- Display a grid: Display coordinate system grids including Latitude/Longitude, MGRS, UTM and USNG on a map view. Also, toggle label visibility and change the color of grid lines and grid labels.
- Display annotation: Display annotation from a feature service URL.
- Display device location with autopan modes: Display your current position on the map, as well as switch between different types of auto pan modes.
- Display draw status: Get the draw status of your map view or scene view to know when all layers in the map or scene have finished drawing.
- Display layer view draw state: Determine if a layer is currently being viewed.
- Display map: Display a map with an imagery basemap.
- Display overview map: Include an overview or inset map as an additional map view to show the wider context of the primary view.
- Download a preplanned map area: Take a map offline using a preplanned map area.
- Feature layer rendering mode (map): Render features statically or dynamically by setting the feature layer rendering mode.
- Find closest facility to an incident (interactive): Find a route to the closest facility from a location.
- Geodesic operations: Calculate a geodesic path between two points and measure its distance.
- Identify graphics: Display an alert message when a graphic is clicked.
- Map loaded: Determine the map's load status which can be: `NotLoaded`, `FailedToLoad`, `Loading`, `Loaded`, `Unknown`.
- Map rotation: Rotate a map.
- Min-Max scale: Restrict zooming between specific scale ranges.
- Open map (URL): Display a web map.
- Open mobile map (map package): Display a map from a mobile map package.
- OpenStreetMap layer: Add OpenStreetMap as a basemap layer.
- Service area: Find the service area within a network from a given point.
- Set initial map location: Display a basemap centered at an initial location and scale.
- Set map spatial reference: Specify a map's spatial reference.
- Set max extent: Set a max extent on the map.
- Show device location using indoor positioning: Show your device's real-time location while inside a building by using signals from indoor positioning beacons.
- Show magnifier: Tap and hold on a map to show a magnifier.
- Show popup: Show predefined popups from a web map.
- Sketch on map: This sample demonstrates how to use the Sketch Editor to edit or sketch a new point, line, or polygon geometry on to a map.
- Snap geometry edits: Use the Geometry Editor to edit a geometry and align it to existing geometries on a map.
- Spatial operations: Find the union, intersection, or difference of two geometries.
- Sync map and scene views: Keep the viewpoints of two views (e.g. MapView and SceneView) synchronized with each other.
- Take screenshot: Take a screenshot of the map.
- Token authentication: Access a web map that is secured with ArcGIS token-based authentication.
- WMS layer (URL): Display a WMS layer using a WMS service URL.
See also Map, GeoView, MapGraphicsView, and MapQuickView.
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.
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::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 ¢er)
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 ¢er, 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().