Defines the set of interactive operations you can enable or disable for a ReticleVertexTool. More...
| Header: | #include <ReticleInteractionConfiguration.h> |
| Since: | Esri::ArcGISRuntime 200.5 |
| Inherits: | Esri::ArcGISRuntime::Object |
Public Functions
| ReticleInteractionConfiguration(QObject *parent = nullptr) | |
| virtual | ~ReticleInteractionConfiguration() override |
| bool | isAllowDeletingSelectedElement() const |
| bool | isAllowMidVertexSelection() const |
| bool | isAllowMovingSelectedElement() const |
| bool | isAllowPartCreation() const |
| bool | isAllowVertexCreation() const |
| bool | isAllowVertexSelection() const |
| void | setAllowDeletingSelectedElement(bool allowDeletingSelectedElement) |
| void | setAllowMidVertexSelection(bool allowMidVertexSelection) |
| void | setAllowMovingSelectedElement(bool allowMovingSelectedElement) |
| void | setAllowPartCreation(bool allowPartCreation) |
| void | setAllowVertexCreation(bool allowVertexCreation) |
| void | setAllowVertexSelection(bool allowVertexSelection) |
Detailed Description
A ReticleInteractionConfiguration allows you to customize the interactive geometry editing experience when editing with a reticle to suit your specific users and app workflow. The default values of ReticleVertexTool::configuration allow creating and moving vertices.
Editing geometries when using the ReticleVertexTool involves different interactions to the VertexTool:
- When you start a geometry editor with an empty geometry (GeometryEditor::start(Esri::ArcGISRuntime::GeometryType)) and the reticle is displayed, it will show the GeometryEditorStyle::feedbackVertexSymbol at the crosshairs of the reticle. Tapping on the map view (at any position) will add a vertex at the position indicated by this symbol.
- When you drag on the map view to pan the map, the reticle remains in the center of the view, which repositions the reticle over the map. The feedback symbols (GeometryEditorStyle::feedbackVertexSymbol and GeometryEditorStyle::feedbackLineSymbol) update to show what change will be made to the GeometryEditor::geometry when you next tap on the map view. The new vertex is added at the index position (GeometryEditorVertex::vertexIndex) following the currently selected element (GeometryEditor::selectedElement).
- New vertices can also be created in between two existing vertices by using a mid-vertex (GeometryEditorStyle::midVertexSymbol). Position the reticle over the mid-vertex and tap, then drag the map and tap a second time to drop the new vertex in the required position.
- To move an existing vertex, first pan the map to position the reticle crosshairs over an existing vertex, and then tap. This will start a move of that vertex. Drag the map to reposition the reticle - you will again see the feedback symbols which indicate the change that will be made to the GeometryEditor::geometry. When the vertex is positioned correctly at the required new position, tap a second time to finish the move and update the geometry with the new vertex position.
If using snapping (see SnapSettings), the position of the GeometryEditorStyle::feedbackVertexSymbol will be adjusted to account for the current snapping configuration when adding and moving vertices with the ReticleVertexTool.
Use the properties on this class to customize which interactions are enabled. For example:
- Disable vertex creation (isAllowVertexCreation) to provide a tool focused on moving existing vertices in a geometry.
- Disable moving the selected element (isAllowMovingSelectedElement) for a workflow focused only on adding vertices, disallowing vertices to be moved with the tool.
- Set isAllowPartCreation to
trueto allow you to tap on the view when there is no current selection (GeometryEditor::selectedElement isnullptr) to start new parts in polyline and polygon geometries.
You can change the interaction properties of a tool at any point, including when a geometry editor is started (GeometryEditor::isStarted = true) and the tool is in use by the editor. If you change a property that disallows an in-progress interaction, then the interaction is cancelled and does not affect the state of the GeometryEditor.
Tapping when the reticle crosshairs are positioned over an existing vertex or mid-vertex will also select that element in addition to starting a move (providing the current values of ReticleInteractionConfiguration allow). Both selection and also moving (isAllowMidVertexSelection, isAllowVertexSelection, and isAllowMovingSelectedElement) must be enabled in order to allow moving.
You cannot use the ReticleVertexTool to select whole geometries or parts of multipart geometries, or deselect vertices - switch to an appropriately configured VertexTool in order to allow this workflow if required. Alternatively, you can programmatically set and clear selections regardless of the tool type or its current interaction configuration - see GeometryEditor::clearSelection, GeometryEditor::selectGeometry, GeometryEditor::selectMidVertex(int, int), GeometryEditor::selectPart(int), and GeometryEditor::selectVertex(int, int).
See also ReticleVertexTool::configuration.
Member Function Documentation
[explicit] ReticleInteractionConfiguration::ReticleInteractionConfiguration (QObject *parent = nullptr)
Creates a ReticleInteractionConfiguration that enables vertex adding, moving, and deleting.
- parent - The optional parent QObject.
Using this constructor results in the same default values as the ReticleVertexTool::configuration defaults.
[override virtual] ReticleInteractionConfiguration::~ReticleInteractionConfiguration ()
Destructor.
bool ReticleInteractionConfiguration::isAllowDeletingSelectedElement () const
Returns true if the selected GeometryEditorElement can be interactively deleted, false otherwise. Default is true.
If false, then the GeometryEditorElement::canDelete property of the GeometryEditor::selectedElement is also false. If you have implemented a customization to allow users to interactively delete the selected element, then you can use this property to check if that customization should be enabled.
Whether true or false, an element can be deleted by GeometryEditor::deleteSelectedElement.
bool ReticleInteractionConfiguration::isAllowMidVertexSelection () const
Returns true if a mid-vertex of a polygon or polyline can be interactively selected, false otherwise. Default is true.
By default, mid-vertices (GeometryEditorMidVertex) are displayed and can be helpful in interactive workflows to provide a visual cue that new vertices can be inserted between the existing vertices of polygons and polylines. They may be most helpful for users with less editing experience.
If true, and isAllowVertexCreation is also true, you can position the reticle over a mid-vertex, tap to select it and start the move, then drag the map to reposition the reticle - feedback symbols update to show what change will be made to the GeometryEditor::geometry when you next tap on the map view. Tap a second time to complete the move and drop the new vertex at the reticle position and update the GeometryEditor::geometry.
If false, and you also do not intend to programmatically select any mid-vertices (GeometryEditor::selectMidVertex(int, int)) then set GeometryEditorStyle::midVertexSymbol to empty to prevent the display of unusable mid-vertices.
Whether true or false, a mid-vertex can be selected by GeometryEditor::selectMidVertex(int, int).
See also GeometryEditor::selectedElement and GeometryEditor::selectedElementChanged.
bool ReticleInteractionConfiguration::isAllowMovingSelectedElement () const
Returns true if the selected GeometryEditorElement can be interactively moved, false otherwise. Default is true.
If true, you can use the reticle to move the selected GeometryEditorElement to the required position. A ReticleVertexTool can move a vertex if isAllowVertexSelection is true, and also use a move action on a mid-vertex if isAllowMidVertexSelection is true (which results in the insertion of a new vertex). Position the reticle over the required element, then tap to select it and start the move. Drag the map to reposition the reticle - feedback symbols update to show what change will be made to the GeometryEditor::geometry when you next tap on the map view. Tap a second time to complete the move and drop the new vertex at the reticle position and update the GeometryEditor::geometry.
If false, elements cannot be moved, but may be selected depending on the values of isAllowVertexSelection and isAllowMidVertexSelection.
If true, and the selected element is a GeometryEditorPart or a GeometryEditorGeometry with a geometry type of GeometryType::Polyline or GeometryType::Polygon then you cannot move the element with the ReticleVertexTool, but you can position the reticle and tap to change the selection to the vertex or mid-vertex you want to work with. This state can arise if the selection state was set programmatically, or set interactively when using a different GeometryEditorTool prior to switching to a ReticleVertexTool.
Whether true or false, any selected element can be moved using GeometryEditor::moveSelectedElement(const Esri::ArcGISRuntime::Point&) or GeometryEditor::moveSelectedElement(double, double).
bool ReticleInteractionConfiguration::isAllowPartCreation () const
Returns true if you can interactively create a new part in a polyline or polygon, false otherwise. Default is false.
If true and the GeometryType of the GeometryEditor::geometry is a polygon or polyline, you can interactively add new parts to the Multipart geometry if there is no currently selected element. If the GeometryType of the GeometryEditor::geometry is a point or multipoint, this property is ignored. The ReticleVertexTool does not support selection cycling to clear the selection in the same way as the VertexTool, so to allow you to start a new part interactively without first switching tools, first call GeometryEditor::clearSelection. When GeometryEditor::selectedElement is empty you can position the reticle as required and tap to add the first vertex of the new part at that position - feedback symbols will show where the new vertex will be added.
When creating new geometries using GeometryEditor::start(Esri::ArcGISRuntime::GeometryType), or calling GeometryEditor::start(const Esri::ArcGISRuntime::Geometry&) with an empty geometry, this property is always ignored when adding the first part, and respected thereafter.
Users less experienced with GIS data may not understand how to visually separate parts of polygons and polylines form a single geometry. You may wish to prevent such users from inadvertently creating geometries with multiple parts in order to keep their workflows straightforward and understandable. Alternatively, your app may be editing data which does not support multipart geometries.
See also isAllowVertexCreation and Multipart.
bool ReticleInteractionConfiguration::isAllowVertexCreation () const
Returns true to allow a vertex to be created interactively, false otherwise. Default is true.
If true, the GeometryEditorStyle::feedbackVertexSymbol will be displayed at the crosshairs of the reticle. Tapping on the map view (at any position) will add a vertex at the position indicated by this symbol. The vertex is added at an index position in the geometry after the previously selected vertex. An error to this rule is that if the previous selection was the first vertex in a Polyline, then the new vertex is inserted before the previous selection and becomes the first vertex of the polyline.
If you position the reticle over an existing GeometryEditorElement and tap, then this begins a move instead - see isAllowMovingSelectedElement.
Whether true or false, a vertex can be created by GeometryEditor::insertVertex(const Esri::ArcGISRuntime::Point&).
See also GeometryEditor::geometryChanged and isAllowPartCreation.
bool ReticleInteractionConfiguration::isAllowVertexSelection () const
Returns true to allow vertices to be selected interactively, false otherwise. Default is true.
If true, you can position the reticle over a vertex and tap to select it. If isAllowMovingSelectedElement is also true then the tap will also start a move.
Whether true or false, a vertex may still become selected in other ways, for example by a call to GeometryEditor::selectVertex(int, int), or when a new vertex is created.
See also GeometryEditor::selectedElement, GeometryEditor::selectedElementChanged, and GeometryEditorVertex.
void ReticleInteractionConfiguration::setAllowDeletingSelectedElement (bool allowDeletingSelectedElement )
Sets the allowDeletingSelectedElement to allowDeletingSelectedElement.
See also isAllowDeletingSelectedElement.
void ReticleInteractionConfiguration::setAllowMidVertexSelection (bool allowMidVertexSelection )
Sets the allowMidVertexSelection to allowMidVertexSelection.
See also isAllowMidVertexSelection.
void ReticleInteractionConfiguration::setAllowMovingSelectedElement (bool allowMovingSelectedElement )
Sets the allowMovingSelectedElement to allowMovingSelectedElement.
See also isAllowMovingSelectedElement.
void ReticleInteractionConfiguration::setAllowPartCreation (bool allowPartCreation )
Sets the allowPartCreation to allowPartCreation.
See also isAllowPartCreation.
void ReticleInteractionConfiguration::setAllowVertexCreation (bool allowVertexCreation )
Sets the allowVertexCreation to allowVertexCreation.
See also isAllowVertexCreation.
void ReticleInteractionConfiguration::setAllowVertexSelection (bool allowVertexSelection )
Sets the allowVertexSelection to allowVertexSelection.
See also isAllowVertexSelection.