QgsSnappingUtils class

This class has all the configuration of snapping and can return answers to snapping queries.

Reference

Internally, it keeps a cache of QgsPointLocator instances for multiple layers.

Currently it supports the following queries:

snapToMap() - has multiple modes of operation
snapToCurrentLayer() For more complex queries it is possible to use locatorForLayer() method that returns point locator instance with layer's indexed data.

Indexing strategy determines how fast the queries will be and how much memory will be used.

When working with map canvas, it may be useful to use derived class QgsMapCanvasSnappingUtils which keeps the configuration in sync with map canvas (e.g. current view, active layer).

Derived classes

class QgsMapCanvasSnappingUtils: Snapping utils instance that is connected to a canvas and updates the configuration (map settings + current layer) whenever that is changed in the canvas.

Public types

struct LayerConfig: Configures how a certain layer should be handled in a snapping operation.
enum IndexingStrategy { IndexAlwaysFull, IndexNeverFull, IndexHybrid, IndexExtent }

Constructors, destructors, conversion operators

QgsSnappingUtils(QObject* parent = nullptr, bool enableSnappingForInvisibleFeature = true): Constructor for QgsSnappingUtils.

Public functions

auto config() const -> QgsSnappingConfig: The snapping configuration controls the behavior of this object.
auto currentLayer() const -> QgsVectorLayer*: The current layer used if mode is SnapCurrentLayer.
auto dump() -> QString: Gets extra information about the instance.
auto indexingStrategy() const -> IndexingStrategy: Find out which strategy is used for indexing - by default hybrid indexing is used.
auto layers() const -> QList<QgsSnappingUtils::LayerConfig>: Query layers used for snapping.
auto locatorForLayer(QgsVectorLayer* vl) -> QgsPointLocator*: Gets a point locator for the given layer. If such locator does not exist, it will be created.
void setCurrentLayer(QgsVectorLayer* layer): Sets current layer so that if mode is SnapCurrentLayer we know which layer to use.
void setEnableSnappingForInvisibleFeature(bool enable): Set if invisible features must be snapped or not.
void setIndexingStrategy(IndexingStrategy strategy): Sets a strategy for indexing geometry data - determines how fast and memory consuming the data structures will be.
void setMapSettings(const QgsMapSettings& settings): Assign current map settings to the utils - used for conversion between screen coords to map coords.
auto snapToCurrentLayer(QPoint point, QgsPointLocator::Types type, QgsPointLocator::MatchFilter* filter = nullptr) -> QgsPointLocator::Match: Snap to current layer.
auto snapToMap(QPoint point, QgsPointLocator::MatchFilter* filter = nullptr) -> QgsPointLocator::Match: Snap to map according to the current configuration. Optional filter allows discarding unwanted matches.

Signals

void configChanged(const QgsSnappingConfig& snappingConfig): Emitted when the snapping settings object changes.

Public slots

void setConfig(const QgsSnappingConfig& snappingConfig): The snapping configuration controls the behavior of this object.
void toggleEnabled(): Toggles the state of snapping.

Protected functions

void clearAllLocators(): Deletes all existing locators (e.g. when destination CRS has changed and we need to reindex)
void prepareIndexProgress(int index) virtual: Called when finished indexing a layer. When index == count the indexing is complete.
void prepareIndexStarting(int count) virtual: Called when starting to index - can be overridden and e.g. progress dialog can be provided.

Enum documentation

enum QgsSnappingUtils::IndexingStrategy

Enumerators
IndexAlwaysFull	For all layers build index of full extent. Uses more memory, but queries are faster.
IndexNeverFull	For all layers only create temporary indexes of small extent. Low memory usage, slower queries.
IndexHybrid	For "big" layers using IndexNeverFull, for the rest IndexAlwaysFull. Compromise between speed and memory usage.
IndexExtent	For all layer build index of extent given in map settings.

Function documentation

QString QgsSnappingUtils::dump()

Gets extra information about the instance.

void QgsSnappingUtils::setEnableSnappingForInvisibleFeature(bool enable)

Set if invisible features must be snapped or not.

Parameters
enable	Enable or not this feature

QgsPointLocator::Match QgsSnappingUtils::snapToCurrentLayer(QPoint point, QgsPointLocator::Types type, QgsPointLocator::MatchFilter* filter = nullptr)

Snap to current layer.

Snap to current layer

void QgsSnappingUtils::toggleEnabled() public slot

Toggles the state of snapping.