Geometry
Allows you to create new geometries, and change existing geometries, by interacting with a MapView. To use a GeometryEditor:
Set the MapView.geometryEditor property.
Call one of the start methods.
To interactively create new geometries from scratch, call GeometryEditor.start(GeometryType) passing in a GeometryType to determine the type of geometry created.
For geometry editing workflows, pass an existing Geometry into GeometryEditor.start(Geometry).
You can then edit the geometry directly on the map view using mouse or touch gestures.
The GeometryEditor.tool determines how you draw on the map to define the new geometry, for example by adding individual vertices or with a freehand gesture. The default tool is VertexTool.
If you passed in an initial geometry, it is displayed in the view, and you can interact with the geometry to make changes.
Call GeometryEditor.stop() to return the geometry and prevent the geometry editor from processing any more interactions.
Geometries are immutable, therefore a new Geometry object reflecting the updates is returned from GeometryEditor.geometry and GeometryEditor.stop() each time.
When started (GeometryEditor.isStarted is true), you can interact with the different GeometryEditorElement objects that compose the representation of the GeometryEditor.geometry in the map view. Depending on what is selected, different types of GeometryEditorElement are returned from GeometryEditor.selectedElement.
The type of the current GeometryEditor.tool determines how you create and edit geometries, with the current InteractionConfiguration or ReticleInteractionConfiguration allowing you to enable or disable different interactions and capabilities of the tool.
The default VertexTool allows you to create and edit geometries by interacting with individual vertices. You can tap to select the different elements and drag to move them, and also tap multiple times on an element to select the different types of GeometryEditorElement representing vertices, parts, or the entire geometry. You can rotate and scale the selected element (if applicable to the selected element type), and can also create new parts in a multipart geometry (if enabled in the InteractionConfiguration).
The FreehandTool is ideal for creating new polygon or polyline geometries using a single freehand drag gesture. It also allows multiple taps to cycle the selected element type.
The ShapeTool is ideal for creating new polygon or polyline geometries with a geometric shape by using a single drag interaction. It also allows multiple taps to cycle the selected element type.
The ReticleVertexTool is recommended for precise, vertex-based, geometry editing on touch devices, especially when using snapping (SnapSettings). It does not support multiple taps to cycle the selected element.
Programmatic changes to the GeometryEditor.geometry or GeometryEditor.selectedElement (for example calling GeometryEditor.selectVertex(Int, Int) or GeometryEditor.moveSelectedElement(Point)) not affected by the settings in InteractionConfiguration or ReticleInteractionConfiguration.
Change the appearance of the geometry by using the GeometryEditorStyle of the current GeometryEditor.tool - for example to match the symbology used by the graphic or feature being edited.
Enabling snapping can help ensure that interactive edits are more accurate, with fewer errors, by allowing you to create geometries that connect to each other and are coincident. Use GeometryEditor.snapSettings to configure snapping behavior.
Programmatic editing methods are also provided so you can augment your interactive geometry editing to support specific user requirements. For example:
Use GeometryEditor.insertVertex(Point) to add a subsequent vertex based on a GPS location from LocationDisplay.
Use GeometryEditor.deleteSelectedElement() to delete the current GeometryEditor.selectedElement.
Use GeometryEditor.moveSelectedElement(Point) to move the currently selected GeometryEditorElement to a specific Point, or GeometryEditor.moveSelectedElement(Double, Double) to nudge it in a specific direction.
Use GeometryEditor.replaceGeometry(Geometry) to take the current GeometryEditor.geometry, apply an operation such as a union or intersect by using GeometryEngine, and then replace the current geometry with the result so you can continue to edit as required.
Use GeometryEditor.undo() and GeometryEditor.redo() to undo and redo individual interactive or programmatic edits.
Use GeometryEditor.geometryChanged and GeometryEditor.selectedElementChanged to be notified when a user interaction or API call has changed the GeometryEditor.selectedElement or GeometryEditor.geometry. Changing the geometry state can also change GeometryEditor.canUndo, which triggers GeometryEditor.canUndoChanged.
Since
200.1.0
Constructors
Creates a default GeometryEditor.
Properties
True if there are actions that can be redone on the GeometryEditor.geometry, false otherwise. This applies to both programmatic and interactive changes to the GeometryEditor.geometry and is useful for enabling or disabling a UI control for redo actions.
True if there are actions that can be undone on the GeometryEditor.geometry, false otherwise. This applies to both programmatic and interactive changes to the GeometryEditor.geometry and is useful for enabling or disabling a UI control for undo actions.
The current geometry, updated as you interact with the view. The geometry returned depends on the state of the GeometryEditor:
True if an editing session is active, false otherwise. When true, interactions with the view can affect the state of the GeometryEditor.geometry or GeometryEditor.selectedElement.
The element that is currently selected in the GeometryEditor, or null if nothing is selected. Clicking or tapping on the different visible elements of a GeometryEditor.geometry in a view allows you to select and unselect them. This property returns a different type of GeometryEditorElement depending on what is selected - a vertex (GeometryEditorVertex), a mid-vertex (GeometryEditorMidVertex), a part of a polygon or polyline (GeometryEditorPart), or the entire geometry (GeometryEditorGeometry). You can change which selection interactions are allowed by using the InteractionConfiguration of the GeometryEditor.tool.
Configurable options for interactive snapping. Snapping allows you to create geometries that connect to each other and are coincident, so that interactive edits are more accurate, with fewer errors. Snapping is disabled by default - see SnapSettings for information about setting up snapping workflows.
The tool defining how you interact with the view to create and edit the GeometryEditor.geometry. The default value is a VertexTool with all interactive operations enabled, providing a common way of editing points, multipoints, polygons, and polylines.
Functions
Clears the current geometry being edited. Sets GeometryEditor.geometry to an empty geometry (Geometry.isEmpty = true). The GeometryType is maintained - to edit a different type of geometry, restart the GeometryEditor with the required type.
Clears the current selection. This sets GeometryEditor.selectedElement to null. It does not change the GeometryEditor.geometry.
Deletes the selected element from the current GeometryEditor.geometry. To clear the selection, but leave the state of the GeometryEditor.geometry unchanged, call GeometryEditor.clearSelection() instead.
Creates a new vertex at the specified location and inserts it after the currently selected element, or appends the point if there is nothing selected. If GeometryEditor.geometry is empty (Geometry.isEmpty is true), the given point is added as the initial vertex, and then selected. If nothing is selected (GeometryEditor.selectedElement is null), the point is appended to the end of the GeometryEditor.geometry, and then selected. If GeometryEditor.selectedElement is the first vertex in a part of a Multipart, the given point is inserted before the currently selected vertex, and then selected.
Moves the selected element to the specified location. If GeometryEditor.selectedElement is a GeometryEditorVertex, then the location of the vertex is moved to the given point. If the GeometryEditor.selectedElement is any other type of GeometryEditorElement, then the center of the element is moved to the given point.
Moves the selected element by the specified distances along the x-axis and y-axis.
Redoes the last action undone on the GeometryEditor.geometry.
Replaces the current GeometryEditor.geometry with the specified geometry. Use this method to make changes to the GeometryEditor.geometry that are not directly supported using other GeometryEditor methods. For example, to start a new part in a Polygon or Polyline geometry, get the current GeometryEditor.geometry, use a MultipartBuilder to add the required part, and then pass the updated GeometryBuilder.toGeometry() to this method.
Rotates the GeometryEditor.selectedElement by the specified angle. The angle of rotation is used in the form of the modulo of 360 degrees; for example rotating by 540 degrees is equivalent to rotating the by 180 degrees. A positive value corresponds to a counterclockwise rotation.
Scales the selected element by the specified factors. If the origin Point has a different SpatialReference than the associated MapView, the point will be reprojected before the geometry is rotated, using the default transformation.
Selects the entire GeometryEditor.geometry. When the entire geometry is selected it can be edited interactively and programmatically. For example you can move the entire geometry interactively by dragging, or call GeometryEditor.moveSelectedElement(Point) or GeometryEditor.moveSelectedElement(Double, Double) to move it programmatically.
Selects the mid-vertex with the specified indices. Mid-vertices do not exist in the GeometryEditor.geometry. They exist only in the display to serve as a visual cue that new vertices can be inserted between existing vertices. Since they do not exist in the geometry, mid-vertices cannot be programmatically moved or deleted. They can be used to insert a new vertex interactively.
Selects the part with the specified index. When a part of a polygon or polyline geometry is selected, a GeometryEditorPart is returned from GeometryEditor.selectedElement. If the polygon or polyline has only one part[Part], then a GeometryEditorGeometry with a shape equivalent to the entire geometry is returned from GeometryEditor.selectedElement instead, which provides immediate access to the extent (Geometry.extent) and can be directly used in other geometry operations. If the current GeometryEditor.geometry is a Point or Multipoint, the entire geometry is selected.
Selects the vertex with the specified indices. When a vertex is selected it can be edited while all other vertices of the geometry are unchanged. For example, you can move only the selected vertex interactively by dragging, or call GeometryEditor.moveSelectedElement(Point) or GeometryEditor.moveSelectedElement(Double, Double) to move the selected vertex programmatically.
Starts a geometry editing session based on the specified geometry. Use this method for data editing workflows, where you have an existing Geometry to be updated. After calling this method, the geometry is drawn in the map view, and interactions with the map view will select and edit the geometry, depending on the current GeometryEditor.tool and its InteractionConfiguration.
Starts a geometry editing session with an empty geometry of the specified GeometryType. Use this method for data creation workflows, where you know the GeometryType required but do not have an existing geometry to edit. After calling this method, nothing is drawn on the map view initially - user interactions on the map view will define and edit the geometry, depending on the current GeometryEditor.tool.
Stops the editing session by making the GeometryEditor no longer respond to user interaction and clears the GeometryEditor.geometry.
Undoes the last action on the GeometryEditor.geometry.