Package com.esri.arcgisruntime.mapping.view

Class SketchEditor

  • public final class SketchEditor
extends java.lang.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.

    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​(SketchCreationMode creationMode)
        Starts a new editing session for given sketch creation mode.

        Note - this method needs to be called on a looper thread, as it schedules runnables to be executed at some point in the future as a result of MapView interactions, see android.os.Looper.

        Parameters:
        creationMode - representing the type of geometry that users are going to sketch
        Throws:
        java.lang.IllegalArgumentException - if the creationMode is null
        java.lang.IllegalStateException - if the method is called before the SketchEditor is set on a map view
        java.lang.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.

        Note - this method needs to be called on a looper thread, as it schedules runnables to be executed at some point in the future as a result of MapView interactions, see android.os.Looper.

        Parameters:
        creationMode - representing the type of geometry that users are going to sketch
        editConfiguration - the SketchEditConfiguration
        Throws:
        java.lang.IllegalArgumentException - if creationMode or editConfiguration is null
        java.lang.IllegalStateException - if the method is called before the SketchEditor is set on a map view
        java.lang.IllegalStateException - if the map is null or not loaded
        Since:
        100.3.0

      • start

        public void start​(Geometry geometry)
        Starts a sketch editing session based on the provided geometry. A non-freehand sketch creation mode and a default edit configuration is created and used based on the geometry type. The sketch editor will respond to user interactions with the map view to perform a sketch.

        If you like to set the geometry in freehand editing mode, you can use the start(Geometry, SketchCreationMode) method.

        Note - this method needs to be called on a looper thread, as it schedules runnables to be executed at some point in the future as a result of MapView interactions, see android.os.Looper.

        Parameters:
        geometry - the geometry to start the sketch with
        Throws:
        java.lang.IllegalArgumentException - if the geometry is null
        java.lang.IllegalStateException - if the method is called before the SketchEditor is set on a map view
        java.lang.IllegalStateException - if the map is null or not loaded
        Since:
        100.1.0

      • start

        public void start​(Geometry geometry,
                  SketchCreationMode creationMode)
        Starts a sketch editing session based on the provided geometry and creation mode. The sketch editor will respond to user interactions with the map view to perform a sketch.

        Note - this method needs to be called on a looper thread, as it schedules runnables to be executed at some point in the future as a result of MapView interactions, see android.os.Looper.

        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
        Throws:
        java.lang.IllegalArgumentException - if the geometry is null
        java.lang.IllegalArgumentException - if the geometry type is incompatible with the sketch creation mode
        java.lang.IllegalStateException - if the method is called before the SketchEditor is set on a map view
        java.lang.IllegalStateException - if the map is null or not loaded
        Since:
        100.1.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.

        Note - this method needs to be called on a looper thread, as it schedules runnables to be executed at some point in the future as a result of MapView interactions, see android.os.Looper.

        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:
        java.lang.IllegalArgumentException - if geometry or editConfiguration is null
        java.lang.IllegalArgumentException - if the geometry type is incompatible with the sketch creation mode
        java.lang.IllegalStateException - if the method is called before the SketchEditor is set on a map view
        java.lang.IllegalStateException - if the map is null or not loaded
        Since:
        100.3.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 is started. These geometries must be matching in type.
        Parameters:
        geometry - the new geometry to be used
        Throws:
        java.lang.IllegalArgumentException - if the geometry is null or geometry type is incompatible with current creation mode
        java.lang.IllegalStateException - if the method is called before the SketchEditor is set on a map view and started
        Since:
        100.1.0

      • isSketchValid

        public boolean isSketchValid()
        Indicates if the sketch geometry is valid. 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 a 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

      • stop

        public void stop()
        Stops the sketching session if it is started. The final sketch geometry can be obtained by getGeometry() before calling stop.
        Since:
        100.1.0

      • isVisible

        public boolean isVisible()
        Gets the visibility of the sketch geometry and associated graphics displayed by the SketchEditor such as vertices.
        Returns:
        true if the sketch geometry and associated graphics are visible, false otherwise
        Since:
        100.1.0

      • setVisible

        public void setVisible​(boolean visible)
        Sets the visibility of the sketch geometry and associated graphics displayed by the SketchEditor such as vertices.
        Parameters:
        visible - true to make the sketch geometry and associated graphics visible, false to make invisible
        Since:
        100.1.0

      • setOpacity

        public void setOpacity​(float opacity)
        Sets the opacity of the sketch geometry.
        Parameters:
        opacity - the opacity of the sketch geometry, it should be a value between 0 (fully transparent) and 1 (fully opaque)
        Throws:
        java.lang.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 the sketch geometry.
        Returns:
        the opacity of the sketch geometry, it should be a value between 0 (fully transparent) and 1 (fully opaque)
        Since:
        100.1.0

      • getSketchCreationMode

        public SketchCreationMode getSketchCreationMode()
        Gets the SketchCreationMode specifying what type of geometry will be sketched.
        Returns:
        the current sketch creation mode
        Since:
        100.1.0

      • setSketchStyle

        public void setSketchStyle​(SketchStyle sketchStyle)
        Applies the sketch style to the sketch editor.
        Parameters:
        sketchStyle - a SketchStyle object
        Throws:
        java.lang.IllegalArgumentException - if the sketchStyle is null
        Since:
        100.1.0

      • getSketchStyle

        public SketchStyle getSketchStyle()
        Gets the current SketchStyle. 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(Color.GREEN);
   style.getLineSymbol().setWidth(2.0f);
   style.setVertexSymbol(new SimpleMarkerSymbol(SimpleMarkerSymbol.Style.CIRCLE, Color.RED, 10));
   sketchEditor.setSketchStyle(style);
        Returns:
        a SketchStyle object
        Since:
        100.1.0
        See Also:
        SketchStyle

      • getSketchEditConfiguration

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

      • addGeometryChangedListener

        public void addGeometryChangedListener​(SketchGeometryChangedListener listener)
        Adds the geometry changed listener. A geometry changed listener will be invoked whenever a sketch geometry is updated.
        Parameters:
        listener - the geometry changed listener
        Throws:
        java.lang.IllegalArgumentException - if the listener is null
        Since:
        100.1.0

      • removeGeometryChangedListener

        public boolean removeGeometryChangedListener​(SketchGeometryChangedListener listener)
        Removes the geometry changed listener.
        Parameters:
        listener - the geometry changed listener
        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:
        java.lang.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

      • 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

      • getGeometry

        public Geometry getGeometry()
        Gets the current sketch geometry.

        Use SketchGeometryChangedListener to listen to changes of geometry as the user sketches interactively on the map view.

        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

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