Add QgsMapToPixel::isValid() to determine if a map to pixel is default

constructed with no parameters set or not
qgis · Sep 27, 2021 · d3792a9 · d3792a9
1 parent 6a57fd0
commit d3792a9
Show file tree

Hide file tree

Showing 4 changed files with 172 additions and 52 deletions.
diff --git a/python/core/auto_generated/qgsmaptopixel.sip.in b/python/core/auto_generated/qgsmaptopixel.sip.in
@@ -23,6 +23,13 @@ This class can convert device coordinates to map coordinates and vice versa.
 %End
   public:
 
+    QgsMapToPixel();
+%Docstring
+Constructor for an invalid QgsMapToPixel.
+
+A manual call to :py:func:`~QgsMapToPixel.setParameters` is required to initialise the object.
+%End
+
     QgsMapToPixel( double mapUnitsPerPixel, double centerX, double centerY, int widthPixels, int heightPixels, double rotation );
 %Docstring
 Constructor
@@ -57,16 +64,17 @@ Returns a new QgsMapToPixel created using a specified ``scale`` and distance uni
 .. versionadded:: 3.0
 %End
 
-    QgsMapToPixel();
+    bool isValid() const;
 %Docstring
-Constructor
+Returns ``True`` if the object is valid (i.e. it has parameters set), or ``False`` if the object is default constructed
+with no parameters set.
 
-Use setParameters to fill
+.. versionadded:: 3.22
 %End
 
     QgsPointXY transform( const QgsPointXY &p ) const;
 %Docstring
-Transform the point ``p`` from map (world) coordinates to device coordinates.
+Transforms a point ``p`` from map (world) coordinates to device coordinates.
 
 :param p: Point to transform
 
@@ -75,42 +83,42 @@ Transform the point ``p`` from map (world) coordinates to device coordinates.
 
     void transform( QgsPointXY *p ) const;
 %Docstring
-Transform the point ``p`` from map (world) coordinates to device coordinates in place.
+Transforms a point ``p`` from map (world) coordinates to device coordinates in place.
 %End
 
     QgsPointXY transform( qreal x, qreal y ) const;
 %Docstring
-Transform the point specified by x,y from map (world)
-coordinates to device coordinates
+Transforms the point specified by x,y from map (world) coordinates to device coordinates.
 
-:param x: x coordinate o point to transform
+:param x: x coordinate of point to transform
 :param y: y coordinate of point to transform
 
 :return: :py:class:`QgsPointXY` in device coordinates
 %End
 
     void transformInPlace( double &x, double &y ) const;
 %Docstring
-Transforms device coordinates to map coordinates. Modifies the
-given coordinates in place. Intended as a fast way to do the
+Transforms device coordinates to map coordinates.
+
+This method modifies the given coordinates in place. It is intended as a fast way to do the
 transform.
 %End
 
 
 
     QgsPointXY toMapCoordinates( int x, int y ) const;
 %Docstring
-Transform device coordinates to map (world) coordinates
+Transforms device coordinates to map (world) coordinates.
 %End
 
     QgsPointXY toMapCoordinates( double x, double y ) const /PyName=toMapCoordinatesF/;
 %Docstring
-Transform device coordinates to map (world) coordinates
+Transforms device coordinates to map (world) coordinates.
 %End
 
     QgsPointXY toMapCoordinates( QPoint p ) const;
 %Docstring
-Transform device coordinates to map (world) coordinates
+Transforms device coordinates to map (world) coordinates.
 
 :param p: Point to be converted to map cooordinates
 
@@ -119,28 +127,37 @@ Transform device coordinates to map (world) coordinates
 
  QgsPointXY toMapPoint( double x, double y ) const /Deprecated/;
 %Docstring
-Transform device coordinates to map (world) coordinates
+Transforms device coordinates to map (world) coordinates.
 
 .. deprecated:: QGIS 3.4
    use toMapCoordinates instead
 %End
 
     void setMapUnitsPerPixel( double mapUnitsPerPixel );
 %Docstring
-Set map units per pixel
+Sets the map units per pixel.
+
+Calling this method will automatically set the object as valid.
 
 :param mapUnitsPerPixel: Map units per pixel
+
+.. seealso:: :py:func:`mapUnitsPerPixel`
 %End
 
     double mapUnitsPerPixel() const;
 %Docstring
-Returns current map units per pixel
+Returns the current map units per pixel.
+
+.. seealso:: :py:func:`setMapUnitsPerPixel`
 %End
 
     int mapWidth() const;
 %Docstring
