Module com.esri.arcgisruntime
Package com.esri.arcgisruntime.mapping.view

Class MapView

  • All Implemented Interfaces:
    Styleable, EventTarget, Skinnable
    public final class MapView
extends GeoView
    A user interface control that displays two-dimensional (2D) geographic content defined by an ArcGISMap.

    To display an ArcGISMap, add a MapView control to your app and assign the map to it. This loads the map, its basemap and collection of operational layers, and displays their 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 of the MapView is represented by the Viewpoint.

    You can programmatically set the visible area by specifying a viewpoint. For example, setViewpointGeometryAsync(Geometry) sets the visible area to the extent of a provided geometry, and setViewpointCenterAsync(Point) zooms to a given scale, centered at the given point. Any geometries passed to these methods are automatically projected to match the SpatialReference of the map view's ArcGISMap, if required.

    To determine the current visible area or the center point and scale of a MapView, call GeoView.getCurrentViewpoint(Viewpoint.Type). Call GeoView.isNavigating() to ensure that any user-initiated or programmatic navigation is complete before getting the current Viewpoint.

    In an MVC architecture, this class represents the View tier. The Model tier is represented by the ArcGISMap object which provides a collection of operational layers and a Basemap. A Layer provides a visual representation of geographic information and comes in many forms. The types of layers that are displayed in a MapView are two-dimensional in nature; meaning they are displayed in X/Y coordinate space.

    This class must only be created and used on the UI thread. A MapView cannot be used after it has been disposed.

    Since:
    100.0.0
    See Also:
    ArcGISMap

    • Property Detail

      • wrapAroundMode

        public ObjectProperty<WrapAroundMode> wrapAroundModeProperty
        Indicates whether continuous panning across the international date line is enabled.

        By default, the MapView attempts to wrap the ArcGISMap 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.ENABLE_WHEN_SUPPORTED. To remove the wraparound behavior set the value to WrapAroundMode.DISABLED.

        If wraparound is enabled, geometries returned from getVisibleArea() 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(Geometry).

        The default value is WrapAroundMode.ENABLE_WHEN_SUPPORTED.

        Since:
        200.0.0
        See Also:
        getWrapAroundMode(), setWrapAroundMode(WrapAroundMode)

      • map

        public ObjectProperty<ArcGISMap> mapProperty
        The map that is currently set to the map view.

        Setting a non-loaded map to a view starts the load process of the map so the map can be displayed once loaded.

        Since:
        200.0.0
        See Also:
        getMap(), setMap(ArcGISMap)

      • viewInsets

        public ObjectProperty<Insets> viewInsetsProperty
        The insets on the MapView in device-independent pixels (DIP).

        ViewInsets define the edges of the MapView that may be obscured by other UI elements.

        Insets are useful to shift UI controls (such as license string, callout, etc) which are overlaid on the view. An application may need to do this shift to make room for application specific controls.

        It also affects the reported visible area, which will now be the area of the view minus the area of the insets.

        Insets may be invalidated when the view is resized. If the insets are bigger than the view size, they are ignored.

        Since:
        100.1.0
        See Also:
        getViewInsets(), setViewInsets(Insets)

      • grid

        public ObjectProperty<Grid> gridProperty
        A 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 getMap() has been loaded.

        The default value is null.

        Since:
        200.0.0
        See Also:
        getGrid(), setGrid(Grid)

      • locationDisplay

        public ReadOnlyObjectProperty<LocationDisplay> locationDisplayProperty
        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.getLocationDataSource(). Although the LocationDisplay.getLocationDataSource() 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 LocationDataSource.

        Once the getMap() has been assigned and loaded, call LocationDisplay.startAsync() to initiate location updates from the LocationDataSource.

        Use the LocationDisplay.getAutoPanMode() enumerations to build navigation or compass style apps. For example, adopt LocationDisplay.AutoPanMode.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.

        Since:
        200.0.0
        See Also:
        getLocationDisplay()

    • Constructor Detail

      • MapView

        public MapView()
        Creates a new MapView instance.
        Since:
        100.0.0

    • Method Detail

      • getSpatialReference

        public SpatialReference getSpatialReference()
        Gets the spatial reference.
        Specified by:
        getSpatialReference in class GeoView
        Returns:
        the spatial reference, null if the ArcGISMap is null
        Since:
        100.0.0

      • wrapAroundModeProperty

        public ObjectProperty<WrapAroundMode> wrapAroundModeProperty()
        Indicates whether continuous panning across the international date line is enabled.

        By default, the MapView attempts to wrap the ArcGISMap 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.ENABLE_WHEN_SUPPORTED. To remove the wraparound behavior set the value to WrapAroundMode.DISABLED.

        If wraparound is enabled, geometries returned from getVisibleArea() 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(Geometry).

        The default value is WrapAroundMode.ENABLE_WHEN_SUPPORTED.

        Since:
        200.0.0
        See Also:
        getWrapAroundMode(), setWrapAroundMode(WrapAroundMode)

      • getWrapAroundMode

        public WrapAroundMode getWrapAroundMode()
        Gets the wrap around mode.

        If a map is in wrap around mode then you can pan across the international date line if your BaseMap is in a suitable SpatialReference.

        Returns:
        the wrap around mode
        Since:
        100.0.0

      • setWrapAroundMode

        public void setWrapAroundMode​(WrapAroundMode wrapAroundMode)
        Sets the wrap around mode.

        If a map is in wrap around mode then you can pan across the international date line if your BaseMap is in a suitable SpatialReference.

        Parameters:
        wrapAroundMode - the new wrap around mode
        Throws:
        java.lang.IllegalArgumentException - if wrapAroundMode is null
        Since:
        100.0.0

      • getMapScale

        public double getMapScale()
        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 setViewpointScaleAsync(double).

        The value is NAN until the load status of the ArcGISMap is LoadStatus.LOADED and the draw status of the GeoView is DrawStatus.COMPLETED.

        Returns:
        the scale of the MapView
        Since:
        100.0.0

      • getMapRotation

        public double getMapRotation()
        Gets the rotation angle of the ArcGISMap 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 ArcGISMap.

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

        Returns:
        the rotation angle of the ArcGISMap in degrees from its north-south direction
        Since:
        100.0.0
        See Also:
        GeoView.setViewpoint(Viewpoint)

      • getBackgroundGrid

        public BackgroundGrid getBackgroundGrid()
        Gets the BackgroundGrid set on the MapView.
        Returns:
        the BackgroundGrid currently set on the MapView
        Since:
        100.0.0

      • setBackgroundGrid

        public void setBackgroundGrid​(BackgroundGrid backgroundGrid)
        Sets the desired BackgroundGrid on the MapView.
        Parameters:
        backgroundGrid - the BackgroundGrid to be applied to the MapView
        Throws:
        java.lang.IllegalArgumentException - if the backgroundGrid is null
        Since:
        100.0.0

      • getUnitsPerDensityIndependentPixel

        public double getUnitsPerDensityIndependentPixel()
        Gets 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 getMapScale() (it decreases as the user zooms in, for example).

        The value is NAN until the load status of the ArcGISMap is LoadStatus.LOADED and the draw status of the GeoView is DrawStatus.COMPLETED.

        Returns:
        the size of each device-independent pixel (DIP) in map units
        Since:
        100.0.0

      • getVisibleArea

        public Polygon getVisibleArea()
        Gets the map view's visible area.

        The visible area represents the portion of the ArcGISMap that is visible in the MapView. When a new ArcGISMap is assigned to a MapView, the default value of the visible area is set from the GeoModel.getInitialViewpoint().

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

        Returns:
        the visible area
        Since:
        100.0.0

      • setViewpointAsync

        public ListenableFuture<java.lang.Boolean> setViewpointAsync​(Viewpoint viewpoint,
                                                             float durationSeconds,
                                                             AnimationCurve animationCurve)
        Animates the display to the new viewpoint using the provided animation curve. The AnimationCurve defines the animation easing function.
        Parameters:
        viewpoint - the visible area to display in the view
        durationSeconds - the time for the transition animation to complete, in seconds
        animationCurve - the type of animation curve
        Returns:
        a ListenableFuture. Add a listener to this to know when the viewpoint has finished animating. The result of the future indicates if the operation completed successfully or not.
        Throws:
        java.lang.IllegalArgumentException - if viewpoint is null
        java.lang.IllegalArgumentException - if animationCurve is null
        Since:
        100.1.0

      • setViewpointCenterAsync

        public ListenableFuture<java.lang.Boolean> setViewpointCenterAsync​(Point point)
        Centers the map view at the provided center point.
        Parameters:
        point - the location at which to center the map view
        Returns:
        a ListenableFuture. Add a listener to this to know when the viewpoint has finished animating. The result of the future indicates if the operation completed successfully or not.
        Throws:
        java.lang.NullPointerException - if argument is null
        Since:
        100.0.0

      • setViewpointGeometryAsync

        public ListenableFuture<java.lang.Boolean> setViewpointGeometryAsync​(Geometry boundingGeometry)
        Zooms and pans the map view to the extent of the provided geometry.
        Parameters:
        boundingGeometry - the geometry to zoom to
        Returns:
        a ListenableFuture. Add a listener to this to know when the viewpoint has finished animating. The result of the future indicates if the operation completed successfully or not.
        Throws:
        java.lang.NullPointerException - if the argument is null
        Since:
        100.0.0

      • setViewpointGeometryAsync

        public ListenableFuture<java.lang.Boolean> setViewpointGeometryAsync​(Geometry boundingGeometry,
                                                                     double padding)
        Zooms and pans the map view to the extent of the provided geometry with additional padding.
        Parameters:
        boundingGeometry - the geometry to zoom to
        padding - the minimum amount of padding around the bounding geometry in pixels
        Returns:
        a ListenableFuture. Add a listener to this to know when the viewpoint has finished animating. The result of the future indicates if the operation completed successfully or not.
        Throws:
        java.lang.NullPointerException - if the bounding geometry is null
        Since:
        100.0.0

      • setViewpointRotationAsync

        public ListenableFuture<java.lang.Boolean> setViewpointRotationAsync​(double angleDegrees)
        Rotates the map view to the provided angle.

        The angle will be normalized between 0 and 360 degrees.

        Parameters:
        angleDegrees - the degrees to rotate to (in counterclockwise direction)
        Returns:
        a ListenableFuture. Add a listener to this to know when the viewpoint has finished animating. The result of the future indicates if the operation completed successfully or not.
        Since:
        100.0.0

      • setViewpointScaleAsync

        public ListenableFuture<java.lang.Boolean> setViewpointScaleAsync​(double scale)
        Zooms the map view to the provided scale around its current center point.
        Parameters:
        scale - the scale to zoom to. For example, 50000 is a scale of 1:50,000.
        Returns:
        a ListenableFuture. Add a listener to this to know when the viewpoint has finished animating. The result of the future indicates if the operation completed successfully or not.
        Since:
        100.0.0

      • setViewpointCenterAsync

        public ListenableFuture<java.lang.Boolean> setViewpointCenterAsync​(Point center,
                                                                   double scale)
        Centers the map view at the provided center point and zooms to the given scale.
        Parameters:
        center - the location at which to center the map view
        scale - the scale at which the map is displayed
        Returns:
        a ListenableFuture. Add a listener to this to know when the viewpoint has finished animating. The result of the future indicates if the operation completed successfully or not.
        Throws:
        java.lang.NullPointerException - if the center is null
        Since:
        100.0.0

      • mapProperty

        public ObjectProperty<ArcGISMap> mapProperty()
        The map that is currently set to the map view.

        Setting a non-loaded map to a view starts the load process of the map so the map can be displayed once loaded.

        Since:
        200.0.0
        See Also:
        getMap(), setMap(ArcGISMap)

      • getMap

        public ArcGISMap getMap()
        Gets the map that the MapView is displaying.
        Returns:
        the ArcGISMap
        Since:
        100.0.0

      • setMap

        public void setMap​(ArcGISMap map)
        Sets the map that the MapView is displaying.

        If you assign an ArcGISMap 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.loadAsync() to load the ArcGISMap into your app before you assign it to a MapView.

        Parameters:
        map - the new ArcGISMap
        Since:
        100.0.0

      • locationToScreen

        public Point2D locationToScreen​(Point mapPoint)
        Converts a Point in map coordinates to a javafx.geometry.Point2D representing JavaFX local coordinates. Coordinate values are in pixels, relative to the top-left corner of the MapView's screen location.

        Use this method to help perform custom drawing, or to locate other user interface components, relative to specific map coordinates. For example, calculate the screen coordinates at which to show a button so that it displays adjacent to a specific feature or raster cell in the map.

        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.

        If the wraparound mode is active, this method returns the closest screen location matching the specified map location. 'Closest' meaning: If it's in view, return that location, otherwise return for the frame where the location is the closest to the center of the view.

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

        Parameters:
        mapPoint - the map point
        Returns:
        an javafx.geometry.Point2D representing the JavaFX local coordinates.
        Throws:
        java.lang.IllegalArgumentException - if mapPoint is null
        Since:
        100.0.0

      • screenToLocation

        public Point screenToLocation​(Point2D screenPoint)
        Converts a point in JavaFX local coordinates to a location in map coordinates.

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

        Parameters:
        screenPoint - the point in JavaFX local coordinates
        Returns:
        a point object. Null is returned if the map view's spatial reference is not yet known, for example, before the viewed map is loaded.
        Throws:
        java.lang.IllegalArgumentException - if screenPoint is null
        Since:
        100.0.0

      • setViewInsets

        public void setViewInsets​(Insets viewInsets)
        Sets the specified insets on the view.

        Units are specified in density-independent pixels (DIPs)

        Parameters:
        viewInsets - insets to be set on the view, can be null. If null, the insets will be set to empty.
        Since:
        100.1.0
        See Also:
        viewInsetsProperty()

      • viewInsetsProperty

        public ObjectProperty<Insets> viewInsetsProperty()
        The insets on the MapView in device-independent pixels (DIP).

        ViewInsets define the edges of the MapView that may be obscured by other UI elements.

        Insets are useful to shift UI controls (such as license string, callout, etc) which are overlaid on the view. An application may need to do this shift to make room for application specific controls.

        It also affects the reported visible area, which will now be the area of the view minus the area of the insets.

        Insets may be invalidated when the view is resized. If the insets are bigger than the view size, they are ignored.

        Since:
        100.1.0
        See Also:
        getViewInsets(), setViewInsets(Insets)

      • getViewInsets

        public Insets getViewInsets()
        Gets the insets on the view.
        Returns:
        the insets
        Since:
        100.1.0

      • addMapRotationChangedListener

        @Deprecated(since="200.0.0",
            forRemoval=true)
