Skip to content

Commit 68b621a

Browse files
authored
Merge pull request #3314 from nyalldawson/units
Consolidate unit handling in QgsUnitTypes
2 parents 156c098 + 813ed5e commit 68b621a

File tree

172 files changed

+2562
-2151
lines changed

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

172 files changed

+2562
-2151
lines changed

doc/api_break.dox

Lines changed: 39 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -53,6 +53,14 @@ should now call QgsCoordinateReferenceSystem::invalidateCache() and QgsCoordinat
5353
<li>permissiveToDouble() and permissiveToInt() where moved out of the QGis class and renamed to qgsPermissiveToDouble() and
5454
qgsPermissiveToInt()</li>
5555
<li>The constants DEFAULT_IDENTIFY_RADIUS and MINIMUM_POINT_SIZE were removed</li>
56+
<li>QGis::DecimalDegrees, DegreesMinutesSeconds and DegreesDecimalMinutes have been removed, and have all been replaced
57+
with the general Degrees unit</li>
58+
<li>The distance unit types QGis::UnitType (including QGis::Meters, QGis::Feet, QGis::Degrees, QGis::NauticalMiles,
59+
QGis::Kilometers, QGis::Yards, QGis::Miles and QGis::UnknownUnit have been moved to QgsUnitTypes::DistanceUnit.
60+
Some of these unit types have also been renamed - see the notes on QgsUnitTypes below. All methods which accepted
61+
QGis::UnitType parameters have been updated to take QgsUnitTypes::DistanceUnit instead.</li>
62+
<li>The unit handling methods toLiteral, fromLiteral, tr, fromTr, fromUnitToUnitFactor have been removed. Their
63+
corresponding counterparts in QgsUnitTypes should be used instead.</li>
5664
</ul>
5765

5866
\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
447455
and for forcing certain items to always sort on top.</li>
448456
</ul>
449457

458+
\subsection qgis_api_break_3_0_QgsSymbolV2 QgsSymbolV2
459+
460+
<ul>
461+
<li>The OutputUnit enum, including QgsSymbolV2::MM, QgsSymbolV2::MapUnit, QgsSymbolV2::Mixed, QgsSymbolV2::Pixel and QgsSymbolV2::Percentage has been moved to QgsUnitTypes
462+
and renamed to RenderUnit. QgsSymbolV2::OutputUnitList was renamed to QgsUnitTypes::RenderUnitList. All methods which previously accepted QgsSymbolV2::OutputUnit
463+
parameters or QgsSymbolV2::OutputUnitList parameters now take QgsUnitTypes::RenderUnit or QgsUnitTypes::RenderUnitList parameters respectively.</li>
464+
</ul>
465+
466+
\subsection qgis_api_break_3_0_QgsSymbolLayerV2Utils QgsSymbolLayerV2Utils
467+
468+
<ul>
469+
<li>encodeOutputUnit() and decodeOutputUnit() were removed. QgsUnitTypes::encodeUnit() and QgsUnitTypes::decodeRenderUnit() should be used instead.</li>
470+
</ul>
471+
450472
\subsection qgis_api_break_3_0_QgsTreeWidgetItem QgsTreeWidgetItem
451473

452474
<ul>
453475
<li>QgsTreeWidgetItem is no longer a QObject and does not emit the itemEdited signal. Instead,
454476
use QgsTreeWidgetItemObject which is an upgraded version of the original QgsTreeWidgetItem</li>
455477
</ul>
456478

479+
\subsection qgis_api_break_3_0_QgsUnitTypes QgsUnitTypes
480+
481+
<ul>
482+
<li>All distance enumeration values were renamed to have a "Distance" prefix, including
483+
Meters (to DistanceMeters), Kilometers (to DistanceKilometers), Feet (to DistanceFeet),
484+
NauticalMiles (to DistanceNauticalMiles), Yards (to DistanceYards), Miles (to DistanceMiles),
485+
Degrees (to DistanceDegrees) and UnknownDistanceUnit to DistanceUnknownUnit</li>
486+
<li>All area enumeration values were renamed to have a "Area" prefix, including
487+
SquareMeters (to AreaSquareMeters), SquareKilometers (to AreaSquareKilometers), SquareFeet (to AreaSquareFeet),
488+
SquareYards (to AreaSquareYards), SquareMiles (to AreaSquareMiles), Hectares (to AreaHectares),
489+
Acres (to AreaAcres), SquareNauticalMiles (to AreaSquareNauticalMiles), SquareDegrees (to AreaSquareDegrees)
490+
and UnknownAreaUnit to AreaUnknownUnit</li>
491+
<li>All angle enumeration values were renamed to have a "Angle" prefix, including
492+
Radians (to AngleRadians), Gon (to AngleGon), MinutesOfArc (to AngleMinutesOfArc),
493+
SecondsOfArc (to AngleSecondsOfArc), Turn (to AngleTurn) and UnknownAngleUnit to AngleUnknownUnit</li>
494+
</ul>
495+
457496
\subsection qgis_api_break_3_0_QgsVectorLayer QgsVectorLayer
458497

459498
<ul>

python/core/dxf/qgsdxfexport.sip

Lines changed: 4 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -63,14 +63,14 @@ class QgsDxfExport
6363
* Set map units
6464
* @param u unit
6565
*/
66-
void setMapUnits( Qgis::UnitType u );
66+
void setMapUnits( QgsUnitTypes::DistanceUnit u );
6767

6868
/**
6969
* Retrieve map units
7070
* @returns unit
7171
* @see setMapUnits
7272
*/
73-
Qgis::UnitType mapUnits() const;
73+
QgsUnitTypes::DistanceUnit mapUnits() const;
7474

7575
/**
7676
* Set symbology export mode
@@ -327,7 +327,8 @@ class QgsDxfExport
327327
//! @note added in 2.15
328328
void writeMText( const QString &layer, const QString &text, const QgsPointV2 &pt, double width, double angle, const QColor& color );
329329

330-
static double mapUnitScaleFactor( double scaleDenominator, QgsSymbolV2::OutputUnit symbolUnits, Qgis::UnitType mapUnits );
330+
//! Calculates a scaling factor to convert from map units to a specified symbol unit.
331+
static double mapUnitScaleFactor( double scaleDenominator, QgsUnitTypes::RenderUnit symbolUnits, QgsUnitTypes::DistanceUnit mapUnits );
331332

332333
//! Return cleaned layer name for use in DXF
333334
static QString dxfLayerName( const QString &name );

python/core/effects/qgsgloweffect.sip

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -50,15 +50,15 @@ class QgsGlowEffect : QgsPaintEffect
5050
* @see setSpread
5151
* @see setSpreadMapUnitScale
5252
*/
53-
void setSpreadUnit( const QgsSymbolV2::OutputUnit unit );
53+
void setSpreadUnit( const QgsUnitTypes::RenderUnit unit );
5454

5555
/** Returns the units used for the glow spread distance.
5656
* @returns units for spread distance
5757
* @see setSpreadUnit
5858
* @see spread
5959
* @see spreadMapUnitScale
6060
*/
61-
QgsSymbolV2::OutputUnit spreadUnit() const;
61+
QgsUnitTypes::RenderUnit spreadUnit() const;
6262

6363
/** Sets the map unit scale used for the spread distance.
6464
* @param scale map unit scale for spread distance

python/core/effects/qgsshadoweffect.sip

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -69,15 +69,15 @@ class QgsShadowEffect : QgsPaintEffect
6969
* @see setOffsetDistance
7070
* @see setOffsetMapUnitScale
7171
*/
72-
void setOffsetUnit( const QgsSymbolV2::OutputUnit unit );
72+
void setOffsetUnit( const QgsUnitTypes::RenderUnit unit );
7373

7474
/** Returns the units used for the shadow offset distance.
7575
* @returns units for offset distance
7676
* @see setOffsetUnit
7777
* @see offsetDistance
7878
* @see offsetMapUnitScale
7979
*/
80-
QgsSymbolV2::OutputUnit offsetUnit() const;
80+
QgsUnitTypes::RenderUnit offsetUnit() const;
8181

8282
/** Sets the map unit scale used for the shadow offset distance.
8383
* @param scale map unit scale for offset distance

python/core/effects/qgstransformeffect.sip

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -71,7 +71,7 @@ class QgsTransformEffect : QgsPaintEffect
7171
* @see setTranslateY
7272
* @see setTranslateMapUnitScale
7373
*/
74-
void setTranslateUnit( const QgsSymbolV2::OutputUnit unit );
74+
void setTranslateUnit( const QgsUnitTypes::RenderUnit unit );
7575

7676
/** Returns the units used for the transform translation.
7777
* @returns units for translation
@@ -80,7 +80,7 @@ class QgsTransformEffect : QgsPaintEffect
8080
* @see translateY
8181
* @see translateMapUnitScale
8282
*/
83-
QgsSymbolV2::OutputUnit translateUnit() const;
83+
QgsUnitTypes::RenderUnit translateUnit() const;
8484

8585
/** Sets the map unit scale used for the transform translation.
8686
* @param scale map unit scale for translation

python/core/qgis.sip

Lines changed: 0 additions & 44 deletions
Original file line numberDiff line numberDiff line change
@@ -136,50 +136,6 @@ class Qgis
136136
QImage::Format_ARGB32_Premultiplied */ ARGB32_Premultiplied,
137137
};
138138

