Skip to content
Permalink
Browse files
Cleanup API docs for QgsCadUtils
  • Loading branch information
nyalldawson committed Sep 13, 2021
1 parent 93f2756 commit 50ab8c1c81540424c5e92ee67f6ad7698d5f252d
@@ -23,43 +23,59 @@ The :py:class:`QgsCadUtils` class provides routines for CAD editing.
%End
public:

struct AlignMapPointConstraint
{
AlignMapPointConstraint( bool locked = false, bool relative = false, double value = 0 );

bool locked;
bool relative;
double value;
};

struct AlignMapPointOutput
{
bool valid;
class AlignMapPointConstraint
{
%Docstring(signature="appended")
Structure with details of one constraint

QgsPointXY finalMapPoint;
.. versionadded:: 3.0
%End

QgsPointLocator::Match snapMatch;
%TypeHeaderCode
#include "qgscadutils.h"
%End
public:

QgsPointLocator::Match edgeMatch;
AlignMapPointConstraint( bool locked = false, bool relative = false, double value = 0 );
%Docstring
Constructor for AlignMapPointConstraint.
%End

double softLockCommonAngle;
bool locked;
bool relative;
double value;
};

class AlignMapPointContext
class AlignMapPointOutput
{
%Docstring(signature="appended")
Class defining all constraints for :py:func:`~QgsCadUtils.alignMapPoint` method
Structure returned from :py:func:`~QgsCadUtils.alignMapPoint` method

.. versionadded:: 3.0
%End

%TypeHeaderCode
#include "qgscadutils.h"
%End
public:

This class was a structure before QGIS 3.22.
bool valid;

mCadPointList is now a private QList< :py:class:`QgsPoint` >.
Use getters/setters.
QgsPointXY finalMapPoint;

.. seealso:: :py:func:`cadPoints`
QgsPointLocator::Match snapMatch;

.. seealso:: :py:func:`setCadPoints`
QgsPointLocator::Match edgeMatch;

.. versionadded:: 3.22
double softLockCommonAngle;
};

class AlignMapPointContext
{
%Docstring(signature="appended")
Defines constraints for the :py:func:`QgsCadUtils.alignMapPoint()` method.

.. versionadded:: 3.0
%End

%TypeHeaderCode
@@ -82,27 +98,36 @@ Use getters/setters.

QList< QgsPoint > cadPoints() const;
%Docstring
Returns a list of points from mCadPointList.
Returns the list of recent CAD points in map coordinates.

These are used to turn relative constraints to absolute. The first
point is the most recent point.

.. seealso:: :py:func:`setCadPoints`

.. versionadded:: 3.22
%End
void setCadPoints( const QList< QgsPoint> &list );
void setCadPoints( const QList< QgsPoint> &points );
%Docstring
Set points to mCadPointList
Sets the list of recent CAD ``points`` (in map coordinates).

:param list: points to mCadPointList
.. seealso:: :py:func:`cadPoints`

.. versionadded:: 3.22
%End
void setCadPoint( const QgsPoint &point, int index );
void setCadPoint( int index, const QgsPoint &point );
%Docstring
Set ``point`` at ``index`` to mCadPointList
Sets the recent CAD point at the specified ``index`` to ``point`` (in map coordinates).

.. seealso:: :py:func:`cadPoint`

.. versionadded:: 3.22
%End
QgsPoint cadPoint( int index ) const;
%Docstring
Get ``point`` at ``index`` from mCadPointList
Returns the recent CAD point at the specified ``index`` (in map coordinates).

.. seealso:: :py:func:`setCadPoint`

.. versionadded:: 3.22
%End
@@ -317,8 +317,8 @@ The last point.
Helper for the CAD point list. The CAD point list is the list of points
currently digitized. It contains both "normal" points and intermediate points (construction mode).

.. deprecated:: QGIS 3.22
- will be removed in QGIS 4.0. Use the variant which returns :py:class:`QgsPoint` object instead of :py:class:`QgsPointXY`.
.. deprecated:: QGIS 3.22.
Use :py:func:`~QgsAdvancedDigitizingDockWidget.currentPointV2` instead.
%End
QgsPoint previousPointV2( bool *exists = 0 ) const;
%Docstring
@@ -333,8 +333,8 @@ The previous point.
Helper for the CAD point list. The CAD point list is the list of points
currently digitized. It contains both "normal" points and intermediate points (construction mode).

.. deprecated:: QGIS 3.22
- will be removed in QGIS 4.0. Use the variant which returns :py:class:`QgsPoint` object instead of :py:class:`QgsPointXY`.
.. deprecated:: QGIS 3.22.
Use :py:func:`~QgsAdvancedDigitizingDockWidget.previousPointV2` instead.
%End
QgsPoint penultimatePointV2( bool *exists = 0 ) const;
%Docstring
@@ -349,8 +349,8 @@ The penultimate point.
Helper for the CAD point list. The CAD point list is the list of points
currently digitized. It contains both "normal" points and intermediate points (construction mode).

.. deprecated:: QGIS 3.22
- will be removed in QGIS 4.0. Use the variant which returns :py:class:`QgsPoint` object instead of :py:class:`QgsPointXY`.
.. deprecated:: QGIS 3.22.
Use :py:func:`~QgsAdvancedDigitizingDockWidget.penultimatePointV2` instead.
%End
int pointsCount() const;
%Docstring
@@ -527,8 +527,8 @@ when a constraint is toggled.

:param point: The last known digitizing point. Can be used to emulate a mouse event.

.. deprecated:: QGIS 3.22
- No longer used, will be removed in QGIS 4.0. Use the variant which emits :py:class:`QgsPoint` object instead of :py:class:`QgsPointXY`.
.. deprecated:: QGIS 3.22.
No longer used, will be removed in QGIS 4.0. Use pointChangedV2 instead.
%End


@@ -33,68 +33,74 @@ class CORE_EXPORT QgsCadUtils
{
public:

//! Structure with details of one constraint
struct AlignMapPointConstraint
/**
* \brief Structure with details of one constraint
* \ingroup core
* \since QGIS 3.0
*/
class AlignMapPointConstraint
{
AlignMapPointConstraint( bool locked = false, bool relative = false, double value = 0 )
: locked( locked )
, relative( relative )
, value( value )
{}

//! Whether the constraint is active, i.e. should be considered
bool locked;
//! Whether the value is relative to previous value
bool relative;
//! Numeric value of the constraint (coordinate/distance in map units or angle in degrees)
double value;
public:

/**
* Constructor for AlignMapPointConstraint.
*/
AlignMapPointConstraint( bool locked = false, bool relative = false, double value = 0 )
: locked( locked )
, relative( relative )
, value( value )
{}

//! Whether the constraint is active, i.e. should be considered
bool locked;
//! Whether the value is relative to previous value
bool relative;
//! Numeric value of the constraint (coordinate/distance in map units or angle in degrees)
double value;
};

//! Structure returned from alignMapPoint() method
struct AlignMapPointOutput
/**
* \brief Structure returned from alignMapPoint() method
* \ingroup core
* \since QGIS 3.0
*/
class AlignMapPointOutput
{
//! Whether the combination of constraints is actually valid
bool valid;

//! map point aligned according to the constraints
QgsPointXY finalMapPoint;

/**
* Snapped point - only valid if actually used for something
* \since QGIS 3.14
*/
QgsPointLocator::Match snapMatch;

/**
* Snapped segment - only valid if actually used for something
* \deprecated will be removed in QGIS 4.0 - use snapMatch instead
*/
QgsPointLocator::Match edgeMatch;

//! Angle (in degrees) to which we have soft-locked ourselves (if not set it is -1)
double softLockCommonAngle;
public:

//! Whether the combination of constraints is actually valid
bool valid;

//! map point aligned according to the constraints
QgsPointXY finalMapPoint;

/**
* Snapped point - only valid if actually used for something
* \since QGIS 3.14
*/
QgsPointLocator::Match snapMatch;

/**
* Snapped segment - only valid if actually used for something
* \deprecated will be removed in QGIS 4.0 - use snapMatch instead
*/
QgsPointLocator::Match edgeMatch;

//! Angle (in degrees) to which we have soft-locked ourselves (if not set it is -1)
double softLockCommonAngle;
};

/**
* \ingroup core
* \brief Class defining all constraints for alignMapPoint() method
*
* This class was a structure before QGIS 3.22.
*
* mCadPointList is now a private QList< QgsPoint >.
* Use getters/setters.
*
* \see cadPoints
* \see setCadPoints
*
* \since QGIS 3.22
* \brief Defines constraints for the QgsCadUtils::alignMapPoint() method.
* \since QGIS 3.0
*/
class AlignMapPointContext
{
public:
//! Snapping utils that will be used to snap point to map. Must not be NULLPTR.
QgsSnappingUtils *snappingUtils = nullptr;
//! Map units/pixel ratio from map canvas. Needed for
//! Map units/pixel ratio from map canvas.
double mapUnitsPerPixel;

//! Constraint for X coordinate
@@ -127,26 +133,36 @@ class CORE_EXPORT QgsCadUtils
SIP_SKIP void dump() const;

/**
* Returns a list of points from mCadPointList.
* Returns the list of recent CAD points in map coordinates.
*
* These are used to turn relative constraints to absolute. The first
* point is the most recent point.
*
* \see setCadPoints()
* \since QGIS 3.22
*/
QList< QgsPoint > cadPoints() const { return mCadPointList; } ;

/**
* Set points to mCadPointList
* \param list points to mCadPointList
* Sets the list of recent CAD \a points (in map coordinates).
*
* \see cadPoints()
* \since QGIS 3.22
*/
void setCadPoints( const QList< QgsPoint> &list ) { mCadPointList = list; };
void setCadPoints( const QList< QgsPoint> &points ) { mCadPointList = points; };

/**
* Set \a point at \a index to mCadPointList
* Sets the recent CAD point at the specified \a index to \a point (in map coordinates).
*
* \see cadPoint()
* \since QGIS 3.22
*/
void setCadPoint( const QgsPoint &point, int index ) { mCadPointList[index] = point; };
void setCadPoint( int index, const QgsPoint &point ) { mCadPointList[index] = point; };

/**
* Get \a point at \a index from mCadPointList
* Returns the recent CAD point at the specified \a index (in map coordinates).
*
* \see setCadPoint()
* \since QGIS 3.22
*/
QgsPoint cadPoint( int index ) const { return mCadPointList[index]; };
@@ -331,7 +331,7 @@ class GUI_EXPORT QgsAdvancedDigitizingDockWidget : public QgsDockWidget, private
* The last point.
* Helper for the CAD point list. The CAD point list is the list of points
* currently digitized. It contains both "normal" points and intermediate points (construction mode).
* \deprecated since QGIS 3.22 - will be removed in QGIS 4.0. Use the variant which returns QgsPoint object instead of QgsPointXY.
* \deprecated since QGIS 3.22. Use currentPointV2() instead.
*/
Q_DECL_DEPRECATED QgsPointXY currentPoint( bool *exists = nullptr ) const SIP_DEPRECATED { return currentPointV2( exists ); };

@@ -346,7 +346,7 @@ class GUI_EXPORT QgsAdvancedDigitizingDockWidget : public QgsDockWidget, private
* The previous point.
* Helper for the CAD point list. The CAD point list is the list of points
* currently digitized. It contains both "normal" points and intermediate points (construction mode).
* \deprecated since QGIS 3.22 - will be removed in QGIS 4.0. Use the variant which returns QgsPoint object instead of QgsPointXY.
* \deprecated since QGIS 3.22. Use previousPointV2() instead.
*/
Q_DECL_DEPRECATED QgsPointXY previousPoint( bool *exists = nullptr ) const SIP_DEPRECATED { return previousPointV2( exists ); };

@@ -361,7 +361,7 @@ class GUI_EXPORT QgsAdvancedDigitizingDockWidget : public QgsDockWidget, private
* The penultimate point.
* Helper for the CAD point list. The CAD point list is the list of points
* currently digitized. It contains both "normal" points and intermediate points (construction mode).
* \deprecated since QGIS 3.22 - will be removed in QGIS 4.0. Use the variant which returns QgsPoint object instead of QgsPointXY.
* \deprecated since QGIS 3.22. Use penultimatePointV2() instead.
*/
Q_DECL_DEPRECATED QgsPointXY penultimatePoint( bool *exists = nullptr ) const SIP_DEPRECATED { return penultimatePointV2( exists ); };

@@ -502,7 +502,7 @@ class GUI_EXPORT QgsAdvancedDigitizingDockWidget : public QgsDockWidget, private
* when a constraint is toggled.
*
* \param point The last known digitizing point. Can be used to emulate a mouse event.
* \deprecated since QGIS 3.22 - No longer used, will be removed in QGIS 4.0. Use the variant which emits QgsPoint object instead of QgsPointXY.
* \deprecated since QGIS 3.22. No longer used, will be removed in QGIS 4.0. Use pointChangedV2 instead.
*/
Q_DECL_DEPRECATED void pointChanged( const QgsPointXY &point ) SIP_DEPRECATED;

@@ -231,7 +231,7 @@ void TestQgsCadUtils::testCommonAngle()
// common angle rel
context.angleConstraint = QgsCadUtils::AlignMapPointConstraint();
context.commonAngleConstraint = QgsCadUtils::AlignMapPointConstraint( true, true, 90 );
context.setCadPoint( QgsPoint( 40, 20 ), 1 );
context.setCadPoint( 1, QgsPoint( 40, 20 ) );
QgsCadUtils::AlignMapPointOutput res3 = QgsCadUtils::alignMapPoint( QgsPointXY( 50.1, 29.9 ), context );
QVERIFY( res3.valid );
QCOMPARE( res3.softLockCommonAngle, 90.0 );

0 comments on commit 50ab8c1

Please sign in to comment.