|
| 1 | +# Edit geometries with programmatic reticle tool |
| 2 | + |
| 3 | +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. |
| 4 | + |
| 5 | + |
| 6 | + |
| 7 | +## Use case |
| 8 | + |
| 9 | +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. |
| 10 | + |
| 11 | +## How to use the sample |
| 12 | + |
| 13 | +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. |
| 14 | + |
| 15 | +Vertices can be selected and the viewpoint can be updated to their position by tapping them. |
| 16 | + |
| 17 | +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. |
| 18 | + |
| 19 | +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. |
| 20 | + |
| 21 | +## How it works |
| 22 | + |
| 23 | +1. Create a `GeometryEditor` and assign it to a map view with the `geometryEditor` view modifier. |
| 24 | +2. Use the `start(withType:)` method on the `GeometryEditor` to create a new geometry or `start(withInitial:)` to edit an existing geometry. |
| 25 | + - 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: |
| 26 | + - Create a `MapViewReader` to get the `MapViewProxy` and use it to identify graphics at the tapped location with `identifyGraphicsOverlays(screenPoint:tolerance:returnPopupsOnly:maximumResultsPerLayer:)`. |
| 27 | + - Access the first graphic from the identify result `IdentifyGraphicsOverlayResult`. |
| 28 | + - Access the geometry associated with the Graphic using `Graphic.geometry` - this will be used in the `GeometryEditor.start(withInitial:)` method. |
| 29 | +3. Create a `ProgrammaticReticleTool` and set the geometry editor tool. |
| 30 | +4. Add event handlers to listen to GeometryEditor.HoveredElementChanged and GeometryEditorPickedUpElementChanged. |
| 31 | + - These events can be used to determine the effect a button press will have and set the button text accordingly. |
| 32 | +5. Use the `onSingleTapGesture` modifier 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. |
| 33 | + - To retrieve the tapped element and update the viewpoint: |
| 34 | + - Use `MapViewProxy.identifyGeometryEditor(screenPoint:tolerance)` to identify geometry editor elements at the location of the tap. |
| 35 | + - Access the first element from the `IdentifyGeometryEditorResult` as `result.elements.first`. |
| 36 | + - Depending on whether or not the element is a `GeometryEditorVertex` or `GeometryEditorMidVertex` use the `selectVertexAt(partIndex:vertexIndex:)` or the `selectMidVertexAt(partIndex:segmentIndex:)` methods on the geometry reader to select it. |
| 37 | + - Update the viewpoint using `MapViewProxy.setViewpoint(_:duration:)`. |
| 38 | +6. Enable and disable the vertex creation preview using `ProgrammaticReticleTool.vertexCreationPreviewIsEnabled`. |
| 39 | + - To prevent mid-vertex growth when hovered use `ProgrammaticReticleTool.Style.GrowEffect.appliesToMidVertices`. |
| 40 | +7. Check to see if undo and redo are possible during an editing session using `GeometryEditor.canUndo` and `GeometryEditor.canRedo`. If it's possible, use the `undo()` and `redo()` methods on the geometry editor. |
| 41 | + - 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 the `GeometryEditor.pickedUpElement` property to check for a picked up element. |
| 42 | +8. Check whether the currently selected `GeometryEditorElement` can be deleted `GeometryEditor.selectedElement.canBeDeleted`. If the element can be deleted, delete using `GeometryEditor.deleteSelectedElement()`. |
| 43 | +9. Call `GeometryEditor.stop()` to finish the editing session and store the `Graphic`. 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. |
| 44 | + - To create a new graphic in the graphics overlay: |
| 45 | + - Use `Graphic(geometry:)`, create a new Graphic with the geometry returned by the `GeometryEditor.stop()` method. |
| 46 | + - Append the graphic to the graphics overlay using `GraphicsOverlay.addGraphic(_:)`. |
| 47 | + - To update the geometry underlying an existing Graphic in the GraphicsOverlay: |
| 48 | + - Replace the existing graphic's geometry property with the geometry returned by the `GeometryEditor.stop()` method. |
| 49 | + |
| 50 | +## Relevant API |
| 51 | + |
| 52 | +* Geometry |
| 53 | +* GeometryEditor |
| 54 | +* Graphic |
| 55 | +* GraphicsOverlay |
| 56 | +* MapView |
| 57 | +* ProgrammaticReticleTool |
| 58 | + |
| 59 | +## Additional information |
| 60 | + |
| 61 | +The sample demonstrates a number of workflows which can be altered depending on desired app functionality: |
| 62 | + |
| 63 | +* picking up a hovered element combines selection and pick up, this can be separated into two steps to require selection before pick up. |
| 64 | + |
| 65 | +* 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. |
| 66 | + |
| 67 | +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. |
| 68 | + |
| 69 | +## Tags |
| 70 | + |
| 71 | +draw, edit, freehand, geometry editor, programmatic, reticle, sketch, vertex |
0 commit comments