/** \ingroup gui
 * This class reads the snapping properties from the current project and
 * configures a QgsSnapper to perform the snapping.
 * Snapping can be done to the active layer  (useful for selecting a vertex to
 * manipulate) or to background layers
 */
class QgsMapCanvasSnapper
{
%TypeHeaderCode
#include <qgsmapcanvassnapper.h>
%End

  public:
    /** Constructor
     @param canvas the map canvas to snap to*/
    QgsMapCanvasSnapper( QgsMapCanvas* canvas );

    QgsMapCanvasSnapper();

    ~QgsMapCanvasSnapper();

    /** Does a snap to the current layer. Uses snap mode
     * QgsSnapper::SnapWithResultsForSamePosition if topological editing is enabled
     * and QgsSnapper::SnapWithOneResult_BY_SEGMENT if not. As this method is usually used to
     * find vertices/segments for editing operations, it uses the search radius for vertex
     * editing from the qgis options.
     * @param p start point of the snap (in pixel coordinates)
     * @param results list to which the results are appended
     * @param snap_to snap to vertex or to segment
     * @param snappingTol snapping tolerance. -1 means that the search radius for vertex edits is taken
     * @param excludePoints a list with (map coordinate) points that should be excluded in the snapping result. Useful e.g. for vertex moves where a vertex should not be snapped to its original position
     * @param allResutInTolerance return all thew results in the tolerance
     */
    int snapToCurrentLayer( QPoint p, QList<QgsSnappingResult>& results /Out/, QgsSnapper::SnappingType snap_to, double snappingTol = -1, const QList<QgsPoint>& excludePoints = QList<QgsPoint>() );
    /** Snaps to the background layers. This method is useful to align the features of the
     * edited layers to those of other layers (as described in the project properties).
     * Uses snap mode QgsSnapper::SnapWithOneResult. Therefore, only the
     * closest result is returned.
     * @param p start point of the snap (in pixel coordinates)
     * @param results snapped points
     * @param excludePoints a list with (map coordinate) points that should be excluded in the snapping result. Useful e.g. for vertex moves where a vertex should not be snapped to its original position
     * @return 0 in case of success
     */
    int snapToBackgroundLayers( QPoint p, QList<QgsSnappingResult>& results /Out/, const QList<QgsPoint>& excludePoints = QList<QgsPoint>() );

    // @note not available in python bindings
    // int snapToBackgroundLayers( const QgsPoint& point, QList<QgsSnappingResult>& results, const QList<QgsPoint>& excludePoints = QList<QgsPoint>() );

    void setMapCanvas( QgsMapCanvas* canvas );

  private:

    QgsMapCanvasSnapper( const QgsMapCanvasSnapper& rh );
};