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

Class GraphicsOverlay

java.lang.Object
com.esri.arcgisruntime.mapping.view.GraphicsOverlay
All Implemented Interfaces:
PopupSource
public final class GraphicsOverlay extends Object implements PopupSource
Manages a collection of graphics that can be displayed in a map view or scene view.

Graphics overlays display a collection of graphics on top of all the layers (including reference layers) in a map view or scene view. Every map view or scene view can contain a collection of graphics overlays (GeoView.getGraphicsOverlays()), and each graphics overlay can contain a collection of graphics (getGraphics()). The graphics in the first GraphicsOverlay are drawn first, with subsequent ones on top. The Renderer provided by getRenderer() defines the symbology of the getGraphics() collection.

A graphic's Graphic.getZIndex() value defines its draw order within the graphics overlay that contains it. The Graphic.getZIndex() value applies in a map view, and in a scene view if the scene view drapes the graphics on the surface (LayerSceneProperties.SurfacePlacement.DRAPED_FLAT). In other scene view rendering, the graphic's display order is determined by the distance to the camera rather than by Z-index.

If the Graphic.getZIndex() value is not set, graphics will render in the order in which they were added to the graphics overlay. The first added is rendered first and subsequent ones on top. In rare cases, the rendering algorithm may change the display order to provide more efficient rendering. If ordering is important, set the Z-index explicitly on Graphics.

To improve view responsiveness, you can set the rendering mode to either of these options:

