|
| 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. Tap the button to start the geometry editor, pan the map to position the reticle then tap 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 tapping the button to pick it up. The vertex can be moved by panning the map and dropped in a new position by tapping 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 set it to the map view using `ArcGISMapViewController.geometryEditor`. |
| 24 | +2. Start the `GeometryEditor` using `GeometryEditor.startWithGeometryType()` to create a new geometry or `GeometryEditor.startWithGeometry()` 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 | + * Use `ArcGISMapViewController.identifyGraphicsOverlay()` to identify graphics at the location of a tap. |
| 27 | + * Access the `IdentifyGraphicsOverlayResult.graphics`. |
| 28 | + * Find the desired graphic in the list. |
| 29 | + * Access the geometry associated with the `Graphic` using `Graphic.geometry` - this will be used in the `GeometryEditor.StartWithGeometry()` method. |
| 30 | +3. Create a `ProgrammaticReticleTool` and set the `GeometryEditor.tool`. |
| 31 | +4. Subscribe to the `GeometryEditor.onHoveredElementChanged` and `GeometryEditor.onPickedUpElementChanged` events. |
| 32 | + * These events can be used to update the UI state, such as determining the effect a button press will have. |
| 33 | +5. Listen to tap events when the geometry editor is active to select and navigate to tapped vertices and mid-vertices. |
| 34 | + * To retrieve the tapped element and update the viewpoint: |
| 35 | + * Use `ArcGISMapViewController.identifyGeometryEditor()` to identify geometry editor elements at the location of the tap. |
| 36 | + * Access the `IdentifyGeometryEditorResult.elements`. |
| 37 | + * Find the desired element in the list. |
| 38 | + * Depending on whether or not the element is a `GeometryEditorVertex` or `GeometryEditorMidVertex` use `GeometryEditor.selectVertex()` or `GeometryEditor.selectMidVertex()` to select it. |
| 39 | + * Update the viewpoint using `ArcGISMapView.setViewpoint()`. |
| 40 | +6. Enable and disable the vertex creation preview using `ProgrammaticReticleTool.vertexCreationPreviewEnabled`. |
| 41 | + * To prevent mid-vertex growth when hovered use `ProgrammaticReticleTool.style.growEffect.applyToMidVertices`. |
| 42 | +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 `GeometryEditor.undo()` and `GeometryEditor.redo()`. |
| 43 | + * A picked up element can be returned to its previous position using `GeometryEditor.cancelCurrentAction()`. 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. |
| 44 | +8. Check whether the currently selected `GeometryEditorElement` can be deleted (`GeometryEditor.selectedElement.canDelete`). If the element can be deleted, delete using `GeometryEditor.deleteSelectedElement()`. |
| 45 | +9. Call `GeometryEditor.stop()` to finish the editing session and store the `Graphic`. The `GeometryEditor` 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 `GraphicsOverlay`. |
| 46 | + * To create a new `Graphic` in the `GraphicsOverlay`: |
| 47 | + * Create a new `Graphic` with the geometry returned by the `GeometryEditor.stop()` method. |
| 48 | + * Append the `Graphic` to the `GraphicsOverlay`(i.e. `GraphicsOverlay.graphics.add(graphic)`). |
| 49 | + * To update the geometry underlying an existing `Graphic` in the `GraphicsOverlay`: |
| 50 | + * Replace the existing `Graphic`'s `geometry` property with the geometry returned by the `GeometryEditor.stop()` method. |
| 51 | + |
| 52 | +## Relevant API |
| 53 | + |
| 54 | +* ArcGISMapView |
| 55 | +* Geometry |
| 56 | +* GeometryEditor |
| 57 | +* Graphic |
| 58 | +* GraphicsOverlay |
| 59 | +* ProgrammaticReticleTool |
| 60 | + |
| 61 | +## Additional information |
| 62 | + |
| 63 | +The sample demonstrates a number of workflows which can be altered depending on desired app functionality: |
| 64 | + |
| 65 | +* picking up a hovered element combines selection and pick up, this can be separated into two steps to require selection before pick up. |
| 66 | + |
| 67 | +* 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. |
| 68 | + |
| 69 | +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. |
| 70 | + |
| 71 | +## Tags |
| 72 | + |
| 73 | +draw, edit, freehand, geometry editor, programmatic, reticle, sketch, vertex |
0 commit comments