Controls interactive snapping functionality for the GeometryEditor. More...
| Header: | #include <SnapSettings.h> |
| Since: | Esri::ArcGISRuntime 200.4 |
| Inherits: | Esri::ArcGISRuntime::Object |
Public Functions
| SnapSettings(QObject *parent = nullptr) | |
| virtual | ~SnapSettings() override |
| bool | isEnabled() const |
| bool | isFeatureSnappingEnabled() const |
| bool | isGeometryGuidesEnabled() const |
| bool | isHapticFeedbackEnabled() const |
| void | setEnabled(bool enabled) |
| void | setFeatureSnappingEnabled(bool featureSnappingEnabled) |
| void | setGeometryGuidesEnabled(bool geometryGuidesEnabled) |
| void | setHapticFeedbackEnabled(bool hapticFeedbackEnabled) |
| QList<Esri::ArcGISRuntime::SnapSourceSettings *> | sourceSettings() const |
| void | syncSourceSettings() |
Detailed Description
Snapping allows you to create geometries that connect to each other and are coincident, so that interactive edits are more accurate, with fewer errors.
If isEnabled is true and a user edits a geometry interactively, then the position of the interactive edit is adjusted to coincide with ("snap to") other geometry edges (segments) or vertices. When the edit position has been adjusted, visual cues show the user the adjusted edit position, and which aspect of the referenced geometry was used as the best candidate for that adjustment. You can enable different types of snapping:
- isFeatureSnappingEnabled allows snapping to other features or graphics.
- isGeometryGuidesEnabled allows snapping to the current GeometryEditor::geometry.
To use snapping in the GeometryEditor:
- Connect a GeometryEditor to a map view using MapView::geometryEditor.
- Get the GeometryEditor::snapSettings and set isEnabled to
true. - To snap to other features or graphics in the map view:
- Ensure the MapView::map and any layers in it are loaded. Only layers that provide full resolution geometries can be used for snapping.
- Call syncSourceSettings, and then set SnapSourceSettings::isEnabled to
truefor each SnapSource that you want users to be able to snap to. You may wish to enable all the SnapSourceSettings, use only select sources, or delegate the choice to your users. - Call one of the start methods on GeometryEditor to allow the end user to create or edit a new geometry using the current SnapSettings.
- You can also call syncSourceSettings to refresh the collection of snap sources at any time. The state of any existing SnapSourceSettings is preserved by this call.
You can snap to SnapSource objects that are contained in the MapView associated with the GeometryEditor, and are visible. As snapping to SnapSource objects is done to maintain data integrity between different sources of data, only SnapSource objects that provide full resolution geometries can be used for snapping. See SnapSource for more information.
The visual cues that indicate to a user when snapping has occurred can be customized using GeometryEditorStyle::snappedToVertexSymbol and GeometryEditorStyle::snappedToLineSymbol. If there are multiple potential candidates that could be snapped to for a given pointer position, then GeometryEditorStyle::multipleSnapCandidatesSymbol is used to indicate this.
Relevant samples:
- Snap geometry edits: Use the Geometry Editor to edit a geometry and align it to existing geometries on a map.
See also GeometryEditor, SnapSourceSettings, and SnapSource.
Member Function Documentation
[explicit] SnapSettings::SnapSettings (QObject *parent = nullptr)
Creates a default SnapSettings.
- parent - The optional parent QObject.
[override virtual] SnapSettings::~SnapSettings ()
Destructor.
bool SnapSettings::isEnabled () const
Returns true to allow interactive snapping, based on the configured sourceSettings, false otherwise. Default is false.
If isEnabled is true and a user edits a geometry interactively, then when the pointer is close to an existing snappable graphic or feature, the position of the interactive edit is adjusted to coincide with ("snap to") that graphic or feature. The content of sourceSettings determines which sources of geometries can be used to snap to.
[since Esri::ArcGISRuntime 200.6] bool SnapSettings::isFeatureSnappingEnabled () const
Returns true to allow interactive snapping to other features and graphics, based on the configured sourceSettings, false otherwise. Default is true.
Ignored if isEnabled is false.
Feature snapping can be combined with geometry guides by ensuring isGeometryGuidesEnabled is true.
This function was introduced in Esri::ArcGISRuntime 200.6.
[since Esri::ArcGISRuntime 200.6] bool SnapSettings::isGeometryGuidesEnabled () const
Returns true to allow interactive snapping relative to the current GeometryEditor::geometry, false otherwise. Default is true.
When enabled, additional visual cues appear as temporary guides when interactively editing polygon or polyline geometries, allowing edits to be snapped to:
- coincide with an existing edge (segment) or vertex of the current GeometryEditor::geometry
- create a new segment perpendicular to the previous segment of the current GeometryEditor::geometry
- create a new segment as an extension of the previous segment of the current GeometryEditor::geometry
- create a new segment parallel to an existing segment of the current GeometryEditor::geometry
The guides shown indicate the type of snap occurring.
Ignored if isEnabled is false.
Geometry guides can be combined with snapping to other features or graphics by ensuring isFeatureSnappingEnabled is true and configuring sourceSettings appropriately.
This function was introduced in Esri::ArcGISRuntime 200.6.
[since Esri::ArcGISRuntime 200.6] bool SnapSettings::isHapticFeedbackEnabled () const
Returns true to enable haptic feedback whenever a snap occurs (if supported by the device), false otherwise.
Enables haptic feedback whenever a snap occurs to a feature or graphic from a SnapSource, or geometry guide.
Note that the specifics of the haptic will vary on different platforms and devices, and this boolean will have no effect if the end user's device does not support haptics.
Haptic feedback should be expected whenever the GeometryEditor::snapChanged event fires. If you want to implement your own haptics experience, set this boolean to false and trigger your own custom haptics by listening to the GeometryEditor::snapChanged event.
The default value is true.
This function was introduced in Esri::ArcGISRuntime 200.6.
void SnapSettings::setEnabled (bool enabled)
Sets the enabled to enabled.
See also isEnabled.
[since Esri::ArcGISRuntime 200.6] void SnapSettings::setFeatureSnappingEnabled (bool featureSnappingEnabled )
Sets the featureSnappingEnabled to featureSnappingEnabled.
This function was introduced in Esri::ArcGISRuntime 200.6.
See also isFeatureSnappingEnabled.
[since Esri::ArcGISRuntime 200.6] void SnapSettings::setGeometryGuidesEnabled (bool geometryGuidesEnabled )
Sets the geometryGuidesEnabled to geometryGuidesEnabled.
This function was introduced in Esri::ArcGISRuntime 200.6.
See also isGeometryGuidesEnabled.
[since Esri::ArcGISRuntime 200.6] void SnapSettings::setHapticFeedbackEnabled (bool hapticFeedbackEnabled )
Sets the hapticFeedbackEnabled to hapticFeedbackEnabled.
This function was introduced in Esri::ArcGISRuntime 200.6.
See also isHapticFeedbackEnabled.
QList<Esri::ArcGISRuntime::SnapSourceSettings *> SnapSettings::sourceSettings () const
Returns defines the collection of snapping sources and whether or not each is enabled for snapping.
Call syncSourceSettings to populate this collection with a SnapSourceSettings for each valid SnapSource present in the connected MapView. SnapSettings is connected to a MapView via GeometryEditor::snapSettings, and MapView::geometryEditor. If there is no connected MapView, or the map view and the associated map contains no valid SnapSource objects, then the collection will be empty after syncSourceSettings returns.
The order of SnapSourceSettings objects will match the order that the associated SnapSource objects appear in the Map::operationalLayers and MapView::graphicsOverlays collections, with objects from Map::operationalLayers appearing first, followed by MapView::graphicsOverlays objects, in order. The collection will not contain a SnapSourceSettings for any SnapSource which is not yet LoadStatus::Loaded when syncSourceSettings is called.
As snapping is used to maintain data integrity between different sources of data, only SnapSource objects that provide full resolution geometries as considered valid for creating a SnapSourceSettings object - see SnapSource for more information.
void SnapSettings::syncSourceSettings ()
Synchronizes the sourceSettings collection based on SnapSource objects in the currently connected Map.
Call this method to populate sourceSettings with a SnapSourceSettings for each valid SnapSource present in the MapView currently connected to this SnapSettings via GeometryEditor::snapSettings, and MapView::geometryEditor. If there is no connected MapView, or the map view and the associated map contains no SnapSource objects valid for snapping, then the collection will be empty after this method returns.
The order of SnapSourceSettings objects will match the order that the associated SnapSource objects appear in the Map::operationalLayers and MapView::graphicsOverlays collections, with objects from Map::operationalLayers appearing first, followed by MapView::graphicsOverlays objects, in order. The collection will not contain a SnapSourceSettings for any loadable SnapSource which is not yet LoadStatus::Loaded when syncSourceSettings is called.
Subsequent calls will update the existing collection, accounting for SnapSource objects that have been added, removed, or moved since the last call to the same connected map. Any changes made to existing SnapSourceSettings objects, for example setting SnapSourceSettings::isEnabled, will be preserved.
See also sourceSettings.