A table of snapping rules to apply to one or more SnapSource objects. More...
| Header: | #include <SnapRules.h> |
| Since: | Esri::ArcGISRuntime 200.7 |
| Inherits: | Esri::ArcGISRuntime::Object |
Public Functions
| virtual | ~SnapRules() override |
| Esri::ArcGISRuntime::SnapRuleBehavior | ruleBehavior(Esri::ArcGISRuntime::SnapSource *source) const |
Static Public Members
| QFuture<Esri::ArcGISRuntime::SnapRules *> | createAsync(Esri::ArcGISRuntime::UtilityNetwork *utilityNetwork, Esri::ArcGISRuntime::UtilityAssetType *assetType, QObject *parent = nullptr) |
| QFuture<Esri::ArcGISRuntime::SnapRules *> | createAsync(Esri::ArcGISRuntime::UtilityNetwork *utilityNetwork, Esri::ArcGISRuntime::FeatureTable *featureTable, const QVariantMap &attributes, QObject *parent = nullptr) |
Detailed Description
When using the GeometryEditor to edit the geometry of features that participate in a utility network, rule-based snapping can be configured on SnapSettings. Utility networks rely on geometric coincident-based connectivity to provide pathways for resources, and snapping can be a useful tool to help maintain those pathways. A utility network contains rules for connectivity, and using rule-based snapping respects the rules for the specific feature type being edited, based on its asset type and asset group, helping maintain network connectivity.
To use rule-based snapping to edit a specific UtilityAssetType:
- Connect a GeometryEditor to the map view, and ensure the MapView::map is set and contains the pertinent utility network(s).
- See GeometryEditor for more information about general GeometryEditor set up and configuration.
- The Map::operationalLayers collection should include, at a minimum, the layer you wish to edit, and the layers that have connectivity with the edit layer that will be used for snapping. The utility network data model makes use of sublayers, and adding the layers using SubtypeFeatureLayer offers the ability to change visibility and enable or disable snapping for specific subtypes. If you are programmatically adding layers to the map, ensure that you use a ServiceGeodatabase when adding multiple layers from the same feature service.
- Get the UtilityNetwork that you will be working with.
- If you are opening a web map or MobileMapPackage, the Map::utilityNetworks collection may already contain the relevant utility network. Alternatively you may get the utility network from the same Geodatabase that backs your operational layers, or call UtilityNetwork::UtilityNetwork(const QUrl&, Map*, QObject*) to create the network from a feature service URL and associate it with your Map.
- Create a SnapRules object appropriate for use with the utility network and asset type you will edit:
- If you know the UtilityAssetType, you can pass this to createAsync(UtilityNetwork*, UtilityAssetType*, QObject*). For example, if you have identified an existing feature to be edited, you can call UtilityNetwork::createElementWithArcGISFeature(ArcGISFeature*, UtilityTerminal*, QObject*), then get UtilityElement::assetType.
- If you have a set of Feature::attributes, you can pass these to createAsync(UtilityNetwork*, FeatureTable*, const QVariantMap&, QObject*). For example, you may be creating a new feature from a FeatureTemplate.
- Get the GeometryEditor::snapSettings, and ensure SnapSettings::isEnabled and SnapSettings::isFeatureSnappingEnabled are
true. - Call SnapSettings::syncSourceSettings(SnapRules*, SnapSourceEnablingBehavior), passing in the snap rules you created previously, and SnapSourceEnablingBehavior::SetFromRules.
- If your workflow has previously synchronized snap sources, consider if SnapSourceEnablingBehavior::Preserve is more appropriate instead.
- Call GeometryEditor::start(const Geometry&) passing in the GeoElement::geometry of the feature you wish to edit, or GeometryEditor::start(GeometryType) if you have no initial geometry.
- The user can interactively edit the feature geometry.
- When edits are complete, set the feature geometry with the result of GeometryEditor::stop.
After calling SnapSettings::syncSourceSettings(Esri::ArcGISRuntime::SnapRules*, Esri::ArcGISRuntime::SnapSourceEnablingBehavior), each SnapSourceSettings in SnapSettings::sourceSettings is configured with the appropriate SnapSourceSettings::ruleBehavior based on the connectivity rules specified in the utility network. For details, see SnapRuleBehavior.
Ensure that your UtilityNetwork and the layers in the map that you will snap to use the same feature tables. For more information, see createAsync(Esri::ArcGISRuntime::UtilityNetwork*, Esri::ArcGISRuntime::UtilityAssetType*, QObject*).
Utility network features are z-aware - each feature geometry includes z-values (Geometry::hasZ is true). Two points, or vertices, are geometrically coincident when the x, y, and z-values of the points or vertices are equal. When you configure rule-based snapping, by calling SnapSettings::syncSourceSettings(Esri::ArcGISRuntime::SnapRules*, Esri::ArcGISRuntime::SnapSourceEnablingBehavior), any edits made using snapping will use the z-value of the feature geometry from the SnapSource, if that snap source geometry is z-aware. If multiple snap candidates exist at the same location, then the default z-value is used instead.
See also SnapSettings::syncSourceSettings(Esri::ArcGISRuntime::SnapRules*, Esri::ArcGISRuntime::SnapSourceEnablingBehavior), SnapSettings, SnapSource, UtilityNetwork, UtilityAssetType, and Network Rules ArcGIS Pro help topic.
Member Function Documentation
[override virtual noexcept] SnapRules::~SnapRules ()
Destructor.
[static] QFuture<Esri::ArcGISRuntime::SnapRules *> SnapRules::createAsync (Esri::ArcGISRuntime::UtilityNetwork *utilityNetwork , Esri::ArcGISRuntime::UtilityAssetType *assetType , QObject *parent = nullptr)
Analyzes a UtilityNetwork for the rules which allow or limit the snapping of the given UtilityAssetType to other features, and returns a SnapRules which can be used to configure interactive snapping behavior in a GeometryEditor.
- utilityNetwork - The UtilityNetwork object to analyze for its connectivity rules relating to the given assetType.
- assetType - The asset type of the feature geometry that will be edited in the GeometryEditor. Connectivity rules involving this asset type are included in the returned SnapRules.
- parent - The optional parent QObject.
To configure rule-based snapping, use this method to create a SnapRules that you can then pass to SnapSettings::syncSourceSettings(Esri::ArcGISRuntime::SnapRules*, Esri::ArcGISRuntime::SnapSourceEnablingBehavior). This method is ideal for creating SnapRules when you have a reference to the UtilityAssetType, for example if you have identified an existing feature to be edited, you can call UtilityNetwork::createElementWithArcGISFeature(ArcGISFeature*, UtilityTerminal*, QObject*), then get UtilityElement::assetType to pass in.
Ensure that the feature tables underlying the given UtilityNetwork are the same used by operational layers in the map, so that the SnapRules are based on the same underlying data sets.
If your map view displays a web map, or is set from a MobileMapPackage, the Map::utilityNetworks collection may already contain the relevant utility network object to use. Alternatively you may get the utility network from the same Geodatabase that backs your operational layers, or call UtilityNetwork::UtilityNetwork(const QUrl&, Esri::ArcGISRuntime::Map*, QObject*) to create the network from a feature service URL and associate it with your Map.
Ensure that the UtilityAssetType is from the given UtilityNetwork.
This method returns a QFuture for the asynchronous operation. Use future.then() to continue processing when the operation completes. Use future.onFailed() to handle exceptions of type ErrorException.
See Working with QFuture for further details.
See also SnapSettings::syncSourceSettings(Esri::ArcGISRuntime::SnapRules*, Esri::ArcGISRuntime::SnapSourceEnablingBehavior) and UtilityConnectivityPolicy.
[static] QFuture<Esri::ArcGISRuntime::SnapRules *> SnapRules::createAsync (Esri::ArcGISRuntime::UtilityNetwork *utilityNetwork , Esri::ArcGISRuntime::FeatureTable *featureTable , const QVariantMap &attributes, QObject *parent = nullptr)
Analyzes a UtilityNetwork for the rules which allow or limit the snapping of a feature in the given featureTable with the given attributes, and returns a SnapRules which can be used to configure interactive snapping behavior in a GeometryEditor.
- utilityNetwork - The UtilityNetwork object to analyze for its connectivity rules relating to a feature of the asset type described by the given featureTable and attributes.
- featureTable - The feature table that will contain the feature whose geometry will be edited in the GeometryEditor using the returned SnapRules. Must be part of the given utilityNetwork.
- attributes - The attributes for the feature whose geometry will be edited in the GeometryEditor using the returned SnapRules.
Note: The key of the attributes map is of type QString. It is not case-sensitive as it essentially represents a Fieldname.
- parent - The optional parent QObject.
To configure rule-based snapping, use this method to create a SnapRules that you can then pass to SnapSettings::syncSourceSettings(Esri::ArcGISRuntime::SnapRules*, Esri::ArcGISRuntime::SnapSourceEnablingBehavior). This method is ideal for creating SnapRules where you have a set of attributes, for example, if you are creating a new feature from a FeatureTemplate. Connectivity rules involving the UtilityAssetType of the feature are described by those attributes are included in the resulting rules.
Ensure that the feature tables underlying the given UtilityNetwork are the same used by operational layers in the map, so that the SnapRules are based on the same underlying data sets.
If your map view displays a web map, or is set from a MobileMapPackage, the Map::utilityNetworks collection may already contain the relevant utility network object to use. Alternatively you may get the utility network from the same Geodatabase that backs your operational layers, or call UtilityNetwork::UtilityNetwork(const QUrl&, Esri::ArcGISRuntime::Map*, QObject*) to create the network from a feature service URL and associate it with your Map.
This method returns a QFuture for the asynchronous operation. Use future.then() to continue processing when the operation completes. Use future.onFailed() to handle exceptions of type ErrorException.
See Working with QFuture for further details.
See also SnapSettings::syncSourceSettings(Esri::ArcGISRuntime::SnapRules*, Esri::ArcGISRuntime::SnapSourceEnablingBehavior) and UtilityConnectivityPolicy.
Esri::ArcGISRuntime::SnapRuleBehavior SnapRules::ruleBehavior (Esri::ArcGISRuntime::SnapSource *source) const
Returns the applicable SnapRuleBehavior for the given SnapSource.
- source - The SnapSource to retrieve snap rules for.
This method can be used to check SnapRuleBehavior of a valid SnapSource directly, without needing to synchronize the SnapSettings::sourceSettings collection on SnapSettings and get SnapSourceSettings::ruleBehavior.
See also SnapSourceSettings::ruleBehavior.