139-
140-
/** Map units that qgis supports
141-
* @note that QGIS < 1.4 api had only Meters, Feet, Degrees and UnknownUnit
142-
* @note and QGIS >1.8 returns to that
143-
*/
144-
//TODO QGIS 3.0 - clean up and move to QgsUnitTypes and rename to DistanceUnit
145-
enum UnitType
146-
{
147-
Meters, /*!< meters */
148-
Feet, /*!< imperial feet */
149-
Degrees, /*!< degrees, for planar geographic CRS distance measurements */ //for 1.0 api backwards compatibility
150-
NauticalMiles, /*!< nautical miles */
151-
Kilometers, /*!< kilometers */
152-
Yards, /*!< imperial yards */
153-
Miles, /*!< terrestial miles */
154-
155-
UnknownUnit, /*!< unknown distance unit */
156-
157-
// for [1.4;1.8] api compatibility
158-
DecimalDegrees, // was 2
159-
DegreesMinutesSeconds, // was 4
160-
DegreesDecimalMinutes, // was 5
161-
};
162-
163-
//! Provides the canonical name of the type value
164-
//! @deprecated use QgsUnitTypes::encodeUnit() instead
165-
static QString toLiteral( Qgis::UnitType unit ) /Deprecated/;
166-
167-
//! Converts from the canonical name to the type value
168-
//! @deprecated use QgsUnitTypes::decodeDistanceUnit() instead
169-
static UnitType fromLiteral( const QString& literal, Qgis::UnitType defaultType = UnknownUnit ) /Deprecated/;
170-
171-
//! Provides translated version of the type value
172-
//! @deprecated use QgsUnitTypes::toString() instead
173-
static QString tr( Qgis::UnitType unit ) /Deprecated/;
174-
175-
//! Provides type value from translated version
176-
//! @deprecated use QgsUnitTypes::stringToDistanceUnit() instead
177-
static UnitType fromTr( const QString& literal, Qgis::UnitType defaultType = UnknownUnit ) /Deprecated/;
178-
179-
//! Returns the conversion factor between the specified units
180-
//! @deprecated use QgsUnitTyoes::fromUnitToUnitFactor() instead
181-
static double fromUnitToUnitFactor( Qgis::UnitType fromUnit, Qgis::UnitType toUnit ) /Deprecated/;
182-
183139
//! User defined event types
184140
enum UserEvent
185141
{

python/core/qgscoordinatereferencesystem.sip

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -479,7 +479,7 @@ class QgsCoordinateReferenceSystem
479479

480480
/** Returns the units for the projection used by the CRS.
481481
*/
482-
Qgis::UnitType mapUnits() const;
482+
QgsUnitTypes::DistanceUnit mapUnits() const;
483483

484484

485485
// Mutators -----------------------------------

python/core/qgsdiagramrendererv2.sip

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -285,7 +285,7 @@ class QgsDiagramSettings
285285

286286
/** Diagram size unit
287287
*/
288-
QgsSymbolV2::OutputUnit sizeType;
288+
QgsUnitTypes::RenderUnit sizeType;
289289

290290
/** Diagram size unit scale
291291
* @note added in 2.16
@@ -295,7 +295,7 @@ class QgsDiagramSettings
295295
/** Line unit index
296296
* @note added in 2.16
297297
*/
298-
QgsSymbolV2::OutputUnit lineSizeUnit;
298+
QgsUnitTypes::RenderUnit lineSizeUnit;
299299

300300
/** Line unit scale
301301
* @note added in 2.16

python/core/qgsdistancearea.sip

Lines changed: 5 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -155,7 +155,7 @@ class QgsDistanceArea
155155
* @note added in QGIS 2.14
156156
* @see areaUnits()
157157
*/
158-
Qgis::UnitType lengthUnits() const;
158+
QgsUnitTypes::DistanceUnit lengthUnits() const;
159159

160160
/** Returns the units of area for areal calculations made by this object.
161161
* @note added in QGIS 2.14
@@ -179,7 +179,7 @@ class QgsDistanceArea
179179
* @return formatted measurement string
180180
* @deprecated use formatDistance() or formatArea() instead
181181
*/
182-
static QString textUnit( double value, int decimals, Qgis::UnitType u, bool isArea, bool keepBaseUnit = false ) /Deprecated/;
182+
static QString textUnit( double value, int decimals, QgsUnitTypes::DistanceUnit u, bool isArea, bool keepBaseUnit = false ) /Deprecated/;
183183

184184
/** Returns an distance formatted as a friendly string.
185185
* @param distance distance to format
@@ -191,7 +191,7 @@ class QgsDistanceArea
191191
* @note added in QGIS 2.16
192192
* @see formatArea()
193193
*/
194-
static QString formatDistance( double distance, int decimals, Qgis::UnitType unit, bool keepBaseUnit = false );
194+
static QString formatDistance( double distance, int decimals, QgsUnitTypes::DistanceUnit unit, bool keepBaseUnit = false );
195195

196196
/** Returns an area formatted as a friendly string.
197197
* @param area area to format
@@ -208,7 +208,7 @@ class QgsDistanceArea
208208

209209
//! Helper for conversion between physical units
210210
// TODO QGIS 3.0 - remove this method, as its behaviour is non-intuitive.
211-
void convertMeasurement( double &measure /In,Out/, Qgis::UnitType &measureUnits /In,Out/, Qgis::UnitType displayUnits, bool isArea ) const;
211+
void convertMeasurement( double &measure /In,Out/, QgsUnitTypes::DistanceUnit &measureUnits /In,Out/, QgsUnitTypes::DistanceUnit displayUnits, bool isArea ) const;
212212

213213
/** Takes a length measurement calculated by this QgsDistanceArea object and converts it to a
214214
* different distance unit.
@@ -219,7 +219,7 @@ class QgsDistanceArea
219219
* @see convertAreaMeasurement()
220220
* @note added in QGIS 2.14
221221
*/
222-
double convertLengthMeasurement( double length, Qgis::UnitType toUnits ) const;
222+
double convertLengthMeasurement( double length, QgsUnitTypes::DistanceUnit toUnits ) const;
223223

224224
/** Takes an area measurement calculated by this QgsDistanceArea object and converts it to a
225225
* different areal unit.

python/core/qgsexpression.sip

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -167,14 +167,14 @@ class QgsExpression
167167
* @note added in QGIS 2.14
168168
* @see setDistanceUnits()
169169
*/
170-
Qgis::UnitType distanceUnits() const;
170+
QgsUnitTypes::DistanceUnit distanceUnits() const;
171171

172172
/** Sets the desired distance units for calculations involving geomCalculator(), eg "$length" and "$perimeter".
173173
* @note distances are only converted when a geomCalculator() has been set
174174
* @note added in QGIS 2.14
175175
* @see distanceUnits()
176176
*/
177-
void setDistanceUnits( Qgis::UnitType unit );
177+
void setDistanceUnits( QgsUnitTypes::DistanceUnit unit );
178178

179179
/** Returns the desired areal units for calculations involving geomCalculator(), eg "$area".
180180
* @note areas are only converted when a geomCalculator() has been set

python/core/qgsmapsettings.sip

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -91,9 +91,9 @@ class QgsMapSettings
9191
QgsCoordinateReferenceSystem destinationCrs() const;
9292

9393
//! Get units of map's geographical coordinates - used for scale calculation
94-
Qgis::UnitType mapUnits() const;
94+
QgsUnitTypes::DistanceUnit mapUnits() const;
9595
//! Set units of map's geographical coordinates - used for scale calculation
96-
void setMapUnits( Qgis::UnitType u );
96+
void setMapUnits( QgsUnitTypes::DistanceUnit u );
9797

9898
//! Set the background color of the map
9999
void setBackgroundColor( const QColor& color );

python/core/qgsproject.sip

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -246,7 +246,7 @@ class QgsProject : QObject
246246
* @note added in QGIS 2.14
247247
* @see areaUnits()
248248
*/
249-
Qgis::UnitType distanceUnits() const;
249+
QgsUnitTypes::DistanceUnit distanceUnits() const;
250250

251251
/** Convenience function to query default area measurement units for project.
252252
* @note added in QGIS 2.14

python/core/qgsscalecalculator.sip

Lines changed: 4 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -13,11 +13,10 @@ class QgsScaleCalculator
1313
/**
1414
* Constructor
1515
* @param dpi Monitor resolution in dots per inch
16-
* @param mapUnits Units of the data on the map. Must match a value from the
17-
* Qgis::UnitType enum (Meters, Feet, Degrees)
16+
* @param mapUnits Units of the data on the map
1817
*/
1918
QgsScaleCalculator( double dpi = 0,
20-
Qgis::UnitType mapUnits = Qgis::Meters );
19+
QgsUnitTypes::DistanceUnit mapUnits = QgsUnitTypes::DistanceMeters );
2120

2221
/**
2322
* Set the dpi to be used in scale calculations
@@ -35,10 +34,10 @@ class QgsScaleCalculator
3534
* Set the map units
3635
* @param mapUnits Units of the data on the map. Must match a value from the
3736
*/
38-
void setMapUnits( Qgis::UnitType mapUnits );
37+
void setMapUnits( QgsUnitTypes::DistanceUnit mapUnits );
3938

4039
/** Returns current map units */
41-
Qgis::UnitType mapUnits() const;
40+
QgsUnitTypes::DistanceUnit mapUnits() const;
4241

4342
/**
4443
* Calculate the scale denominator

0 commit comments

Comments
 (0)