public void addMapRotationChangedListener​(MapRotationChangedListener listener)
        Deprecated, for removal: This API element is subject to removal in a future version.
        As of 200.0.0, use ObservableValue.addListener(ChangeListener) on mapRotationProperty().
        Adds a listener for when map rotation has changed.
        Parameters:
        listener - the listener
        Throws:
        java.lang.IllegalArgumentException - if the listener is null
        Since:
        100.0.0

      • removeMapRotationChangedListener

        @Deprecated(since="200.0.0",
            forRemoval=true)
public boolean removeMapRotationChangedListener​(MapRotationChangedListener listener)
        Deprecated, for removal: This API element is subject to removal in a future version.
        As of 200.0.0, use ObservableValue.addListener(ChangeListener) on mapRotationProperty().
        Removes a map rotation changed listener.
        Parameters:
        listener - the listener
        Returns:
        true, if successful
        Since:
        100.0.0

      • addMapScaleChangedListener

        @Deprecated(since="200.0.0",
            forRemoval=true)
public void addMapScaleChangedListener​(MapScaleChangedListener listener)
        Deprecated, for removal: This API element is subject to removal in a future version.
        As of 200.0.0, use ObservableValue.addListener(ChangeListener) on mapScaleProperty().
        Adds a listener for when map scale has changed.
        Parameters:
        listener - the listener
        Throws:
        java.lang.IllegalArgumentException - if the listener is null
        Since:
        100.0.0

      • removeMapScaleChangedListener

        @Deprecated(since="200.0.0",
            forRemoval=true)
