[tracer] added docs and sip files

python/core/core.sip

@@ -120,6 +120,7 @@
 %Include qgsstatisticalsummary.sip
 %Include qgsstringutils.sip
 %Include qgstolerance.sip
+%Include qgstracer.sip
 %Include qgsvectordataprovider.sip
 %Include qgsvectorfilewriter.sip
 %Include qgsvectorlayer.sip

python/core/qgssnappingutils.sip

@@ -59,15 +59,18 @@ class QgsSnappingUtils : QObject
     /** Find out which strategy is used for indexing - by default hybrid indexing is used */
     IndexingStrategy indexingStrategy() const;
 
-    /** Configure options used when the mode is snap to current layer */
+    /** Configure options used when the mode is snap to current layer or to all layers */
     void setDefaultSettings( int type, double tolerance, QgsTolerance::UnitType unit );
-    /** Query options used when the mode is snap to current layer */
+    /** Query options used when the mode is snap to current layer or to all layers */
     void defaultSettings( int& type /Out/, double& tolerance /Out/, QgsTolerance::UnitType& unit /Out/ );
 
     struct LayerConfig
     {
       LayerConfig( QgsVectorLayer* l, const QgsPointLocator::Types& t, double tol, QgsTolerance::UnitType u );
 
+      bool operator==( const QgsSnappingUtils::LayerConfig& other ) const;
+      bool operator!=( const QgsSnappingUtils::LayerConfig& other ) const;
+
       QgsVectorLayer* layer;
       QgsPointLocator::Types type;
       double tolerance;
@@ -88,6 +91,12 @@ class QgsSnappingUtils : QObject
     /** Read snapping configuration from the project */
     void readConfigFromProject();
 
+  signals:
+    /** Emitted when snapping configuration has been changed
+     * @note added in QGIS 2.14
+     */
+    void configChanged();
+
   protected:
     //! Called when starting to index - can be overridden and e.g. progress dialog can be provided
     virtual void prepareIndexStarting( int count );

python/core/qgstracer.sip

@@ -0,0 +1,74 @@
+/** \ingroup core
+ * Utility class that construct a planar graph from the input vector
+ * layers and provides shortest path search for tracing of existing
+ * features.
+ *
+ * @note added in QGIS 2.14
+ */
+class QgsTracer : QObject
+{
+%TypeHeaderCode
+#include <qgstracer.h>
+%End
+
+  public:
+    QgsTracer();
+    ~QgsTracer();
+
+    //! Get layers used for tracing
+    QList<QgsVectorLayer*> layers() const;
+    //! Set layers used for tracing
+    void setLayers( const QList<QgsVectorLayer*>& layers );
+
+    //! Get CRS used for tracing
+    QgsCoordinateReferenceSystem destinationCrs() const;
+    //! Set CRS used for tracing
+    void setDestinationCrs( const QgsCoordinateReferenceSystem& crs );
+
+    //! Get extent to which graph's features will be limited (empty extent means no limit)
+    QgsRectangle extent() const;
+    //! Set extent to which graph's features will be limited (empty extent means no limit)
+    void setExtent( const QgsRectangle& extent );
+
+    //! Get maximum possible number of features in graph. If the number is exceeded, graph is not created.
+    int maxFeatureCount() const;
+    //! Get maximum possible number of features in graph. If the number is exceeded, graph is not created.
+    void setMaxFeatureCount( int count );
+
+    //! Build the internal data structures. This may take some time
+    //! depending on how big the input layers are. It is not necessary
+    //! to call this method explicitly - it will be called by findShortestPath()
+    //! if necessary.
+    bool init();
+
+    //! Whether the internal data structures have been initialized
+    bool isInitialized() const;
+
+    //! Possible errors that may happen when calling findShortestPath()
+    enum PathError
+    {
+      ErrNone,               //!< No error
+      ErrTooManyFeatures,    //!< Max feature count treshold was reached while reading features
+      ErrPoint1,             //!< Start point cannot be joined to the graph
+      ErrPoint2,             //!< End point cannot be joined to the graph
+      ErrNoPath,             //!< Points are not connected in the graph
+    };
+
+    //! Given two points, find the shortest path and return points on the way.
+    //! The optional "error" argument may receive error code (PathError enum) if it is not null
+    //! @return array of points - trace of linestrings of other features (empty array one error)
+    QVector<QgsPoint> findShortestPath( const QgsPoint& p1, const QgsPoint& p2, QgsTracer::PathError* error /Out/ = nullptr );
+
+    //! Find out whether the point is snapped to a vertex or edge (i.e. it can be used for tracing start/stop)
+    bool isPointSnapped( const QgsPoint& pt );
+
+  protected:
+    //! Allows derived classes to setup the settings just before the tracer is initialized.
+    //! This allows the configuration to be set in a lazy way only when it is really necessary.
+    //! Default implementation does nothing.
+    virtual void configure();
+
+  protected slots:
+    //! Destroy the existing graph structure if any (de-initialize)
+    void invalidateGraph();
+};

python/gui/gui.sip

@@ -91,6 +91,7 @@
 %Include qgsmapcanvasmap.sip
 %Include qgsmapcanvassnapper.sip
 %Include qgsmapcanvassnappingutils.sip
+%Include qgsmapcanvastracer.sip
 %Include qgsmaplayeractionregistry.sip
 %Include qgsmaplayercombobox.sip
 %Include qgsmaplayermodel.sip

python/gui/qgsmapcanvastracer.sip

@@ -0,0 +1,38 @@
+/** \ingroup gui
+ * Extension of QgsTracer that provides extra functionality:
+ *  - automatic updates of own configuration based on canvas settings
+ *  - reporting of issues to the user via message bar
+ *
+ * A simple registry of tracer instances associated to map canvas instances
+ * is kept for convenience. (Map tools do not need to create their local
+ * tracer instances and map canvas API is not "polluted" by this optional
+ * functionality).
+ *
+ * @note added in QGIS 2.14
+ */
+class QgsMapCanvasTracer : QgsTracer
+{
+%TypeHeaderCode
+#include <qgsmapcanvastracer.h>
+%End
+
+  public:
+    //! Create tracer associated with a particular map canvas, optionally message bar for reporting
+    explicit QgsMapCanvasTracer( QgsMapCanvas* canvas, QgsMessageBar* messageBar = 0 );
+    ~QgsMapCanvasTracer();
+
+    //! Access to action that user may use to toggle tracing on/off
+    QAction* actionEnableTracing();
+
+    //! Retrieve instance of this class associated with given canvas (if any).
+    //! The class keeps a simple registry of tracers associated with map canvas
+    //! instances for easier access to the common tracer by various map tools
+    static QgsMapCanvasTracer* tracerForCanvas( QgsMapCanvas* canvas );
+
+    //! Report a path finding error to the user
+    void reportError( QgsTracer::PathError err, bool addingVertex );
+
+  protected:
+    //! Sets configuration from current snapping settings and canvas settings
+    virtual void configure();
+};

src/core/qgstracer.h

@@ -28,7 +28,7 @@ class QgsVectorLayer;
 
 struct QgsTracerGraph;
 
-/**
+/** \ingroup core
  * Utility class that construct a planar graph from the input vector
  * layers and provides shortest path search for tracing of existing
  * features.
@@ -71,20 +71,20 @@ class CORE_EXPORT QgsTracer : public QObject
     //! Whether the internal data structures have been initialized
     bool isInitialized() const { return mGraph != nullptr; }
 
+    //! Possible errors that may happen when calling findShortestPath()
     enum PathError
     {
-      ErrNone,
-      ErrTooManyFeatures,
-      ErrPoint1,
-      ErrPoint2,
-      ErrNoPath,
+      ErrNone,               //!< No error
+      ErrTooManyFeatures,    //!< Max feature count treshold was reached while reading features
+      ErrPoint1,             //!< Start point cannot be joined to the graph
+      ErrPoint2,             //!< End point cannot be joined to the graph
+      ErrNoPath,             //!< Points are not connected in the graph
     };
 
     //! Given two points, find the shortest path and return points on the way.
-    //! If the points are not located on existing vertices or edges,
-    //! search will fail and return empty array. The search will also fail
-    //! if the two points are not connected.
-    QVector<QgsPoint> findShortestPath( const QgsPoint& p1, const QgsPoint& p2, PathError* error = 0 );
+    //! The optional "error" argument may receive error code (PathError enum) if it is not null
+    //! @return array of points - trace of linestrings of other features (empty array one error)
+    QVector<QgsPoint> findShortestPath( const QgsPoint& p1, const QgsPoint& p2, PathError* error = nullptr );
 
     //! Find out whether the point is snapped to a vertex or edge (i.e. it can be used for tracing start/stop)
     bool isPointSnapped( const QgsPoint& pt );
@@ -96,6 +96,7 @@ class CORE_EXPORT QgsTracer : public QObject
     virtual void configure() {}
 
   protected slots:
+    //! Destroy the existing graph structure if any (de-initialize)
     void invalidateGraph();
 
   private:

src/gui/qgsmapcanvastracer.h

@@ -8,14 +8,28 @@ class QgsMapCanvas;
 class QgsMessageBar;
 class QgsMessageBarItem;
 
+/** \ingroup gui
+ * Extension of QgsTracer that provides extra functionality:
+ *  - automatic updates of own configuration based on canvas settings
+ *  - reporting of issues to the user via message bar
+ *
+ * A simple registry of tracer instances associated to map canvas instances
+ * is kept for convenience. (Map tools do not need to create their local
+ * tracer instances and map canvas API is not "polluted" by this optional
+ * functionality).
+ *
+ * @note added in QGIS 2.14
+ */
 class GUI_EXPORT QgsMapCanvasTracer : public QgsTracer
 {
     Q_OBJECT
 
   public:
+    //! Create tracer associated with a particular map canvas, optionally message bar for reporting
     explicit QgsMapCanvasTracer( QgsMapCanvas* canvas, QgsMessageBar* messageBar = 0 );
     ~QgsMapCanvasTracer();
 
+    //! Access to action that user may use to toggle tracing on/off
     QAction* actionEnableTracing() { return mActionEnableTracing; }
 
     //! Retrieve instance of this class associated with given canvas (if any).
@@ -27,6 +41,7 @@ class GUI_EXPORT QgsMapCanvasTracer : public QgsTracer
     void reportError( PathError err, bool addingVertex );
 
   protected:
+    //! Sets configuration from current snapping settings and canvas settings
     virtual void configure();
 
   private slots: