Use the Programmatic Reticle Tool to edit and create geometries with programmatic operations to facilitate customized workflows such as those using buttons rather than tap interactions.
Use case
A field worker can use a button driven workflow to mark important features on a map. They can digitize features like sample or observation locations, fences, pipelines, and building footprints using point, multipoint, polyline, and polygon geometries. To create and edit geometries, workers can use a vertex-based reticle tool to specify vertex locations by panning the map to position the reticle over a feature of interest. Using a button-driven workflow they can then place new vertices or pick up, move and drop existing vertices.
How to use the sample
To create a new geometry, select the geometry type you want to create (i.e. points, multipoints, polyline, or polygon) in the settings view. Press the button to start the geometry editor, pan the map to position the reticle then press the button to place a vertex. To edit an existing geometry, tap the geometry to be edited in the map and perform edits by positioning the reticle over a vertex and pressing the button to pick it up. The vertex can be moved by panning the map and dropped in a new position by pressing the button again.
Vertices can be selected and the viewpoint can be updated to their position by tapping them.
Vertex creation can be disabled using the switch in the settings view. When this switch is toggled off new vertex creation is prevented, existing vertices can be picked up and moved, but mid-vertices cannot be selected or picked up and will not grow when hovered. The feedback vertex and feedback lines under the reticle will also no longer be visible.
Use the buttons in the settings view to undo or redo changes made to the geometry and the cancel and done buttons to discard and save changes, respectively.
How it works
- Create a
GeometryEditorand assign it to a map view with thegeometryEditorview modifier. - Use the
start(withType:)method on theGeometryEditorto create a new geometry orstart(withInitial:)to edit an existing geometry.
- If using the Geometry Editor to edit an existing geometry, the geometry must be retrieved from the graphics overlay being used to visualize the geometry prior to calling the start method. To do this:
- Create a
MapViewReaderto get theMapViewProxyand use it to identify graphics at the tapped location withidentifyGraphicsOverlays(screenPoint:tolerance:returnPopupsOnly:maximumResultsPerLayer:). - Access the first graphic from the identify result
IdentifyGraphicsOverlayResult. - Access the geometry associated with the Graphic using
Graphic.geometry- this will be used in theGeometryEditor.start(withInitial:)method.
- Create a
ProgrammaticReticleTooland set the geometry editor tool. - Add event handlers to listen to GeometryEditor.HoveredElementChanged and GeometryEditorPickedUpElementChanged.
- These events can be used to determine the effect a button press will have and set the button text accordingly.
- Use the
onSingleTapGesturemodifier to listen for tap events on the map view when the geometry editor is active to select and navigate to tapped vertices and mid-vertices.
- To retrieve the tapped element and update the viewpoint:
- Use
MapViewProxy.identifyGeometryEditor(screenPoint:tolerance)to identify geometry editor elements at the location of the tap. - Access the first element from the
IdentifyGeometryEditorResultasresult.elements.first. - Depending on whether or not the element is a
GeometryEditorVertexorGeometryEditorMidVertexuse theselectVertexAt(partIndex:vertexIndex:)or theselectMidVertexAt(partIndex:segmentIndex:)methods on the geometry reader to select it. - Update the viewpoint using
MapViewProxy.setViewpoint(_:duration:).
- Enable and disable the vertex creation preview using
ProgrammaticReticleTool.vertexCreationPreviewIsEnabled.
- To prevent mid-vertex growth when hovered use
ProgrammaticReticleTool.Style.GrowEffect.appliesToMidVertices.
- Check to see if undo and redo are possible during an editing session using
GeometryEditor.canUndoandGeometryEditor.canRedo. If it's possible, use theundo()andredo()methods on the geometry editor.
- A picked up element can be returned to its previous position using
cancelCurrentAction()on the geometry editor. This can be useful to undo a pick up without undoing any change to the geometry. Use theGeometryEditor.pickedUpElementproperty to check for a picked up element.
- Check whether the currently selected
GeometryEditorElementcan be deletedGeometryEditor.selectedElement.canBeDeleted. If the element can be deleted, delete usingGeometryEditor.deleteSelectedElement(). - Call
GeometryEditor.stop()to finish the editing session and store theGraphic. The geometry editor does not automatically handle the visualization of a geometry output from an editing session. This must be done manually by propagating the geometry returned into a graphic added to a graphics overlay.
- To create a new graphic in the graphics overlay:
- Use
Graphic(geometry:), create a new Graphic with the geometry returned by theGeometryEditor.stop()method. - Append the graphic to the graphics overlay using
GraphicsOverlay.addGraphic(_:). - To update the geometry underlying an existing Graphic in the GraphicsOverlay:
- Replace the existing graphic's geometry property with the geometry returned by the
GeometryEditor.stop()method.
Relevant API
- Geometry
- GeometryEditor
- Graphic
- GraphicsOverlay
- MapView
- ProgrammaticReticleTool
Additional information
The sample demonstrates a number of workflows which can be altered depending on desired app functionality:
-
picking up a hovered element combines selection and pick up, this can be separated into two steps to require selection before pick up.
-
tapping a vertex or mid-vertex selects it and updates the viewpoint to its position. This could be changed to not update the viewpoint or also pick up the element.
With the hovered and picked up element changed events and the programmatic APIs on the ProgrammaticReticleTool, a broad range of editing experiences can be implemented.
Tags
draw, edit, freehand, geometry editor, programmatic, reticle, sketch, vertex
Sample Code
EditGeometriesWithProgrammaticReticleToolView.swift
// Copyright 2025 Esri // // Licensed under the Apache License, Version 2.0 (the "License"); // you may not use this file except in compliance with the License. // You may obtain a copy of the License at // // https://www.apache.org/licenses/LICENSE-2.0 // // Unless required by applicable law or agreed to in writing, software // distributed under the License is distributed on an "AS IS" BASIS, // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. // See the License for the specific language governing permissions and // limitations under the License. import ArcGIS import SwiftUI struct EditGeometriesWithProgrammaticReticleToolView: View { /// A map with an imagery basemap. @State private var map: Map = { let map = Map(basemapStyle: .arcGISImagery) map.initialViewpoint = .ireland return map }() /// The view model for this sample. @State private var model = GeometryEditorModel() /// The screen point to perform an identify operation. @State private var identifyScreenPoint: CGPoint? var body: some View { VStack { MapViewReader { mapView in MapView(map: map, graphicsOverlays: [model.geometryOverlay]) .geometryEditor(model.geometryEditor) .onSingleTapGesture { screenPoint, _ in identifyScreenPoint = screenPoint } .task(id: identifyScreenPoint) { guard let identifyScreenPoint else { return } if model.isStarted { await selectGeometryEditorElement( at: identifyScreenPoint, mapView: mapView ) } else { await startEditingGraphic( at: identifyScreenPoint, mapView: mapView ) } } } } .toolbar { ToolbarItem(placement: .topBarTrailing) { GeometryEditorMenu(model: model) } ToolbarItem(placement: .bottomBar) { Button(model.reticleState.label) { model.handleReticleState() } .disabled(!model.geometryEditor.isStarted) } } } /// Selects the geometry editor element identified at the tap location to edit. /// - Parameters: /// - point: The screen coordinate of the geo view at which to identify. /// - mapView: The map view proxy used to identify the screen point. private func selectGeometryEditorElement(at point: CGPoint, mapView: MapViewProxy) async { // Identify the geometry editor result at the tapped position. let identifyResult = try? await mapView.identifyGeometryEditor( screenPoint: point, tolerance: 10 ) guard let element = identifyResult?.elements.first else { return } // If the element is a vertex or mid-vertex, set the viewpoint to its position and select it. switch element { case let vertex as GeometryEditorVertex: await mapView.setViewpoint( Viewpoint( center: element.extent.center, scale: Viewpoint.ireland.targetScale ) ) model.geometryEditor.selectVertexAt( partIndex: vertex.partIndex, vertexIndex: vertex.vertexIndex ) case let midVertex as GeometryEditorMidVertex where model.allowsVertexCreation: await mapView.setViewpoint( Viewpoint( center: element.extent.center, scale: Viewpoint.ireland.targetScale ) ) model.geometryEditor.selectMidVertexAt( partIndex: midVertex.partIndex, segmentIndex: midVertex.segmentIndex ) default: break } } /// Starts editing the graphic identified at the tap location. /// - Parameters: /// - point: The screen coordinate of the geo view at which to identify. /// - mapView: The map view proxy used to identify the screen point. private func startEditingGraphic(at point: CGPoint, mapView: MapViewProxy) async { // Identify graphics in the graphics overlay using the tapped position. let results = try? await mapView.identifyGraphicsOverlays( screenPoint: point, tolerance: 10 ) guard let selectedGraphic = results?.first?.graphics.first, let geometry = selectedGraphic.geometry else { return } model.startEditing(with: selectedGraphic) // If vertex creation is allowed, set the viewpoint to the center of the selected graphic's geometry. // Otherwise, set the viewpoint to the end point of the first part of the geometry. if model.allowsVertexCreation { await mapView.setViewpoint( Viewpoint( center: geometry.extent.center, scale: Viewpoint.ireland.targetScale ) ) } else { guard let center = model.selectedGraphic?.geometry?.lastPoint else { return } await mapView.setViewpoint( Viewpoint( center: center, scale: Viewpoint.ireland.targetScale ) ) } } } /// A view that provides a menu for geometry editor functionality. private struct GeometryEditorMenu: View { /// The model for the menu. @Bindable var model: GeometryEditorModel /// The currently selected element. @State private var selectedElement: GeometryEditorElement? /// The current geometry of the geometry editor. @State private var geometry: Geometry? var body: some View { Menu("Geometry Editor", systemImage: "pencil.line") { if !model.isStarted { // If the geometry editor is not started, show the main menu. mainMenuContent } else { // If the geometry editor is started, show the edit menu. editMenuContent .task { for await geometry in model.geometryEditor.$geometry { // Update geometry when there is an update. self.geometry = geometry } } .task { for await element in model.geometryEditor.$selectedElement { // Update selected element when there is an update. selectedElement = element } } .task { for await _ in model.geometryEditor.$hoveredElement { // Update reticle state when there is a hovered element update. model.updateReticleState() } } .task { for await _ in model.geometryEditor.$pickedUpElement { // Update reticle state when there is a hovered picked up element update. model.updateReticleState() } } } } } } private extension GeometryEditorMenu { /// The content of the main menu. @ViewBuilder var mainMenuContent: some View { Menu("Programmatic Reticle Tool") { Button("New Point", systemImage: "smallcircle.filled.circle") { model.startEditing(withType: Point.self) } Button("New Line", systemImage: "line.diagonal") { model.startEditing(withType: Polyline.self) } Button("New Area", systemImage: "skew") { model.startEditing(withType: Polygon.self) } Button("New Multipoint", systemImage: "hand.point.up.braille") { model.startEditing(withType: Multipoint.self) } } Divider() Button("Delete All Geometries", systemImage: "trash", role: .destructive) { model.deleteAllGeometries() } .disabled(!model.canClearGraphics) } /// The content of the editing menu. @ViewBuilder var editMenuContent: some View { Toggle("Allow vertex creation", isOn: $model.allowsVertexCreation) Button("Undo", systemImage: "arrow.uturn.backward") { if model.geometryEditor.pickedUpElement != nil { model.geometryEditor.cancelCurrentAction() } else { model.geometryEditor.undo() } } .disabled(!model.geometryEditor.canUndo) Button("Redo", systemImage: "arrow.uturn.forward") { model.geometryEditor.redo() } .disabled(!model.geometryEditor.canRedo) Button("Delete Selected Element", systemImage: "xmark.square.fill") { model.geometryEditor.deleteSelectedElement() } .disabled(deleteButtonIsDisabled) Button("Clear Current Sketch", systemImage: "trash", role: .destructive) { model.geometryEditor.clearGeometry() } .disabled(!canClearCurrentSketch) Divider() Button("Save Sketch", systemImage: "square.and.arrow.down") { model.save() } .disabled(!canSave) Button("Cancel Sketch", systemImage: "xmark") { model.stop() } } } private extension GeometryEditorMenu { /// A Boolean value indicating whether the selection can be deleted. /// /// In some instances deleting the selection may be invalid. One example would be the mid vertex /// of a line. var deleteButtonIsDisabled: Bool { guard let selectedElement else { return true } return !selectedElement.canBeDeleted } /// A Boolean value indicating if the geometry can be saved to a graphics overlay. var canSave: Bool { return geometry?.sketchIsValid ?? false } /// A Boolean value indicating if the geometry can be cleared from the geometry editor. var canClearCurrentSketch: Bool { return geometry.map { !$0.isEmpty } ?? false } } /// An object that acts as a view model for the geometry editor menu. @MainActor @Observable private class GeometryEditorModel { /// The geometry editor. let geometryEditor = GeometryEditor() /// The programmatic reticle tool. private let reticleTool = ProgrammaticReticleTool() /// The graphics overlay used to save geometries to. let geometryOverlay = GraphicsOverlay(renderingMode: .dynamic) /// The selected graphic to edit. @ObservationIgnored var selectedGraphic: Graphic? /// A Boolean value indicating if the initial graphics and saved sketches can be cleared. private(set) var canClearGraphics = true /// A Boolean value indicating if the geometry editor has started. private(set) var isStarted = false /// A Boolean value indicating if vertex creation is allowed. var allowsVertexCreation = true { didSet { reticleTool.vertexCreationPreviewIsEnabled = allowsVertexCreation reticleTool.style.growEffect?.appliesToMidVertices = allowsVertexCreation } } /// The reticle state used to determine the current action of the programmatic reticle tool. enum ReticleState { case `default`, pickedUp, hoveringVertex, hoveringMidVertex /// A human-readable label of the property. var label: String { switch self { case .default: "Insert Point" case .pickedUp: "Drop Point" case .hoveringVertex: "Pick up point" case .hoveringMidVertex: "Pick up point" } } } /// The programmatic reticle state. var reticleState: ReticleState = .default init() { let pinkneysGreenGraphic = Graphic(geometry: .pinkneysGreen, symbol: .redArea()) let beechLodgeBoundaryGraphic = Graphic(geometry: .beechLodgeBoundary, symbol: .blueLine()) let treeMarkers = Graphic(geometry: .treeMarkers, symbol: .yellowCircle()) geometryOverlay.addGraphics([ pinkneysGreenGraphic, beechLodgeBoundaryGraphic, treeMarkers ]) geometryEditor.tool = reticleTool } /// Saves the current geometry to the graphics overlay and stops editing. /// - Precondition: Geometry's sketch must be valid. func save() { precondition(geometryEditor.geometry?.sketchIsValid ?? false) if selectedGraphic != nil { // Update geometry for edited graphic. updateGraphic() } else { // Add new graphic. addGraphic() } reticleState = .default } /// Updates the selected graphic with the current geometry. private func updateGraphic() { guard let selectedGraphic = selectedGraphic.take() else { return } selectedGraphic.geometry = geometryEditor.stop() isStarted = false selectedGraphic.isVisible = true } /// Adds a new graphic for the current geometry to the graphics overlay. private func addGraphic() { let geometry = geometryEditor.geometry! let graphic = Graphic(geometry: geometry, symbol: symbol(for: geometry)) geometryOverlay.addGraphic(graphic) stop() canClearGraphics = true } /// Removes the initial graphics and saved sketches on the graphics overlay. func deleteAllGeometries() { geometryOverlay.removeAllGraphics() canClearGraphics = false reticleState = .default } /// Starts editing with the specified tool and geometry type. /// - Parameter geometryType: The type of geometry to draw. func startEditing(withType geometryType: Geometry.Type) { geometryEditor.start(withType: geometryType) isStarted = true reticleState = .default } /// Starts editing a given graphic with the geometry editor. /// - Parameter graphic: The graphic to edit. func startEditing(with graphic: Graphic) { selectedGraphic = graphic graphic.isVisible = false let geometry = graphic.geometry! geometryEditor.start(withInitial: geometry) isStarted = true updateReticleState() } /// Stops editing with the geometry editor. func stop() { geometryEditor.stop() isStarted = false if let selectedGraphic = selectedGraphic.take() { selectedGraphic.isVisible = true } reticleState = .default } /// Returns the symbology for graphics saved to the graphics overlay. /// - Parameter geometry: The geometry of the graphic to be saved. /// - Returns: Either a marker or fill symbol depending on the type of provided geometry. private func symbol(for geometry: Geometry) -> Symbol { return switch geometry { case is Point: .redSquare() case is Multipoint: .yellowCircle() case is Polyline: .blueLine() case is ArcGIS.Polygon: .redArea() default: fatalError("Unexpected geometry type") } } /// Updates the reticle state based on the picked up and hovered elements. func updateReticleState() { reticleState = if geometryEditor.pickedUpElement != nil { .pickedUp } else if let hoveredElement = geometryEditor.hoveredElement { if allowsVertexCreation { // Vertices and mid-vertices can be picked up. switch hoveredElement { case is GeometryEditorVertex: .hoveringVertex case is GeometryEditorMidVertex: .hoveringMidVertex default: .default } } else { // Only vertices can be picked up, mid-vertices cannot be picked up. switch hoveredElement { case is GeometryEditorVertex: .hoveringVertex default: .default } } } else { .default } } /// Handles the reticle state by placing or picking up an element. func handleReticleState() { switch reticleState { case .default, .pickedUp: reticleTool.placeElementAtReticle() case .hoveringVertex, .hoveringMidVertex: reticleTool.selectElementAtReticle() reticleTool.pickUpSelectedElement() } } } private extension Geometry { var lastPoint: Point? { switch self { case let multipart as any Multipart: multipart.parts.last?.endPoint case let multipoint as Multipoint: multipoint.points.last case let point as Point: point default: nil } } // swiftlint:disable force_try static var pinkneysGreen: Geometry { let json = Data( """ {"rings":[[[-84843.262719916485,6713749.9329888355],[-85833.376589175183,6714679.7122141244], [-85406.822347959576,6715063.9827222107],[-85184.329997390232,6715219.6195847588], [-85092.653857582554,6715119.5391713539],[-85090.446872787768,6714792.7656492386], [-84915.369168906298,6714297.8798246197],[-84854.295522911285,6714080.907587287], [-84843.262719916485,6713749.9329888355]]], "spatialReference":{"wkid":102100,"latestWkid":3857}} """.utf8 ) return try! Polygon.fromJSON(json) } static var beechLodgeBoundary: Geometry { let json = Data( """ {"paths":[[[-87090.652708065536,6714158.9244240439],[-87247.362370337316,6714232.880689906], [-87226.314032974493,6714605.4697726099],[-86910.499335316243,6714488.006312645], [-86750.82198052686,6714401.1768307304],[-86749.846825938366,6714305.8450344801]]], "spatialReference":{"wkid":102100,"latestWkid":3857}} """.utf8 ) return try! Polyline.fromJSON(json) } static var treeMarkers: Geometry { let json = Data( """ {"points":[[-86750.751150056443,6713749.4529355941],[-86879.381793060631,6713437.3335486846], [-87596.503104619667,6714381.7342108283],[-87553.257569537804,6714402.0910389507], [-86831.019903597829,6714398.4128562529],[-86854.105933315877,6714396.1957954112], [-86800.624094892439,6713992.3374453448]], "spatialReference":{"wkid":102100,"latestWkid":3857}}" """.utf8 ) return try! Multipoint.fromJSON(json) } // swiftlint:enable force_try } private extension Symbol { static func redSquare() -> Symbol { SimpleMarkerSymbol( style: .square, color: .red, size: 10 ) } static func yellowCircle() -> Symbol { SimpleMarkerSymbol( style: .circle, color: .yellow, size: 5 ) } static func blueLine() -> Symbol { SimpleLineSymbol( color: .blue, width: 2 ) } static func redArea() -> Symbol { SimpleFillSymbol( style: .solid, color: .red.withAlphaComponent(0.3), outline: SimpleLineSymbol( style: .dash, color: .black, width: 1 ) ) } } private extension Viewpoint { /// A viewpoint centered at the island of Inis Meáin (Aran Islands) in Ireland. static var ireland: Viewpoint { Viewpoint( center: Point(latitude: 51.523806, longitude: -0.775395), scale: 2e4 ) } } #Preview { NavigationStack { EditGeometriesWithProgrammaticReticleToolView() } }