public boolean removeMapScaleChangedListener​(MapScaleChangedListener listener)
        Deprecated, for removal: This API element is subject to removal in a future version.
        As of 200.0.0, use ObservableValue.addListener(ChangeListener) on mapScaleProperty().
        Removes a map scale changed listener.
        Parameters:
        listener - the listener
        Returns:
        true, if successful
        Since:
        100.0.0

      • setSketchEditor

        public void setSketchEditor​(SketchEditor sketchEditor)
        Sets the sketch editor, which allows users to interactively sketch geometries on the view.
        Parameters:
        sketchEditor - a sketch editor, can be null
        Since:
        100.1.0
        See Also:
        SketchEditor

      • getSketchEditor

        public SketchEditor getSketchEditor()
        Gets the current sketch editor, or null if not set. A sketch editor allows users to interactively sketch geometries on the view
        Returns:
        the current sketch editor, or null if not set
        Since:
        100.1.0

      • gridProperty

        public ObjectProperty<Grid> gridProperty()
        A 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 getMap() has been loaded.

        The default value is null.

        Since:
        200.0.0
        See Also:
        getGrid(), setGrid(Grid)

      • setGrid

        public void setGrid​(Grid grid)
        Sets a grid to be displayed on top of the MapView.

        If a developer wants to temporarily hide the grid, they can change the grid's visibility. Setting a grid to not visible will hide the grid and its labels. This method should be used in preference to setting the grid to null, which is an expensive operation.

        Parameters:
        grid - grid to display on top of the MapView, can be null
        Since:
        100.0.0
        See Also:
        getGrid(), Grid.setVisible(boolean), LatitudeLongitudeGrid, MgrsGrid, UsngGrid, UtmGrid

      • getLabeling

        public ViewLabelProperties getLabeling()
        Gets the view label properties.

        This property determines whether labels are created, added and animated for all of the layers and graphic overlays in the view. For example, you can prevent labels displaying in the GeoView if you set ViewLabelProperties.isLabelingEnabled() to false. This overrides the labelsEnabled properties set on all layers and graphic overlays in the view. The default value of ViewLabelProperties.isLabelingEnabled() is true.

        Overrides:
        getLabeling in class GeoView
        Returns:
        the view label properties
        Since:
        100.4.0

      • setLabeling

        public void setLabeling​(ViewLabelProperties viewLabelProperties)
        Sets the view label properties.

        This property determines whether labels are created, added and animated for all of the layers and graphic overlays in the view. For example, you can prevent labels displaying in the GeoView if you set ViewLabelProperties.isLabelingEnabled() to false. This overrides the labelsEnabled properties set on all layers and graphic overlays in the view.

        Overrides:
        setLabeling in class GeoView
        Parameters:
        viewLabelProperties - the view label properties
        Since:
        100.4.0

      • locationDisplayProperty

        public ReadOnlyObjectProperty<LocationDisplay> locationDisplayProperty()
        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.getLocationDataSource(). Although the LocationDisplay.getLocationDataSource() 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 LocationDataSource.

        Once the getMap() has been assigned and loaded, call LocationDisplay.startAsync() to initiate location updates from the LocationDataSource.

        Use the LocationDisplay.getAutoPanMode() enumerations to build navigation or compass style apps. For example, adopt LocationDisplay.AutoPanMode.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.

        Since:
        200.0.0
        See Also:
        getLocationDisplay()

      • getLocationDisplay

        public LocationDisplay getLocationDisplay()
        Returns the MapView's LocationDisplay, used to display the current location from a location data source in the MapView. A MapView only has one LocationDisplay.
        Returns:
        the LocationDisplay object
        Since:
        100.9.0