Controls interactive snapping functionality for the GeometryEditor. More...
| Header | #include <Snap |
| Since | Esri |
| Inherits | Esri |
Public Functions
| Snap | |
| virtual | ~ |
| bool | is |
(since Esri bool | is |
(since Esri bool | is |
(since Esri bool | is |
| void | set |
(since Esri void | set |
(since Esri void | set |
(since Esri void | set |
| Q | source |
| void | sync |
(since Esri void | sync |
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. - Or call syncSourceSettings(Esri::ArcGISRuntime::SnapRules*, Esri::ArcGISRuntime::SnapSourceEnablingBehavior), to configure rule-based snapping behavior to limit snaps based on connectivity rules stored in a utility network.
- 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 or syncSourceSettings(Esri::ArcGISRuntime::SnapRules*, Esri::ArcGISRuntime::SnapSourceEnablingBehavior) to refresh the collection of snap sources at any time.
You can snap to SnapSource objects that are contained in the MapView associated with the GeometryEditor, and are visible. If you configured rule-based snapping, then the features that you can snap to will additionally be limited by the SnapRules you set.
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, SnapSource, and SnapRules.
Member Function Documentation
[explicit] SnapSettings::SnapSettings (QObject *parent = nullptr)
Creates a default SnapSettings.
- parent - The optional parent QObject.
[override virtual noexcept] 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.
Setting this value temporarily to false may be useful if you wish to temporarily disable all snapping without affecting how snapping is currently configured. For example, changing this property will not affect the value of SnapSourceSettings::isEnabled, or if rule-based snapping has been configured by using SnapRules.
[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. The default value is true.
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 when the GeometryEditor::snapChanged event happens with a SnapState of SnapState::SnappedToFeature or SnapState.snappedToGeometryGuide. You can alternatively implement your own custom haptic feedback, for example if you wish to change the type of haptic feedback, or include haptic feedback for SnapState::Unsnapped. To do this, set this boolean to false, and perform your custom haptic feedback by listening to the GeometryEditor::snapChanged event.
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
Defines and returns a QList of snapping sources and whether or not each is enabled for snapping.
Call syncSourceSettings to populate the QList with a SnapSourceSettings for each valid SnapSource present in the connected MapView. To use rule-based snapping, call syncSourceSettings(Esri::ArcGISRuntime::SnapRules*, Esri::ArcGISRuntime::SnapSourceEnablingBehavior) instead.
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 QList will be empty after the synchronization call 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.
For SnapSourceSettings objects that correspond to a SubtypeFeatureLayer, SnapSourceSettings::source returns a QList of separate SnapSourceSettings objects representing each SubtypeSublayer.
After synchronization, the Qlist will not contain a SnapSourceSettings for any loadable SnapSource which is not yet LoadStatus::Loaded.
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 QList 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 QList 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.
Calling this method removes any rule-based snapping configuration that was previously set by calling syncSourceSettings(Esri::ArcGISRuntime::SnapRules*, Esri::ArcGISRuntime::SnapSourceEnablingBehavior), and the SnapSourceSettings::ruleBehavior of all the SnapSourceSettings objects will be SnapRuleBehavior::None.
See also sourceSettings and SnapSourceSettings.
[since Esri::ArcGISRuntime 200.7] void SnapSettings::syncSourceSettings (Esri::ArcGISRuntime::SnapRules *rules, Esri::ArcGISRuntime::SnapSourceEnablingBehavior snapSourceEnablingBehavior )
Synchronizes the sourceSettings QList based on SnapSource objects in the currently connected Map and the given SnapRules which may affect each of them.
- rules - The rules to apply to the SnapSource objects.
- snapSourceEnablingBehavior - Whether to set SnapSourceSettings::isEnabled based on the given SnapRules, or preserve the existing values.
Call this method to configure rule-based snapping. Similarly to syncSourceSettings, this method will populate sourceSettings with a SnapSourceSettings for each valid SnapSource present in the MapView currently connected to this SnapSettings via GeometryEditor::snapSettings, and MapView::geometryEditor. In addition to populating the collection, the given SnapRules will be applied to each SnapSourceSettings, setting SnapSourceSettings::ruleBehavior appropriately for those rules. SnapRules are created by calling SnapRules::createAsync(Esri::ArcGISRuntime::UtilityNetwork*, Esri::ArcGISRuntime::UtilityAssetType*, QObject*), specifying a particular UtilityAssetType that matches the feature whose geometry will be edited using the GeometryEditor. When editing features in a utility network, it, it is important to ensure that you have synchronized the snap sources with appropriate snap rules, so that the interactive snapping behavior is configured correctly for editing that asset type.
When using rule-based snapping, SnapSourceSettings::ruleBehavior may limit or prevent snapping to a snap source, regardless of its SnapSourceSettings::isEnabled value. Values of SnapSourceSettings::isEnabled will be affected by the given value of SnapSourceEnablingBehavior.
When rule-based snapping is configured, any edits made by interactively snapping to a SnapSource geometry will use the z-value of the feature geometry, if that snap source geometry is z-aware.
The sourceSettings QList includes all valid snap sources in the map after synchronization, and therefore may include snap sources from data that is unrelated to the UtilityNetwork given when creating the SnapRules, for example graphics overlays or feature layers from separate data sources. If there is no connected MapView, or the map view and the associated map contains no SnapSource objects valid for snapping, then the QList 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 synchronization occurs.
This function was introduced in Esri::ArcGISRuntime 200.7.
See also sourceSettings and Geometry::hasZ.