Merge pull request #3314 from nyalldawson/units

Consolidate unit handling in QgsUnitTypes

Author: nyalldawson

doc/api_break.dox

@@ -53,6 +53,14 @@ should now call QgsCoordinateReferenceSystem::invalidateCache() and QgsCoordinat
 <li>permissiveToDouble() and permissiveToInt() where moved out of the QGis class and renamed to qgsPermissiveToDouble() and
 qgsPermissiveToInt()</li>
 <li>The constants DEFAULT_IDENTIFY_RADIUS and MINIMUM_POINT_SIZE were removed</li>
+<li>QGis::DecimalDegrees, DegreesMinutesSeconds and DegreesDecimalMinutes have been removed, and have all been replaced
+with the general Degrees unit</li>
+<li>The distance unit types QGis::UnitType (including QGis::Meters, QGis::Feet, QGis::Degrees, QGis::NauticalMiles,
+QGis::Kilometers, QGis::Yards, QGis::Miles and QGis::UnknownUnit have been moved to QgsUnitTypes::DistanceUnit.
+Some of these unit types have also been renamed - see the notes on QgsUnitTypes below. All methods which accepted
+QGis::UnitType parameters have been updated to take QgsUnitTypes::DistanceUnit instead.</li>
+<li>The unit handling methods toLiteral, fromLiteral, tr, fromTr, fromUnitToUnitFactor have been removed. Their
+corresponding counterparts in QgsUnitTypes should be used instead.</li>
 </ul>
 
 \subsection qgis_api_break_3_0_QgsAuthConfigUriEdit QgsAuthConfigUriEdit
@@ -447,13 +455,44 @@ has improved sort capabilities including the ability to set custom sort values f
 and for forcing certain items to always sort on top.</li>
 </ul>
 
+\subsection qgis_api_break_3_0_QgsSymbolV2 QgsSymbolV2
+
+<ul>
+<li>The OutputUnit enum, including QgsSymbolV2::MM, QgsSymbolV2::MapUnit, QgsSymbolV2::Mixed, QgsSymbolV2::Pixel and QgsSymbolV2::Percentage has been moved to QgsUnitTypes
+and renamed to RenderUnit. QgsSymbolV2::OutputUnitList was renamed to QgsUnitTypes::RenderUnitList. All methods which previously accepted QgsSymbolV2::OutputUnit
+parameters or QgsSymbolV2::OutputUnitList parameters now take QgsUnitTypes::RenderUnit or QgsUnitTypes::RenderUnitList parameters respectively.</li>
+</ul>
+
+\subsection qgis_api_break_3_0_QgsSymbolLayerV2Utils QgsSymbolLayerV2Utils
+
+<ul>
+<li>encodeOutputUnit() and decodeOutputUnit() were removed. QgsUnitTypes::encodeUnit() and QgsUnitTypes::decodeRenderUnit() should be used instead.</li>
+</ul>
+
 \subsection qgis_api_break_3_0_QgsTreeWidgetItem QgsTreeWidgetItem
 
 <ul>
 <li>QgsTreeWidgetItem is no longer a QObject and does not emit the itemEdited signal. Instead,
 use QgsTreeWidgetItemObject which is an upgraded version of the original QgsTreeWidgetItem</li>
 </ul>
 
+\subsection qgis_api_break_3_0_QgsUnitTypes QgsUnitTypes
+
+<ul>
+<li>All distance enumeration values were renamed to have a "Distance" prefix, including
+Meters (to DistanceMeters), Kilometers (to DistanceKilometers), Feet (to DistanceFeet),
+NauticalMiles (to DistanceNauticalMiles), Yards (to DistanceYards), Miles (to DistanceMiles),
+Degrees (to DistanceDegrees) and UnknownDistanceUnit to DistanceUnknownUnit</li>
+<li>All area enumeration values were renamed to have a "Area" prefix, including
+SquareMeters (to AreaSquareMeters), SquareKilometers (to AreaSquareKilometers), SquareFeet (to AreaSquareFeet),
+SquareYards (to AreaSquareYards), SquareMiles (to AreaSquareMiles), Hectares (to AreaHectares),
+Acres (to AreaAcres), SquareNauticalMiles (to AreaSquareNauticalMiles), SquareDegrees (to AreaSquareDegrees)
+and UnknownAreaUnit to AreaUnknownUnit</li>
+<li>All angle enumeration values were renamed to have a "Angle" prefix, including
+Radians (to AngleRadians), Gon (to AngleGon), MinutesOfArc (to AngleMinutesOfArc),
+SecondsOfArc (to AngleSecondsOfArc), Turn (to AngleTurn) and UnknownAngleUnit to AngleUnknownUnit</li>
+</ul>
+
 \subsection qgis_api_break_3_0_QgsVectorLayer QgsVectorLayer
 
 <ul>

python/core/dxf/qgsdxfexport.sip

@@ -63,14 +63,14 @@ class QgsDxfExport
      * Set map units
      * @param u unit
      */
-    void setMapUnits( Qgis::UnitType u );
+    void setMapUnits( QgsUnitTypes::DistanceUnit u );
 
     /**
      * Retrieve map units
      * @returns unit
      * @see setMapUnits
      */
-    Qgis::UnitType mapUnits() const;
+    QgsUnitTypes::DistanceUnit mapUnits() const;
 
     /**
      * Set symbology export mode
@@ -327,7 +327,8 @@ class QgsDxfExport
     //! @note added in 2.15
     void writeMText( const QString &layer, const QString &text, const QgsPointV2 &pt, double width, double angle, const QColor& color );
 
-    static double mapUnitScaleFactor( double scaleDenominator, QgsSymbolV2::OutputUnit symbolUnits, Qgis::UnitType mapUnits );
+    //! Calculates a scaling factor to convert from map units to a specified symbol unit.
+    static double mapUnitScaleFactor( double scaleDenominator, QgsUnitTypes::RenderUnit symbolUnits, QgsUnitTypes::DistanceUnit mapUnits );
 
     //! Return cleaned layer name for use in DXF
     static QString dxfLayerName( const QString &name );

python/core/effects/qgsgloweffect.sip

@@ -50,15 +50,15 @@ class QgsGlowEffect : QgsPaintEffect
      * @see setSpread
      * @see setSpreadMapUnitScale
      */
-    void setSpreadUnit( const QgsSymbolV2::OutputUnit unit );
+    void setSpreadUnit( const QgsUnitTypes::RenderUnit unit );
 
     /** Returns the units used for the glow spread distance.
      * @returns units for spread distance
      * @see setSpreadUnit
      * @see spread
      * @see spreadMapUnitScale
      */
-    QgsSymbolV2::OutputUnit spreadUnit() const;
+    QgsUnitTypes::RenderUnit spreadUnit() const;
 
     /** Sets the map unit scale used for the spread distance.
      * @param scale map unit scale for spread distance

python/core/effects/qgsshadoweffect.sip

@@ -69,15 +69,15 @@ class QgsShadowEffect : QgsPaintEffect
      * @see setOffsetDistance
      * @see setOffsetMapUnitScale
      */
-    void setOffsetUnit( const QgsSymbolV2::OutputUnit unit );
+    void setOffsetUnit( const QgsUnitTypes::RenderUnit unit );
 
     /** Returns the units used for the shadow offset distance.
      * @returns units for offset distance
      * @see setOffsetUnit
      * @see offsetDistance
      * @see offsetMapUnitScale
      */
-    QgsSymbolV2::OutputUnit offsetUnit() const;
+    QgsUnitTypes::RenderUnit offsetUnit() const;
 
     /** Sets the map unit scale used for the shadow offset distance.
      * @param scale map unit scale for offset distance

python/core/effects/qgstransformeffect.sip

@@ -71,7 +71,7 @@ class QgsTransformEffect : QgsPaintEffect
      * @see setTranslateY
      * @see setTranslateMapUnitScale
      */
-    void setTranslateUnit( const QgsSymbolV2::OutputUnit unit );
+    void setTranslateUnit( const QgsUnitTypes::RenderUnit unit );
 
     /** Returns the units used for the transform translation.
      * @returns units for translation
@@ -80,7 +80,7 @@ class QgsTransformEffect : QgsPaintEffect
      * @see translateY
      * @see translateMapUnitScale
      */
-    QgsSymbolV2::OutputUnit translateUnit() const;
+    QgsUnitTypes::RenderUnit translateUnit() const;
 
     /** Sets the map unit scale used for the transform translation.
      * @param scale map unit scale for translation

python/core/qgis.sip

@@ -136,50 +136,6 @@ class Qgis
           QImage::Format_ARGB32_Premultiplied */        ARGB32_Premultiplied,
     };
 
