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

Class MapView

java.lang.Object
javafx.scene.Node
javafx.scene.Parent
javafx.scene.layout.Region
javafx.scene.control.Control
com.esri.arcgisruntime.mapping.view.GeoView
com.esri.arcgisruntime.mapping.view.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.

A MapView is a user interface that displays ArcGISMap layers and graphics in 2D. It controls the area (extent) of the ArcGISMap 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 an ArcGISMap, 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.getCurrentViewpoint(Viewpoint.Type). Make sure that any user-initiated or programmatic navigation is complete before getting the current Viewpoint by calling GeoView.navigatingProperty().

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) 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 ArcGISMap, if required.

In an MVC architecture, the MapView represents the View tier. The Model tier is represented by the ArcGISMap object which can provide a collection of operational layers and a Basemap. You can only set one ArcGISMap per MapView, but you can swap the mapProperty() with another when the application is running.

See Map view for more information.

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:

  • Property Details Link icon

  • Constructor Details Link icon

    • MapView Link icon

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

  • Method Details Link icon

    • getSpatialReference Link icon

      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 Link icon

      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.

      Returns:
      the wrapAroundMode property
      Since:
      200.0.0
      See Also:

    • getWrapAroundMode Link icon

      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 Link icon

      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:
      IllegalArgumentException - if wrapAroundMode is null
      Since:
      100.0.0

    • mapScaleProperty Link icon

      public ReadOnlyDoubleProperty mapScaleProperty()
      The map view's current scale.
      Returns:
      the mapScale property
      Since:
      200.0.0
      See Also:

    • getMapScale Link icon

      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

    • mapRotationProperty Link icon

      public ReadOnlyDoubleProperty mapRotationProperty()
      The map view's current rotation.
      Returns:
      the mapRotation property
      Since:
      200.0.0
      See Also:

    • getMapRotation Link icon

      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:

    • backgroundGridProperty Link icon

      public ObjectProperty<BackgroundGrid> backgroundGridProperty()
      The background grid that an ArcGISMap is displayed on top of.

      BackgroundGrid defines the color and context grid displayed in the MapView. If a getMap() has been assigned, the ArcGISMap displays on top of this background grid.

      If the ArcGISMap contains transparent areas, the BackgroundGrid may be visible within the ArcGISMap.getMaxExtent() and you may wish to define a BackgroundGrid.getColor() appropriate to your map's symbology. If an ArcGISMap has an ArcGISMap.getBackgroundColor(), the getBackgroundGrid() is ignored.

      The default BackgroundGrid color is gray with black grid lines.

      This property must not be set to null.

      Returns:
      the backgroundGrid property
      Since:
      200.0.0
      See Also:

    • getBackgroundGrid Link icon

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

    • setBackgroundGrid Link icon

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

    • geometryEditorProperty Link icon

      public ObjectProperty<GeometryEditor> geometryEditorProperty()
      The GeometryEditor that allows users to interactively create and edit geometries by interacting with the view.
      Returns:
      the geometryEditor property
      Since:
      200.1.0
      See Also:

    • getGeometryEditor Link icon

      public GeometryEditor getGeometryEditor()
      Gets the value of the geometryEditor property.
      Property description:
      The GeometryEditor that allows users to interactively create and edit geometries by interacting with the view.
      Returns:
      the value of the geometryEditor property
      Since:
      200.1.0
      See Also:

    • setGeometryEditor Link icon

      public void setGeometryEditor(GeometryEditor geometryEditor)
      Sets the value of the geometryEditor property.
      Property description:
      The GeometryEditor that allows users to interactively create and edit geometries by interacting with the view.
      Parameters:
      geometryEditor - the value for the geometryEditor property
      Since:
      200.1.0
      See Also:

    • getUnitsPerDensityIndependentPixel Link icon

      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 Link icon

      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 Link icon

      public ListenableFuture<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:
      IllegalArgumentException - if viewpoint is null
      IllegalArgumentException - if animationCurve is null
      Since:
      100.1.0

    • setViewpointCenterAsync Link icon

      public ListenableFuture<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:
      NullPointerException - if argument is null
      Since:
      100.0.0

    • setViewpointGeometryAsync Link icon

      public ListenableFuture<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:
      NullPointerException - if the argument is null
      Since:
      100.0.0

    • setViewpointGeometryAsync Link icon

      public ListenableFuture<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:
      NullPointerException - if the bounding geometry is null
      Since:
      100.0.0

    • setViewpointRotationAsync Link icon

      public ListenableFuture<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 Link icon

      public ListenableFuture<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 Link icon

      public ListenableFuture<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:
      NullPointerException - if the center is null
      Since:
      100.0.0

    • mapProperty Link icon

      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.

      Returns:
      the map property
      Since:
      200.0.0
      See Also:

    • getMap Link icon

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

    • setMap Link icon

      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 Link icon

      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:
      IllegalArgumentException - if mapPoint is null
      Since:
      100.0.0

    • screenToLocation Link icon

      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:
      IllegalArgumentException - if screenPoint is null
      Since:
      100.0.0

    • setViewInsets Link icon

      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 Link icon

      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.

      Returns:
      the viewInsets property
      Since:
      100.1.0
      See Also:

    • getViewInsets Link icon

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

    • addMapRotationChangedListener Link icon

      @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:
      IllegalArgumentException - if the listener is null
      Since:
      100.0.0

    • removeMapRotationChangedListener Link icon

      @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 Link icon

      @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:
      IllegalArgumentException - if the listener is null
      Since:
      100.0.0

    • removeMapScaleChangedListener Link icon

      @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 Link icon

      @Deprecated(since="200.2.0", forRemoval=true) public void setSketchEditor(SketchEditor sketchEditor)
      Deprecated, for removal: This API element is subject to removal in a future version.
      As of 200.2.0, SketchEditor and associated types are deprecated. Use GeometryEditor instead.
      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:

    • getSketchEditor Link icon

      @Deprecated(since="200.2.0", forRemoval=true) public SketchEditor getSketchEditor()
      Deprecated, for removal: This API element is subject to removal in a future version.
      As of 200.2.0, SketchEditor and associated types are deprecated. Use GeometryEditor instead.
      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 Link icon

      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.

      Returns:
      the grid property
      Since:
      200.0.0
      See Also:

    • setGrid Link icon

      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 Link icon

      public Grid getGrid()
      Gets grid set to the MapView.
      Returns:
      grid set to the MapView, null if not set
      Since:
      100.0.0
      See Also:

    • getLabeling Link icon

      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 Link icon

      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 Link icon

      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.

      Returns:
      the locationDisplay property
      Since:
      200.0.0
      See Also:

    • getLocationDisplay Link icon

      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