MapView Class

Map."> MapView Class | ArcGISQtCpp
  • MapView
  • class Esri::ArcGISRuntime::MapView

    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
    Esri::ArcGISRuntime::Grid *grid() 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 setGrid(Esri::ArcGISRuntime::Grid *grid)
    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 &center)
    QFuture<bool> setViewpointCenterAsync(const Esri::ArcGISRuntime::Point &center, 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. 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 sets the visible area to the extent of a provided geometry, and setViewpointCenterAsync 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.

    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

    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 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 Map::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 setViewpointRotation(double) or GeoView::setViewpoint().

    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::setViewpointAsync.

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

    The default value is WrapAroundMode::EnabledWhenSupported.

    See also setWrapAroundMode().

    Your browser is no longer supported. Please upgrade your browser for the best experience. See our browser deprecation post for more details.