-
-    /** Map units that qgis supports
-     * @note that QGIS < 1.4 api had only Meters, Feet, Degrees and UnknownUnit
-     * @note and QGIS >1.8 returns to that
-     */
-    //TODO QGIS 3.0 - clean up and move to QgsUnitTypes and rename to DistanceUnit
-    enum UnitType
-    {
-      Meters, /*!< meters */
-      Feet, /*!< imperial feet */
-      Degrees, /*!< degrees, for planar geographic CRS distance measurements */ //for 1.0 api backwards compatibility
-      NauticalMiles, /*!< nautical miles */
-      Kilometers, /*!< kilometers */
-      Yards, /*!< imperial yards */
-      Miles, /*!< terrestial miles */
-
-      UnknownUnit, /*!< unknown distance unit */
-
-      // for [1.4;1.8] api compatibility
-      DecimalDegrees,         // was 2
-      DegreesMinutesSeconds,  // was 4
-      DegreesDecimalMinutes,  // was 5
-    };
-
-    //! Provides the canonical name of the type value
-    //! @deprecated use QgsUnitTypes::encodeUnit() instead
-    static QString toLiteral( Qgis::UnitType unit ) /Deprecated/;
-
-    //! Converts from the canonical name to the type value
-    //! @deprecated use QgsUnitTypes::decodeDistanceUnit() instead
-    static UnitType fromLiteral( const QString& literal, Qgis::UnitType defaultType = UnknownUnit ) /Deprecated/;
-
-    //! Provides translated version of the type value
-    //! @deprecated use QgsUnitTypes::toString() instead
-    static QString tr( Qgis::UnitType unit ) /Deprecated/;
-
-    //! Provides type value from translated version
-    //! @deprecated use QgsUnitTypes::stringToDistanceUnit() instead
-    static UnitType fromTr( const QString& literal, Qgis::UnitType defaultType = UnknownUnit ) /Deprecated/;
-
-    //! Returns the conversion factor between the specified units
-    //! @deprecated use QgsUnitTyoes::fromUnitToUnitFactor() instead
-    static double fromUnitToUnitFactor( Qgis::UnitType fromUnit, Qgis::UnitType toUnit ) /Deprecated/;
-
     //! User defined event types
     enum UserEvent
     {

python/core/qgscoordinatereferencesystem.sip

@@ -479,7 +479,7 @@ class QgsCoordinateReferenceSystem
 
     /** Returns the units for the projection used by the CRS.
      */
-    Qgis::UnitType mapUnits() const;
+    QgsUnitTypes::DistanceUnit mapUnits() const;
 
 
     // Mutators -----------------------------------

python/core/qgsdiagramrendererv2.sip

@@ -285,7 +285,7 @@ class QgsDiagramSettings
 
     /** Diagram size unit
      */
-    QgsSymbolV2::OutputUnit sizeType;
+    QgsUnitTypes::RenderUnit sizeType;
 
     /** Diagram size unit scale
      * @note added in 2.16
@@ -295,7 +295,7 @@ class QgsDiagramSettings
     /** Line unit index
      * @note added in 2.16
      */
-    QgsSymbolV2::OutputUnit lineSizeUnit;
+    QgsUnitTypes::RenderUnit lineSizeUnit;
 
     /** Line unit scale
      * @note added in 2.16

python/core/qgsdistancearea.sip

@@ -155,7 +155,7 @@ class QgsDistanceArea
      * @note added in QGIS 2.14
      * @see areaUnits()
      */
-    Qgis::UnitType lengthUnits() const;
+    QgsUnitTypes::DistanceUnit lengthUnits() const;
 
     /** Returns the units of area for areal calculations made by this object.
      * @note added in QGIS 2.14
@@ -179,7 +179,7 @@ class QgsDistanceArea
      * @return formatted measurement string
      * @deprecated use formatDistance() or formatArea() instead
      */
-    static QString textUnit( double value, int decimals, Qgis::UnitType u, bool isArea, bool keepBaseUnit = false ) /Deprecated/;
+    static QString textUnit( double value, int decimals, QgsUnitTypes::DistanceUnit u, bool isArea, bool keepBaseUnit = false ) /Deprecated/;
 
     /** Returns an distance formatted as a friendly string.
      * @param distance distance to format
@@ -191,7 +191,7 @@ class QgsDistanceArea
      * @note added in QGIS 2.16
      * @see formatArea()
      */
-    static QString formatDistance( double distance, int decimals, Qgis::UnitType unit, bool keepBaseUnit = false );
+    static QString formatDistance( double distance, int decimals, QgsUnitTypes::DistanceUnit unit, bool keepBaseUnit = false );
 
     /** Returns an area formatted as a friendly string.
      * @param area area to format
@@ -208,7 +208,7 @@ class QgsDistanceArea
 
     //! Helper for conversion between physical units
     // TODO QGIS 3.0 - remove this method, as its behaviour is non-intuitive.
-    void convertMeasurement( double &measure /In,Out/, Qgis::UnitType &measureUnits /In,Out/, Qgis::UnitType displayUnits, bool isArea ) const;
+    void convertMeasurement( double &measure /In,Out/, QgsUnitTypes::DistanceUnit &measureUnits /In,Out/, QgsUnitTypes::DistanceUnit displayUnits, bool isArea ) const;
 
     /** Takes a length measurement calculated by this QgsDistanceArea object and converts it to a
      * different distance unit.
@@ -219,7 +219,7 @@ class QgsDistanceArea
      * @see convertAreaMeasurement()
      * @note added in QGIS 2.14
      */
-    double convertLengthMeasurement( double length, Qgis::UnitType toUnits ) const;
+    double convertLengthMeasurement( double length, QgsUnitTypes::DistanceUnit toUnits ) const;
 
     /** Takes an area measurement calculated by this QgsDistanceArea object and converts it to a
      * different areal unit.

python/core/qgsexpression.sip

@@ -167,14 +167,14 @@ class QgsExpression
      * @note added in QGIS 2.14
      * @see setDistanceUnits()
      */
-    Qgis::UnitType distanceUnits() const;
+    QgsUnitTypes::DistanceUnit distanceUnits() const;
 
     /** Sets the desired distance units for calculations involving geomCalculator(), eg "$length" and "$perimeter".
      * @note distances are only converted when a geomCalculator() has been set
      * @note added in QGIS 2.14
      * @see distanceUnits()
      */
-    void setDistanceUnits( Qgis::UnitType unit );
+    void setDistanceUnits( QgsUnitTypes::DistanceUnit unit );
 
     /** Returns the desired areal units for calculations involving geomCalculator(), eg "$area".
      * @note areas are only converted when a geomCalculator() has been set

python/core/qgsmapsettings.sip

@@ -91,9 +91,9 @@ class QgsMapSettings
     QgsCoordinateReferenceSystem destinationCrs() const;
 
     //! Get units of map's geographical coordinates - used for scale calculation
-    Qgis::UnitType mapUnits() const;
+    QgsUnitTypes::DistanceUnit mapUnits() const;
     //! Set units of map's geographical coordinates - used for scale calculation
-    void setMapUnits( Qgis::UnitType u );
+    void setMapUnits( QgsUnitTypes::DistanceUnit u );
 
     //! Set the background color of the map
     void setBackgroundColor( const QColor& color );

python/core/qgsproject.sip

@@ -246,7 +246,7 @@ class QgsProject : QObject
      * @note added in QGIS 2.14
      * @see areaUnits()
      */
-    Qgis::UnitType distanceUnits() const;
+    QgsUnitTypes::DistanceUnit distanceUnits() const;
 
     /** Convenience function to query default area measurement units for project.
      * @note added in QGIS 2.14

python/core/qgsscalecalculator.sip

@@ -13,11 +13,10 @@ class QgsScaleCalculator
     /**
      * Constructor
      * @param dpi Monitor resolution in dots per inch
-     * @param mapUnits Units of the data on the map. Must match a value from the
-     * Qgis::UnitType enum (Meters, Feet, Degrees)
+     * @param mapUnits Units of the data on the map
      */
     QgsScaleCalculator( double dpi = 0,
-                        Qgis::UnitType mapUnits = Qgis::Meters );
+                        QgsUnitTypes::DistanceUnit mapUnits = QgsUnitTypes::DistanceMeters );
 
     /**
      * Set the dpi to be used in scale calculations
@@ -35,10 +34,10 @@ class QgsScaleCalculator
      * Set the map units
      * @param mapUnits Units of the data on the map. Must match a value from the
      */
-    void setMapUnits( Qgis::UnitType mapUnits );
+    void setMapUnits( QgsUnitTypes::DistanceUnit mapUnits );
 
     /** Returns current map units */
-    Qgis::UnitType mapUnits() const;
+    QgsUnitTypes::DistanceUnit mapUnits() const;
 
     /**
      * Calculate the scale denominator