Class SketchEditor
- java.lang.Object
-
- com.esri.arcgisruntime.mapping.view.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, seestart(SketchCreationMode)
. An existing geometry can be modified usingstart(Geometry)
,start(Geometry, SketchCreationMode)
orreplaceGeometry(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 exceptionIllegalStateException
will be thrown. Thestop()
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)
-
Using Mouse:
-
-
Constructor Summary
Constructors Constructor Description SketchEditor()
Constructs a default SketchEditor.
-
Method Summary
All Methods Instance Methods Concrete Methods Modifier and Type Method Description void
addGeometryChangedListener(SketchGeometryChangedListener listener)
Adds a geometry changed listener.void
addSelectedVertexChangedListener(SelectedVertexChangedListener selectedVertexChangedListener)
Adds a selected vertex changed listener to the SketchEditor.boolean
canRedo()
Gets whether there are actions to redo.boolean
canUndo()
Gets whether there are actions to undo.void
clearGeometry()
Clears the current sketch geometry.Geometry
getGeometry()
Gets the current sketch geometry.float
getOpacity()
Gets the opacity of sketch components.SketchVertex
getSelectedVertex()
Gets the selected sketch vertex.SketchCreationMode
getSketchCreationMode()
Gets the sketch creation mode.SketchEditConfiguration
getSketchEditConfiguration()
Gets the sketch edit configuration.SketchStyle
getSketchStyle()
Gets the current sketch style.boolean
insertVertexAfterSelectedVertex(Point point)
Inserts a new vertex after the selected vertex.boolean
isSketchValid()
A lightweight check to see if the currentGeometry
of this SketchEditor can produce a valid geometry.boolean
isVisible()
Gets the visibility of sketch components.boolean
moveSelectedVertex(Point point)
Moves the selected vertex to a new position.void
redo()
Redoes the last action to the sketch geometry.boolean
removeGeometryChangedListener(SketchGeometryChangedListener listener)
Removes a geometry changed listener.boolean
removeSelectedVertex()
Removes the selected vertex.boolean
removeSelectedVertexChangedListener(SelectedVertexChangedListener selectedVertexChangedListener)
Removes the specified selected vertex changed listener from the SketchEditorvoid
replaceGeometry(Geometry geometry)
Replaces the current sketch geometry with the given geometry if the sketch editor has started.void
setOpacity(float opacity)
Sets the opacity of sketch components.boolean
setSelectedVertex(SketchVertex sketchVertex)
Sets the SketchVertex to be selected.void
setSketchStyle(SketchStyle sketchStyle)
Sets the sketch style.void
setVisible(boolean visible)
Sets the visibility of sketch components.void
start(Geometry geometry)
Starts a sketch editing session based on the provided geometry.void
start(Geometry geometry, SketchCreationMode creationMode)
Starts a sketch editing session based on the provided geometry and creation mode.void
start(Geometry geometry, SketchCreationMode creationMode, SketchEditConfiguration editConfiguration)
Starts a sketch editing session based on the provided geometry, creation mode and edit configuration.void
start(SketchCreationMode creationMode)
Starts a new editing session for given sketch creation mode.void
start(SketchCreationMode creationMode, SketchEditConfiguration editConfiguration)
Starts a new editing session for given sketch creation mode and edit configuration.void
stop()
Stops sketching.void
undo()
Undoes the last action to the sketch geometry.
-
-
-
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 withcreationMode
- represents the type of sketch. A default creation mode is used if null- Throws:
IllegalArgumentException
- if the geometry is nullIllegalArgumentException
- if the geometry type is incompatible with the sketch creation modeIllegalStateException
- if the method is called before the SketchEditor is set on a map viewIllegalStateException
- if the map is null or not loaded- Since:
- 100.1.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.To set a freehand editing mode, use
start(Geometry, SketchCreationMode)
, with eitherSketchCreationMode.FREEHAND_LINE
orSketchCreationMode.FREEHAND_POLYGON
.- Parameters:
geometry
- the geometry to start the sketch with- Throws:
IllegalArgumentException
- if the geometry is nullIllegalStateException
- if the method is called before the SketchEditor is set on a map viewIllegalStateException
- if the map is null or not loaded- Since:
- 100.1.0
-
start
public void start(SketchCreationMode creationMode)
Starts a new editing session for given sketch creation mode.- Parameters:
creationMode
- represents the type of sketch- Throws:
IllegalArgumentException
- if the creationMode is nullIllegalStateException
- if the method is called before the SketchEditor is set on a map viewIllegalStateException
- 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 sketcheditConfiguration
- the SketchEditConfiguration- Throws:
IllegalArgumentException
- if creationMode or editConfiguration is nullIllegalStateException
- if the method is called before the SketchEditor is set on a map viewIllegalStateException
- 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 withcreationMode
- 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 nulleditConfiguration
- the SketchEditConfiguration- Throws:
IllegalArgumentException
- if geometry or editConfiguration is nullIllegalArgumentException
- if the geometry type is incompatible with the sketch creation modeIllegalStateException
- if the method is called before the SketchEditor is set on a map viewIllegalStateException
- 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 listenerSketchGeometryChangedListener
.- 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 currentGeometry
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
- It is a
-
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, thesetSketchStyle(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
-
-