Package com.esri.arcgisruntime.mapping.view

Class SketchEditor

  • public final class SketchEditor
extends Object
    Represents a sketch editor that allows users to interactively sketch geometries on the map view. Different geometry types can be sketched from scratch such as point, multipoint, polyline, or polygon by starting the SketchEditor with the corresponding SketchCreationMode, see start(SketchCreationMode). An existing geometry can be modified using start(Geometry), start(Geometry, SketchCreationMode) or replaceGeometry(Geometry).

    During a sketch session, a geometry can be modified by moving or deleting the vertices or parts interactively. A sketch editor must be set on the map view MapView.setSketchEditor(SketchEditor) before calling the start methods, otherwise a runtime exception IllegalStateException will be thrown. The stop() method needs to be called to finish the current sketch editing session.

    Interactions:

    • Using Mouse:
      • Left-click - on a vertex to select it; on geometry's outline to select geometry; otherwise, to draw
      • Left-press and drag - on a vertex to move a vertex; on geometry's outline to move geometry
      • Right-click - to show a context menu with option to clear the vertex or geometry
    • Using Touch:
      • Touch - on a vertex or outline to show a context menu with option to clear the vertex or geometry; otherwise, to draw
      • Press for 500ms and drag - on a vertex to move a vertex; on geometry's outline to move geometry
    Since:
    100.1.0
    See Also:
    MapView.setSketchEditor(SketchEditor)

    • Constructor Detail

      • SketchEditor

        public SketchEditor()
        Constructs a default SketchEditor.
        Since:
        100.1.0

    • Method Detail

      • start

        public void start​(Geometry geometry,
                  SketchCreationMode creationMode)
        Starts a sketch editing session based on the provided geometry and creation mode.
        Parameters:
        geometry - geometry to start the sketch with
        creationMode - represents the type of sketch. A default creation mode is used if null
        Throws:
        IllegalArgumentException - if the geometry is null
        IllegalArgumentException - if the geometry type is incompatible with the sketch creation mode
        IllegalStateException - if the method is called before the SketchEditor is set on a map view
        IllegalStateException - if the map is null or not loaded
        Since:
        100.1.0

      • start

        public void start​(SketchCreationMode creationMode,
                  SketchEditConfiguration editConfiguration)
        Starts a new editing session for given sketch creation mode and edit configuration.
        Parameters:
        creationMode - representing the type of geometry that users are going to sketch
        editConfiguration - the SketchEditConfiguration
        Throws:
        IllegalArgumentException - if creationMode or editConfiguration is null
        IllegalStateException - if the method is called before the SketchEditor is set on a map view
        IllegalStateException - if the map is null or not loaded
        Since:
        100.3.0

      • start

        public void start​(Geometry geometry,
                  SketchCreationMode creationMode,
                  SketchEditConfiguration editConfiguration)
        Starts a sketch editing session based on the provided geometry, creation mode and edit configuration. The sketch editor will respond to user interactions with the map view to perform a sketch.
        Parameters:
        geometry - the geometry to start the sketch with
        creationMode - representing the type of geometry that users are going to sketch, the type must be compatible with the geometry being provided. A default creation mode is used if it is null
        editConfiguration - the SketchEditConfiguration
        Throws:
        IllegalArgumentException - if geometry or editConfiguration is null
        IllegalArgumentException - if the geometry type is incompatible with the sketch creation mode
        IllegalStateException - if the method is called before the SketchEditor is set on a map view
        IllegalStateException - if the map is null or not loaded
        Since:
        100.3.0

      • stop

        public void stop()
        Stops sketching. The sketch geometry can be obtained using the listener SketchGeometryChangedListener.
        Since:
        100.1.0

      • clearGeometry

        public void clearGeometry()
        Clears the current sketch geometry.
        Since:
        100.1.0

      • replaceGeometry

        public void replaceGeometry​(Geometry geometry)
        Replaces the current sketch geometry with the given geometry if the sketch editor has started. The type of geometries must match.
        Parameters:
        geometry - the new geometry to be used
        Throws:
        IllegalArgumentException - if the geometry is null or if the geometry type is incompatible with current creation mode
        Since:
        100.1.0

      • isSketchValid

        public boolean isSketchValid()
        A lightweight check to see if the current Geometry of this SketchEditor can produce a valid geometry. Returns true if:
        • It is a Point and contains non-NaN x and y coordinates.
        • It is a Multipoint and contains at least one valid vertex.
        • It is a Polyline with at least 2 vertices in each part, and at least one part.
        • It is a Polygon with at least 3 vertices in each part, and at least one part.
        • It is an Envelope and contains non-NaN xmin, ymin, xmax, and ymax coordinates.

        Prior to v100.8, only one part of a multipart polygon or polyline was required to have the minimum number (2 for a polyline, 3 for a polygon) of vertices.

        Returns:
        true if the current sketch geometry is valid, false otherwise
        Since:
        100.1.0

      • isVisible

        public boolean isVisible()
        Gets the visibility of sketch components.
        Returns:
        true if the sketch components are visible, false otherwise
        Since:
        100.1.0

      • setVisible

        public void setVisible​(boolean visible)
        Sets the visibility of sketch components.
        Parameters:
        visible - true to set graphics visible on the sketch editor, false to set invisible
        Since:
        100.1.0

      • setOpacity

        public void setOpacity​(float opacity)
        Sets the opacity of sketch components.
        Parameters:
        opacity - the value to set the opacity of sketch components, it should be a value between 0 (fully transparent) and 1 (fully opaque)
        Throws:
        IllegalArgumentException - if the opacity value is out of range from 0 to 1
        Since:
        100.1.0

      • getOpacity

        public float getOpacity()
        Gets the opacity of sketch components.
        Returns:
        the opacity of sketch components, it should be a value between 0 (fully transparent) and 1 (fully opaque)
        Since:
        100.1.0

      • getSketchCreationMode

        public SketchCreationMode getSketchCreationMode()
        Gets the sketch creation mode.
        Returns:
        the current sketch creation mode
        Since:
        100.1.0

      • setSketchStyle

        public void setSketchStyle​(SketchStyle sketchStyle)
        Sets the sketch style.
        Parameters:
        sketchStyle - the sketch style
        Throws:
        IllegalArgumentException - if the sketchStyle is null
        Since:
        100.1.0

      • getSketchStyle

        public SketchStyle getSketchStyle()
        Gets the current sketch style. If not set, a default is used. To apply the changes of the sketch style on the sketching geometry, the setSketchStyle(SketchStyle) method needs to be called, e.g. 
         SketchStyle style = sketchEditor.getSketchStyle();
   style.getLineSymbol().setColor(0xFF00FF00);
   style.getLineSymbol().setWidth(2.0f);
   style.setVertexSymbol(new SimpleMarkerSymbol(SimpleMarkerSymbol.Style.CIRCLE, 0xFFFF0000, 10));
   sketchEditor.setSketchStyle(style);
        Returns:
        the current sketch style
        Since:
        100.1.0

      • getSketchEditConfiguration

        public SketchEditConfiguration getSketchEditConfiguration()
        Gets the sketch edit configuration.
        Returns:
        the SketchEditConfiguration
        Since:
        100.3.0

      • addGeometryChangedListener

        public void addGeometryChangedListener​(SketchGeometryChangedListener listener)
        Adds a geometry changed listener.

        This listener will be invoked on the UI thread if it is added from the UI thread, otherwise it is not guaranteed on which thread the listener is invoked.

        Parameters:
        listener - the geometry change listener to add
        Throws:
        IllegalArgumentException - if the listener is null
        Since:
        100.1.0

      • removeGeometryChangedListener

        public boolean removeGeometryChangedListener​(SketchGeometryChangedListener listener)
        Removes a geometry changed listener.
        Parameters:
        listener - the geometry changed listener to remove
        Returns:
        true if the geometry changes listener was removed, false otherwise
        Since:
        100.1.0

      • addSelectedVertexChangedListener

        public void addSelectedVertexChangedListener​(SelectedVertexChangedListener selectedVertexChangedListener)
        Adds a selected vertex changed listener to the SketchEditor. A selected vertex changed listener will be called when a new vertex is selected.
        Parameters:
        selectedVertexChangedListener - the listener to add
        Throws:
        IllegalArgumentException - if selectedVertexChangedListener is null
        Since:
        100.3.0
        See Also:
        setSelectedVertex(SketchVertex)

      • removeSelectedVertexChangedListener

        public boolean removeSelectedVertexChangedListener​(SelectedVertexChangedListener selectedVertexChangedListener)
        Removes the specified selected vertex changed listener from the SketchEditor
        Parameters:
        selectedVertexChangedListener - the listener to remove
        Returns:
        true if selectedVertexChangedListener is removed successfully, false otherwise
        Since:
        100.3.0

      • getGeometry

        public Geometry getGeometry()
        Gets the current sketch geometry.

        Use SketchGeometryChangedListener to listen to the changes of the sketch geometry.

        Returns:
        the current geometry, or null if the sketch editor is not started
        Since:
        100.1.0

      • undo

        public void undo()
        Undoes the last action to the sketch geometry.
        Since:
        100.2.0

      • canUndo

        public boolean canUndo()
        Gets whether there are actions to undo.
        Returns:
        true if there are actions to undo, otherwise false
        Since:
        100.2.0

      • redo

        public void redo()
        Redoes the last action to the sketch geometry.
        Since:
        100.2.0

      • canRedo

        public boolean canRedo()
        Gets whether there are actions to redo.
        Returns:
        true if there are actions to redo, otherwise false
        Since:
        100.2.0

      • getSelectedVertex

        public SketchVertex getSelectedVertex()
        Gets the selected sketch vertex.
        Returns:
        the selected SketchVertex, or null if no sketch vertex is selected.
        Since:
        100.3.0
        See Also:
        setSelectedVertex(SketchVertex)

      • setSelectedVertex

        public boolean setSelectedVertex​(SketchVertex sketchVertex)
        Sets the SketchVertex to be selected.
        Parameters:
        sketchVertex - the SketchVertex to be selected. If sketchVertex is null, the currently selected vertex will be unselected.
        Returns:
        true if sketchVertex is valid and selected successfully, false otherwise
        Since:
        100.3.0

      • removeSelectedVertex

        public boolean removeSelectedVertex()
        Removes the selected vertex.
        Returns:
        true if the selected vertex is removed successfully, false otherwise
        Since:
        100.3.0

      • insertVertexAfterSelectedVertex

        public boolean insertVertexAfterSelectedVertex​(Point point)
        Inserts a new vertex after the selected vertex. If the sketch geometry is empty, a new vertex is to be added and selected. If the sketch geometry is a point, this method will move the existing selected point to the specified location and selects it.
        Parameters:
        point - the new point to be inserted
        Returns:
        true if point is inserted after the selected vertex successfully, false otherwise
        Throws:
        IllegalArgumentException - if point is null
        Since:
        100.3.0

      • moveSelectedVertex

        public boolean moveSelectedVertex​(Point point)
        Moves the selected vertex to a new position.
        Parameters:
        point - the new point to which to move the selected vertex
        Returns:
        true if the selected vertex is moved to the new position successfully, false otherwise
        Throws:
        IllegalArgumentException - if point is null
        Since:
        100.3.0