Package com.esri.arcgisruntime.mapping.view

Class GraphicsOverlay

  • All Implemented Interfaces:
    PopupSource
    public final class GraphicsOverlay
extends java.lang.Object
implements PopupSource
    A GraphicsOverlay manages the display of one or more Graphics on a GeoView.

    Graphics are used to represent temporary data, such as the results of a query or an analysis, or to highlight existing content in a map. They are often used to display data that changes location regularly, because they are held in memory instead of being persisted to the map.

    A graphics overlay may contain graphics that have different types of geometry, unlike a feature layer which contains only a single geometry type. Additionally, each graphic in an overlay can have a different attribute schema. A Renderer may be associated with a graphics overlay, which will manage appearance of all the graphics contained in that graphics overlay (providing that the graphics are of a single geometry dimension and have a common attribute). If both the Graphic.getSymbol() and the getRenderer() are set, the graphic symbol will take precedence. You can change the overall opacity of a graphics overlay, and also change its visibility.

    Graphics overlays display on top of all other data in a MapView or SceneView. A graphic's z-index can be used to define its draw order in the collection and is mostly relevant for display in a two dimensional map. For dynamic 3D rendering (in a scene), graphic display order is determined by the distance to the camera rather than by Z-index. Z-index is considered, however, when using static rendering in a scene (draping graphics on the surface, in other words).

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

    The GeoView.getGraphicsOverlays() method returns a modifiable ListenableList that can contain 0 or more graphics overlays. Add a graphics overlay to a GeoView by calling any of the add methods from the returned ListenableList.

    You can add a listener to be notified when graphics are added to or removed from an overlay. Graphics overlays are always displayed on top of the layers in a GeoView (including reference layers), except on Android where it will be below the graphics used by LocationDisplay.

    The graphics at a screen location can be identified by using the methods on GeoView, as shown in this example: 

     // get the point where the user clicked
 ...
 // create a graphics overlay
 GraphicsOverlay graphicsOverlay = new GraphicsOverlay();
 // identify graphics on the graphics overlay
 ListenableFuture<IdentifyGraphicsOverlayResult> identifyGraphics = mapView.identifyGraphicsOverlayAsync(graphicsOverlay, pointClicked, 10, 1);

    A RenderingMode can also be selected when using a GraphicsOverlay:

    • Dynamic, Graphics are updated immediately as GeoView is panned or zoomed.
    • Static, Graphics are updated once the pan or zoom operation on the GeoView is finished.
    Since:
    100.0.0
    See Also:
    Graphic, GeoView.getGraphicsOverlays()

    • Constructor Detail

      • 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:
        java.lang.IllegalArgumentException - if parameter is null
        Since:
        100.0.0

    • Method Detail

      • getRenderingMode

        public GraphicsOverlay.RenderingMode getRenderingMode()
        Gets the rendering mode used to render this overlay.
        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 - a value between 0 to 1.0 with 1.0 being opaque and 0 being transparent.
        Returns:
        the opacity
        Since:
        100.0.0

      • setOpacity

        public void setOpacity​(float opacity)
        Sets the opacity - a value between 0 to 1.0 with 1.0 being solid or opaque and 0 being transparent.
        Parameters:
        opacity - the new opacity
        Throws:
        java.lang.IllegalArgumentException - if opacity is less than 0 or greater than 1.
        Since:
        100.0.0

      • getMinScale

        public double getMinScale()
        Gets the minimum scale for the graphics overlay. 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.
        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 for the graphics overlay. 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. All of the connected GeoViews will be updated.
        Parameters:
        minScale - the new minimum scale
        Since:
        100.0.0

      • getMaxScale

        public double getMaxScale()
        Gets the maximum scale for the graphics overlay. 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.
        Returns:
        the maximum scale level this graphics overlay will be displayed.
        Since:
        100.0.0
        See Also:
        setMaxScale(double)

      • setMaxScale

        public void setMaxScale​(double maxScale)
        Sets the maximum scale for the graphics overlay. 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.
        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 list of the graphics
        Since:
        100.0.0

      • getSelectedGraphics

        public java.util.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(), Graphic

      • clearSelection

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

      • getSelectionColor

        @Deprecated
public int getSelectionColor()
        Deprecated.
        As of 100.4.0, use SelectionProperties.getColor() from your GeoView.
        Gets the selection color used to highlight selected graphics. The default color is cyan.
        Returns:
        an integer representing the selection color as 0xAARRGGBB
        Since:
        100.0.0

      • setSelectionColor

        @Deprecated
public void setSelectionColor​(int selectionColor)
        Deprecated.
        As of 100.4.0, use SelectionProperties.setColor(int) from your GeoView.
        Sets the selection color used to highlight selected graphics.
        Parameters:
        selectionColor - an integer representing the selection color as 0xAARRGGBB
        Since:
        100.0.0

      • getExtent

        public Envelope getExtent()
        Calculates and returns the extent of the graphics currently contained in this overlay. The extent's spatial reference is that of the view that contains the overlay. If the overlay is not in a view, null is returned. If the overlay is in a view but that view does not yet have a spatial reference, null is returned. If the overlay is in a view with a spatial reference, but contains no graphics, then an empty envelope will be returned.
        Returns:
        the envelope. Can be null.
        Since:
        100.0.0

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

        None of these settings will take effect if this applies to a MapView.

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

      • setLabelsEnabled

        public void setLabelsEnabled​(boolean enabled)
        Enables or disables the labeling for the graphics overlay.
        Parameters:
        enabled - true to enable, false to disable labels
        Since:
        100.1.0

      • isLabelsEnabled

        public boolean isLabelsEnabled()
        Gets whether labels are enabled.
        Returns:
        true if labels are enabled, false if not
        Since:
        100.1.0

      • getLabelDefinitions

        public java.util.List<LabelDefinition> getLabelDefinitions()
        Gets a modifiable list of label definitions of this graphics overlay.
        Returns:
        a modifiable list of label definitions
        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. The default value is false.

        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.

        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.

        The default value is false.

        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​(java.lang.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:
        java.lang.IllegalArgumentException - if graphics is null
        Since:
        100.5.0

      • unselectGraphics

        public void unselectGraphics​(java.lang.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:
        java.lang.IllegalArgumentException - if graphics is null
        Since:
        100.5.0