Skip to content

Commit

Permalink
Browse files Browse the repository at this point in the history
[tracer] added docs and sip files
  • Loading branch information
wonder-sk committed Jan 11, 2016
1 parent 726fcfc commit 3883a2e
Show file tree
Hide file tree
Showing 7 changed files with 151 additions and 12 deletions.
1 change: 1 addition & 0 deletions python/core/core.sip
Expand Up @@ -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
Expand Down
13 changes: 11 additions & 2 deletions python/core/qgssnappingutils.sip
Expand Up @@ -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;
Expand All @@ -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 );
Expand Down
74 changes: 74 additions & 0 deletions 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();
};
1 change: 1 addition & 0 deletions python/gui/gui.sip
Expand Up @@ -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
Expand Down
38 changes: 38 additions & 0 deletions 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();
};
21 changes: 11 additions & 10 deletions src/core/qgstracer.h
Expand Up @@ -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.
Expand Down Expand Up @@ -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 );
Expand All @@ -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:
Expand Down
15 changes: 15 additions & 0 deletions src/gui/qgsmapcanvastracer.h
Expand Up @@ -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).
Expand All @@ -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:
Expand Down

0 comments on commit 3883a2e

Please sign in to comment.