Since:
100.0.0
See Also:

  • Property Details

  • Constructor Details

    • GraphicsOverlay

      public GraphicsOverlay()
      Creates a new graphics overlay with default dynamic rendering mode.
      Since:
      100.0.0

    • GraphicsOverlay

      public GraphicsOverlay(GraphicsOverlay.RenderingMode renderingMode)
      Creates a new graphics overlay.
      Parameters:
      renderingMode - the rendering mode to use for this overlay
      Throws:
      IllegalArgumentException - if parameter is null
      Since:
      100.0.0

  • Method Details

    • getPopupDefinition

      public PopupDefinition getPopupDefinition()
      Gets the PopupDefinition set via setPopupDefinition(PopupDefinition), or null if one has not been set.
      Specified by:
      getPopupDefinition in interface PopupSource
      Returns:
      the GraphicOverlay's PopupDefinition
      Since:
      100.0.0
      See Also:

    • setPopupDefinition

      public void setPopupDefinition(PopupDefinition popupDefinition)
      Sets the PopupDefinition for the GraphicsOverlay, overriding any previous one set.
      Specified by:
      setPopupDefinition in interface PopupSource
      Parameters:
      popupDefinition - the PopupDefinition to set
      Since:
      100.0.0
      See Also:

    • isPopupEnabled

      public boolean isPopupEnabled()
      Description copied from interface: PopupSource
      Checks if the pop-up definition returned from PopupSource.getPopupDefinition() is enabled or disabled.
      Specified by:
      isPopupEnabled in interface PopupSource
      Returns:
      true if the pop-up definition is enabled; false otherwise. Will return false if an error occurs.
      See Also:

    • setPopupEnabled

      public void setPopupEnabled(boolean enabled)
      Description copied from interface: PopupSource
      Sets whether the pop-up definition returned from PopupSource.getPopupDefinition() is enabled or disabled.
      Specified by:
      setPopupEnabled in interface PopupSource
      Parameters:
      enabled - true to enable the PopupDefinition; false otherwise
      See Also:

    • getRenderingMode

      public GraphicsOverlay.RenderingMode getRenderingMode()
      Gets the rendering mode used to display graphics in the overlay.

      For more efficient rendering of large numbers of graphics, set the rendering mode to GraphicsOverlay.RenderingMode.STATIC. In order to ensure map responsiveness, static rendering does not refresh the display while pan and zoom operations are in progress. The amount of graphics an overlay can handle in this mode is mainly limited by the system memory.

      Returns:
      the rendering mode
      Since:
      100.0.0

    • isVisible

      public boolean isVisible()
      Checks if this graphics overlay is visible.
      Returns:
      true if the GraphicsOverlay is visible; false otherwise.
      Since:
      100.0.0

    • setVisible

      public void setVisible(boolean visible)
      Sets if this graphics overlay is visible.
      Parameters:
      visible - true to set the graphics overlay visible
      Since:
      100.0.0

    • getOpacity

      public float getOpacity()
      Gets the opacity for the graphics overlay.

      Must be a value between 0 and 1 with 1 being solid or opaque and 0 being transparent. The default opacity is 1.

      Returns:
      the opacity
      Since:
      100.0.0

    • setOpacity

      public void setOpacity(float opacity)
      Sets the opacity for the graphics overlay.

      Must be a value between 0 and 1 with 1 being solid or opaque and 0 being transparent.

      Parameters:
      opacity - the new opacity
      Throws:
      IllegalArgumentException - if opacity is less than 0 or greater than 1
      Since:
      100.0.0

    • getMinScale

      public double getMinScale()
      Gets the minimum scale at which to display the graphics overlay. A large number allows the map to display the layer when zooming further out.

      This controls the minimum scale at which the graphics overlay is displayed. If the current map scale is larger than the minimum scale, then this graphics overlay will not be displayed.

      A scale is usually referred to as 1:X, where X is the scale specified here. This value is the relative scale to the real world, where one inch on the screen is X inches in the real world. Note that this is only an approximation and is dependent on the map's projection that can add some distortion, as well as the system's reported DPI setting which doesn't necessarily match the actual DPI of the screen.

      The default value of this property is NaN which makes the layer unbounded by any scale.

      Returns:
      the minimum scale level at which the graphics overlay is displayed.
      Since:
      100.0.0

    • setMinScale

      public void setMinScale(double minScale)
      Sets the minimum scale at which to display the graphics overlay. A large number allows the map to display the layer when zooming further out.

      This controls the minimum scale at which the graphics overlay is displayed. If the current map scale is larger than the minimum scale, then this graphics overlay will not be displayed.

      A scale is usually referred to as 1:X, where X is the scale specified here. This value is the relative scale to the real world, where one inch on the screen is X inches in the real world. Note that this is only an approximation and is dependent on the map's projection that can add some distortion, as well as the system's reported DPI setting which doesn't necessarily match the actual DPI of the screen.

      Parameters:
      minScale - the new minimum scale
      Since:
      100.0.0

    • getMaxScale

      public double getMaxScale()
      Gets the maximum scale at which to display the graphics overlay. A small number allows the map to display the layer when zooming further in.

      This controls the maximum scale at which the graphics overlay is displayed. If the current map scale is smaller than the maximum scale, then this graphics overlay will not be displayed.

      A scale is usually referred to as 1:X, where X is the scale specified here. This value is the relative scale to the real world, where one inch on the screen is X inches in the real world. Note that this is only an approximation and is dependent on the map's projection that can add some distortion, as well as the system's reported DPI setting which doesn't necessarily match the actual DPI of the screen.

      The default value of this property is NaN which makes the layer unbounded by any scale.

      Returns:
      the maximum scale level this graphics overlay will be displayed.
      Since:
      100.0.0
      See Also:

    • setMaxScale

      public void setMaxScale(double maxScale)
      Sets the maximum scale at which to display the graphics overlay. A small number allows the map to display the layer when zooming further in.

      This controls the maximum scale at which the graphics overlay is displayed. If the current map scale is smaller than the maximum scale, then this graphics overlay will not be displayed.

      A scale is usually referred to as 1:X, where X is the scale specified here. This value is the relative scale to the real world, where one inch on the screen is X inches in the real world. Note that this is only an approximation and is dependent on the map's projection that can add some distortion, as well as the system's reported DPI setting which doesn't necessarily match the actual DPI of the screen.

      Parameters:
      maxScale - the new maximum scale
      Since:
      100.0.0

    • getRenderer

      public Renderer getRenderer()
      Gets the renderer for the graphics overlay. If any graphic in the graphics overlay has a Symbol set, that will take precedence over this renderer.
      Returns:
      the renderer
      Since:
      100.0.0

    • setRenderer

      public void setRenderer(Renderer renderer)
      Sets a renderer to the graphics overlay. If any graphic in the graphics overlay has a Symbol set, that will take precedence over this renderer.
      Parameters:
      renderer - the new renderer
      Since:
      100.0.0

    • getGraphics

      public ListenableList<Graphic> getGraphics()
      Gets a modifiable list of the graphics in this overlay. Add or remove graphics from this list to modify what is displayed. The list returned can be empty but not null. You can add listeners to this list to monitor changes to the list.

      If Z-index for graphics is not set, they will usually render in the order in which they were added to the graphics overlay, the first added is rendered first and subsequent ones on top. In rare cases, the rendering algorithm may change the display order to provide more efficient rendering. If ordering is important, set the Z-index explicitly on graphics by calling Graphic.setZIndex(int). You can also place graphics of the same geometry type in their own graphics overlay and manage the order of the overlays in the view.

      Returns:
      a modifiable list of graphics in this graphics overlay
      Since:
      100.0.0

    • getSelectedGraphics

      public List<Graphic> getSelectedGraphics()
      Gets a read only list of the currently selected graphics in this overlay. The list returned can be empty but not null. The list is a snapshot of the current selected graphics. To change the selection, you call methods on Graphic; a Graphic comes with different methods that alter the list of currently selected Graphics.
      Returns:
      a list of selected graphics
      Since:
      100.0.0
      See Also:

    • clearSelection

      public void clearSelection()
      Deselects all graphics in the graphics overlay.
      Since:
      100.0.0

    • getExtent

      public Envelope getExtent()
      Calculates and returns the extent of the getGraphics() collection.

      The extent's SpatialReference is that of the GeoView that contains the overlay. If the overlay is not in a view, returns null. If the overlay is in a view but that view does not yet have a spatial reference, returns null. If the overlay is in a view with a spatial reference, but has no graphics, then an empty envelope will be returned.

      Returns:
      the envelope. Can be null.
      Since:
      100.0.0

    • featureReductionProperty

      public ObjectProperty<FeatureReduction> featureReductionProperty()
      Defines properties for dynamically aggregating and summarizing groups of graphics as the map scale and visible extent change.

      FeatureReduction is only supported for point graphics in dynamic rendering mode (GraphicsOverlay.RenderingMode.DYNAMIC) in 2D. FeatureReduction is ignored and will result in the original point graphics being rendered for a GraphicsOverlay that:

      1. Uses static rendering mode.
      2. Is added to a SceneView.
      3. Uses an unsupported renderer for the AggregationFeatureReduction.rendererProperty(). See AggregationFeatureReduction.rendererProperty() for more info.

      If this property is explicitly set to null, FeatureReduction is removed from the GraphicsOverlay.

      Returns:
      the featureReduction property
      Since:
      200.4.0
      See Also:

    • getFeatureReduction

      public FeatureReduction getFeatureReduction()
      Gets the value of the featureReduction property.
      Property description:
      Defines properties for dynamically aggregating and summarizing groups of graphics as the map scale and visible extent change.

      FeatureReduction is only supported for point graphics in dynamic rendering mode (GraphicsOverlay.RenderingMode.DYNAMIC) in 2D. FeatureReduction is ignored and will result in the original point graphics being rendered for a GraphicsOverlay that:

      1. Uses static rendering mode.
      2. Is added to a SceneView.
      3. Uses an unsupported renderer for the AggregationFeatureReduction.rendererProperty(). See AggregationFeatureReduction.rendererProperty() for more info.

      If this property is explicitly set to null, FeatureReduction is removed from the GraphicsOverlay.

      Returns:
      the value of the featureReduction property
      Since:
      200.4.0
      See Also:

    • setFeatureReduction

      public void setFeatureReduction(FeatureReduction featureReduction)
      Sets the value of the featureReduction property.
      Property description:
      Defines properties for dynamically aggregating and summarizing groups of graphics as the map scale and visible extent change.

      FeatureReduction is only supported for point graphics in dynamic rendering mode (GraphicsOverlay.RenderingMode.DYNAMIC) in 2D. FeatureReduction is ignored and will result in the original point graphics being rendered for a GraphicsOverlay that:

      1. Uses static rendering mode.
      2. Is added to a SceneView.
      3. Uses an unsupported renderer for the AggregationFeatureReduction.rendererProperty(). See AggregationFeatureReduction.rendererProperty() for more info.

      If this property is explicitly set to null, FeatureReduction is removed from the GraphicsOverlay.

      Parameters:
      featureReduction - the value for the featureReduction property
      Since:
      200.4.0
      See Also:

    • getSceneProperties

      public LayerSceneProperties getSceneProperties()
      Gets a layer scene properties object for the graphics overlay. The object can be used to make changes to how graphics are displayed in a SceneView.

      Use scene properties to control how graphics are displayed in a SceneView. For example, you can adjust the altitude offset or the surface placement in the SceneView.

      None of these settings are applied if the graphics overlay is added to a MapView.

      Returns:
      a scene properties object for the graphics overlay
      Since:
      100.0.0

    • setLabelsEnabled

      public void setLabelsEnabled(boolean enabled)
      Sets whether labels are displayed for graphics in this graphics overlay.
      Parameters:
      enabled - true to enable, false to disable labels
      Since:
      100.1.0

    • isLabelsEnabled

      public boolean isLabelsEnabled()
      Indicates if labels are displayed for graphics in this graphics overlay.
      Returns:
      true if labels are enabled, false if not
      Since:
      100.1.0

    • getLabelDefinitions

      public List<LabelDefinition> getLabelDefinitions()
      Gets a modifiable list of LabelDefinition objects for this graphics overlay.

      A LabelDefinition defines the text, appearance, and position of labels for the graphics. You can manage graphic labeling by defining new LabelDefinition objects and adding or removing them from this collection.

      Returns:
      a modifiable list of LabelDefinition objects for this graphics overlay
      Since:
      100.1.0

    • isScaleSymbols

      public boolean isScaleSymbols()
      Gets whether this graphics overlay's symbols and labels honor the map reference scale when displayed in a map view.

      If the map has a positive reference scale, and the overlay honors it, then symbols and labels will be drawn at their specified size when the viewing scale is the same as the reference scale, and will grow or shrink as the view zooms in or out, to keep the symbol a fixed size on the map. If the map has no reference scale, the reference scale is zero, or the overlay's scaleSymbols property is false, then the symbols and labels will be drawn at their fixed screen size.

      ScaleSymbols can only be used when displaying the overlay in a MapView. The symbols and labels will be displayed at fixed screen size in a SceneView.

      The default value is false.

      Returns:
      true if the symbols and labels honor the map reference scale, false otherwise
      Since:
      100.7.0

    • setScaleSymbols

      public void setScaleSymbols(boolean scaleSymbols)
      Sets whether this graphics overlay's symbols and labels honor the map reference scale when displayed in a map view.

      If the map has a positive reference scale, and the overlay honors it, then symbols and labels will be drawn at their specified size when the viewing scale is the same as the reference scale, and will grow or shrink as the view zooms in or out, to keep the symbol a fixed size on the map. If the map has no reference scale, the reference scale is zero, or the overlay's scaleSymbols property is false, then the symbols and labels will be drawn at their fixed screen size.

      ScaleSymbols can only be used when displaying the overlay in a MapView. The symbols and labels will be displayed at fixed screen size in a SceneView.

      Parameters:
      scaleSymbols - true to make the symbols and labels honor the map reference scale, false otherwise
      Since:
      100.7.0

    • selectGraphics

      public void selectGraphics(Iterable<Graphic> graphics)
      Selects the specified graphics. Any graphics that are not in this graphics overlay will be ignored.
      Parameters:
      graphics - the graphics to be selected
      Throws:
      IllegalArgumentException - if graphics is null
      Since:
      100.5.0

    • unselectGraphics

      public void unselectGraphics(Iterable<Graphic> graphics)
      Unselects the specified graphics. Any graphics that are not in this graphics overlay will be ignored.
      Parameters:
      graphics - the graphics to be unselected
      Throws:
      IllegalArgumentException - if graphics is null
      Since:
      100.5.0