-Returns current map width in pixels
-The information is only known if setRotation was used
+Returns the current map width in pixels.
+
+The information is only known if setRotation was used.
+
+.. seealso:: :py:func:`mapHeight`
 
 .. versionadded:: 2.8
 %End
@@ -149,30 +166,40 @@ The information is only known if setRotation was used
 %Docstring
 Returns current map height in pixels
 
+.. seealso:: :py:func:`mapWidth`
+
 .. versionadded:: 2.8
 %End
 
     void setMapRotation( double degrees, double cx, double cy );
 %Docstring
-Set map rotation in degrees (clockwise)
+Sets map rotation in ``degrees`` (clockwise).
+
+Calling this method will automatically set the object as valid.
 
 :param degrees: clockwise rotation in degrees
 :param cx: X ordinate of map center in geographical units
 :param cy: Y ordinate of map center in geographical units
 
+.. seealso:: :py:func:`mapRotation`
+
 .. versionadded:: 2.8
 %End
 
     double mapRotation() const;
 %Docstring
-Returns current map rotation in degrees (clockwise)
+Returns the current map rotation in degrees (clockwise).
+
+.. seealso:: :py:func:`setMapRotation`
 
 .. versionadded:: 2.8
 %End
 
     void setParameters( double mapUnitsPerPixel, double centerX, double centerY, int widthPixels, int heightPixels, double rotation );
 %Docstring
-Set parameters for use in transforming coordinates
+Sets parameters for use in transforming coordinates.
+
+Calling this method will automatically set the object as valid.
 
 :param mapUnitsPerPixel: Map units per pixel
 :param centerX: X coordinate of map center, in geographical units
@@ -191,7 +218,7 @@ Set parameters for use in transforming coordinates
 
     QString showParameters() const;
 %Docstring
-String representation of the parameters used in the transform
+Returns a string representation of the parameters used in the transform.
 %End
 
     QTransform transform() const;

diff --git a/src/core/qgsmaptopixel.cpp b/src/core/qgsmaptopixel.cpp
@@ -31,7 +31,8 @@ QgsMapToPixel::QgsMapToPixel( double mapUnitsPerPixel,
                               int width,
                               int height,
                               double rotation )
-  : mMapUnitsPerPixel( mapUnitsPerPixel )
+  : mValid( true )
+  , mMapUnitsPerPixel( mapUnitsPerPixel )
   , mWidth( width )
   , mHeight( height )
   , mRotation( rotation )
@@ -45,7 +46,8 @@ QgsMapToPixel::QgsMapToPixel( double mapUnitsPerPixel,
 }
 
 QgsMapToPixel::QgsMapToPixel( double mapUnitsPerPixel )
-  : mMapUnitsPerPixel( mapUnitsPerPixel )
+  : mValid( true )
+  , mMapUnitsPerPixel( mapUnitsPerPixel )
   , mWidth( 0 )
   , mHeight( 0 )
   , mXCenter( 0 )
@@ -80,6 +82,8 @@ bool QgsMapToPixel::updateMatrix()
 
 void QgsMapToPixel::setMapUnitsPerPixel( double mapUnitsPerPixel )
 {
+  mValid = true;
+
   const double oldUnits = mMapUnitsPerPixel;
   mMapUnitsPerPixel = mapUnitsPerPixel;
   if ( !updateMatrix() )
@@ -90,6 +94,8 @@ void QgsMapToPixel::setMapUnitsPerPixel( double mapUnitsPerPixel )
 
 void QgsMapToPixel::setMapRotation( double degrees, double cx, double cy )
 {
+  mValid = true;
+
   const double oldRotation = mRotation;
   const double oldXCenter = mXCenter;
   const double oldYCenter = mYCenter;
@@ -121,6 +127,8 @@ void QgsMapToPixel::setParameters( double mapUnitsPerPixel,
                                    double rotation,
                                    bool *ok )
 {
+  mValid = true;
+
   const double oldMUPP = mMapUnitsPerPixel;
   const double oldXCenter = mXCenter;
   const double oldYCenter = mYCenter;
@@ -164,6 +172,7 @@ void QgsMapToPixel::setParameters( double mapUnitsPerPixel,
                                    int height,
                                    double rotation )
 {
+  mValid = true;
   bool ok;
   setParameters( mapUnitsPerPixel, xc, yc, width, height, rotation, &ok );
 }