QGIS API Documentation  3.8.0-Zanzibar (11aff65)
Classes | Public Types | Static Public Member Functions | List of all members
QgsUnitTypes Class Reference

Helper functions for various unit types. More...

#include <qgsunittypes.h>

Classes

struct  AreaValue
 A combination of area value and unit. More...
 
struct  DistanceValue
 A combination of distance value and unit. More...
 

Public Types

enum  AngleUnit {
  AngleDegrees = 0, AngleRadians, AngleGon, AngleMinutesOfArc,
  AngleSecondsOfArc, AngleTurn, AngleUnknownUnit
}
 Units of angles. More...
 
enum  AreaUnit {
  AreaSquareMeters = 0, AreaSquareKilometers, AreaSquareFeet, AreaSquareYards,
  AreaSquareMiles, AreaHectares, AreaAcres, AreaSquareNauticalMiles,
  AreaSquareDegrees, AreaSquareCentimeters, AreaSquareMillimeters, AreaUnknownUnit
}
 Units of area. More...
 
enum  DistanceUnit {
  DistanceMeters = 0, DistanceKilometers, DistanceFeet, DistanceNauticalMiles,
  DistanceYards, DistanceMiles, DistanceDegrees, DistanceCentimeters,
  DistanceMillimeters, DistanceUnknownUnit
}
 Units of distance. More...
 
enum  DistanceUnitType { Standard = 0, Geographic, UnknownType }
 Types of distance units. More...
 
enum  LayoutUnit {
  LayoutMillimeters = 0, LayoutCentimeters, LayoutMeters, LayoutInches,
  LayoutFeet, LayoutPoints, LayoutPicas, LayoutPixels
}
 Layout measurement units. More...
 
enum  LayoutUnitType { LayoutPaperUnits = 0, LayoutScreenUnits }
 Types of layout units. More...
 
enum  RenderUnit {
  RenderMillimeters = 0, RenderMapUnits, RenderPixels, RenderPercentage,
  RenderPoints, RenderInches, RenderUnknownUnit, RenderMetersInMapUnits
}
 Rendering size units. More...
 
typedef QList< QgsUnitTypes::RenderUnitRenderUnitList
 List of render units. More...
 
enum  SystemOfMeasurement { UnknownSystem = 0, MetricSystem, ImperialSystem, USCSSystem }
 Systems of unit measurement. More...
 

Static Public Member Functions

static Q_INVOKABLE QgsUnitTypes::AngleUnit decodeAngleUnit (const QString &string, bool *ok=nullptr)
 Decodes an angular unit from a string. More...
 
static Q_INVOKABLE AreaUnit decodeAreaUnit (const QString &string, bool *ok=nullptr)
 Decodes an areal unit from a string. More...
 
static Q_INVOKABLE QgsUnitTypes::DistanceUnit decodeDistanceUnit (const QString &string, bool *ok=nullptr)
 Decodes a distance unit from a string. More...
 
static Q_INVOKABLE QgsUnitTypes::LayoutUnit decodeLayoutUnit (const QString &string, bool *ok=nullptr)
 Decodes a layout unit from a string. More...
 
static Q_INVOKABLE QgsUnitTypes::RenderUnit decodeRenderUnit (const QString &string, bool *ok=nullptr)
 Decodes a render unit from a string. More...
 
static Q_INVOKABLE QgsUnitTypes::AreaUnit distanceToAreaUnit (QgsUnitTypes::DistanceUnit distanceUnit)
 Converts a distance unit to its corresponding area unit, e.g., meters to square meters. More...
 
static Q_INVOKABLE QString encodeUnit (QgsUnitTypes::DistanceUnit unit)
 Encodes a distance unit to a string. More...
 
static Q_INVOKABLE QString encodeUnit (QgsUnitTypes::AreaUnit unit)
 Encodes an areal unit to a string. More...
 
static Q_INVOKABLE QString encodeUnit (QgsUnitTypes::AngleUnit unit)
 Encodes an angular unit to a string. More...
 
static Q_INVOKABLE QString encodeUnit (QgsUnitTypes::RenderUnit unit)
 Encodes a render unit to a string. More...
 
static Q_INVOKABLE QString encodeUnit (QgsUnitTypes::LayoutUnit unit)
 Encodes a layout unit to a string. More...
 
static Q_INVOKABLE QString formatAngle (double angle, int decimals, QgsUnitTypes::AngleUnit unit)
 Returns an angle formatted as a friendly string. More...
 
static Q_INVOKABLE QString formatArea (double area, int decimals, QgsUnitTypes::AreaUnit unit, bool keepBaseUnit=false)
 Returns an area formatted as a friendly string. More...
 
static Q_INVOKABLE QString formatDistance (double distance, int decimals, QgsUnitTypes::DistanceUnit unit, bool keepBaseUnit=false)
 Returns an distance formatted as a friendly string. More...
 
static Q_INVOKABLE double fromUnitToUnitFactor (QgsUnitTypes::DistanceUnit fromUnit, QgsUnitTypes::DistanceUnit toUnit)
 Returns the conversion factor between the specified distance units. More...
 
static Q_INVOKABLE double fromUnitToUnitFactor (QgsUnitTypes::AreaUnit fromUnit, QgsUnitTypes::AreaUnit toUnit)
 Returns the conversion factor between the specified areal units. More...
 
static Q_INVOKABLE double fromUnitToUnitFactor (QgsUnitTypes::AngleUnit fromUnit, QgsUnitTypes::AngleUnit toUnit)
 Returns the conversion factor between the specified angular units. More...
 
static Q_INVOKABLE QgsUnitTypes::AreaValue scaledArea (double area, QgsUnitTypes::AreaUnit unit, int decimals, bool keepBaseUnit=false)
 Will convert an area with a given unit to an area value which is nice to display. More...
 
static Q_INVOKABLE QgsUnitTypes::DistanceValue scaledDistance (double distance, QgsUnitTypes::DistanceUnit unit, int decimals, bool keepBaseUnit=false)
 Will convert a distance with a given unit to a distance value which is nice to display. More...
 
static Q_INVOKABLE AreaUnit stringToAreaUnit (const QString &string, bool *ok=nullptr)
 Converts a translated string to an areal unit. More...
 
static Q_INVOKABLE QgsUnitTypes::DistanceUnit stringToDistanceUnit (const QString &string, bool *ok=nullptr)
 Converts a translated string to a distance unit. More...
 
static Q_INVOKABLE QString toAbbreviatedString (QgsUnitTypes::DistanceUnit unit)
 Returns a translated abbreviation representing a distance unit. More...
 
static QString toAbbreviatedString (QgsUnitTypes::AreaUnit unit)
 Returns a translated abbreviation representing an areal unit. More...
 
static Q_INVOKABLE QString toAbbreviatedString (QgsUnitTypes::RenderUnit unit)
 Returns a translated abbreviation representing a render unit. More...
 
static QString toAbbreviatedString (QgsUnitTypes::LayoutUnit unit)
 Returns a translated abbreviation representing a layout unit (e.g. More...
 
static Q_INVOKABLE QString toString (QgsUnitTypes::DistanceUnit unit)
 Returns a translated string representing a distance unit. More...
 
static QString toString (QgsUnitTypes::AreaUnit unit)
 Returns a translated string representing an areal unit. More...
 
static QString toString (QgsUnitTypes::AngleUnit unit)
 Returns a translated string representing an angular unit. More...
 
static QString toString (QgsUnitTypes::RenderUnit unit)
 Returns a translated string representing a render unit. More...
 
static QString toString (QgsUnitTypes::LayoutUnit unit)
 Returns a translated string representing a layout unit. More...
 
static Q_INVOKABLE DistanceUnitType unitType (QgsUnitTypes::DistanceUnit unit)
 Returns the type for a distance unit. More...
 
static Q_INVOKABLE DistanceUnitType unitType (QgsUnitTypes::AreaUnit unit)
 Returns the type for an areal unit. More...
 
static Q_INVOKABLE QgsUnitTypes::LayoutUnitType unitType (QgsUnitTypes::LayoutUnit units)
 Returns the type for a unit of measurement. More...
 

Detailed Description

Helper functions for various unit types.

Since
QGIS 2.14

Definition at line 38 of file qgsunittypes.h.

Member Typedef Documentation

◆ RenderUnitList

List of render units.

Definition at line 184 of file qgsunittypes.h.

Member Enumeration Documentation

◆ AngleUnit

Units of angles.

Enumerator
AngleDegrees 

Degrees.

AngleRadians 

Square kilometers.

AngleGon 

Gon/gradian.

AngleMinutesOfArc 

Minutes of arc.

AngleSecondsOfArc 

Seconds of arc.

AngleTurn 

Turn/revolutions.

AngleUnknownUnit 

Unknown angle unit.

Definition at line 98 of file qgsunittypes.h.

◆ AreaUnit

Units of area.

Enumerator
AreaSquareMeters 

Square meters.

AreaSquareKilometers 

Square kilometers.

AreaSquareFeet 

Square feet.

AreaSquareYards 

Square yards.

AreaSquareMiles 

Square miles.

AreaHectares 

Hectares.

AreaAcres 

Acres.

AreaSquareNauticalMiles 

Square nautical miles.

AreaSquareDegrees 

Square degrees, for planar geographic CRS area measurements.

AreaSquareCentimeters 

Square centimeters.

AreaSquareMillimeters 

Square millimeters.

AreaUnknownUnit 

Unknown areal unit.

Definition at line 80 of file qgsunittypes.h.

◆ DistanceUnit

Units of distance.

Enumerator
DistanceMeters 

Meters.

DistanceKilometers 

Kilometers.

DistanceFeet 

Imperial feet.

DistanceNauticalMiles 

Nautical miles.

DistanceYards 

Imperial yards.

DistanceMiles 

Terrestrial miles.

DistanceDegrees 

Degrees, for planar geographic CRS distance measurements.

DistanceCentimeters 

Centimeters.

DistanceMillimeters 

Millimeters.

DistanceUnknownUnit 

Unknown distance unit.

Definition at line 54 of file qgsunittypes.h.

◆ DistanceUnitType

Types of distance units.

Enumerator
Standard 

Unit is a standard measurement unit.

Geographic 

Unit is a geographic (e.g., degree based) unit.

UnknownType 

Unknown unit type.

Definition at line 72 of file qgsunittypes.h.

◆ LayoutUnit

Layout measurement units.

Enumerator
LayoutMillimeters 

Millimeters.

LayoutCentimeters 

Centimeters.

LayoutMeters 

Meters.

LayoutInches 

Inches.

LayoutFeet 

Feet.

LayoutPoints 

Typographic points.

LayoutPicas 

Typographic picas.

LayoutPixels 

Pixels.

Definition at line 125 of file qgsunittypes.h.

◆ LayoutUnitType

Types of layout units.

Enumerator
LayoutPaperUnits 

Unit is a paper based measurement unit.

LayoutScreenUnits 

Unit is a screen based measurement unit.

Definition at line 139 of file qgsunittypes.h.

◆ RenderUnit

Rendering size units.

Enumerator
RenderMillimeters 

Millimeters.

RenderMapUnits 

Map units.

RenderPixels 

Pixels.

RenderPercentage 

Percentage of another measurement (e.g., canvas size, feature size)

RenderPoints 

Points (e.g., for font sizes)

RenderInches 

Inches.

RenderUnknownUnit 

Mixed or unknown units.

RenderMetersInMapUnits 

Meters value as Map units.

Definition at line 111 of file qgsunittypes.h.

◆ SystemOfMeasurement

Systems of unit measurement.

Enumerator
UnknownSystem 

Unknown system of measurement.

MetricSystem 

International System of Units (SI)

ImperialSystem 

British Imperial.

USCSSystem 

United States customary system.

Definition at line 44 of file qgsunittypes.h.

Member Function Documentation

◆ decodeAngleUnit()

QgsUnitTypes::AngleUnit QgsUnitTypes::decodeAngleUnit ( const QString &  string,
bool *  ok = nullptr 
)
static

Decodes an angular unit from a string.

Parameters
stringstring to decode
okoptional boolean, will be set to true if string was converted successfully
Returns
decoded units
See also
encodeUnit()

Definition at line 1189 of file qgsunittypes.cpp.

◆ decodeAreaUnit()

QgsUnitTypes::AreaUnit QgsUnitTypes::decodeAreaUnit ( const QString &  string,
bool *  ok = nullptr 
)
static

Decodes an areal unit from a string.

Parameters
stringstring to decode
okoptional boolean, will be set to true if string was converted successfully
Returns
decoded units
See also
encodeUnit()

Definition at line 610 of file qgsunittypes.cpp.

◆ decodeDistanceUnit()

QgsUnitTypes::DistanceUnit QgsUnitTypes::decodeDistanceUnit ( const QString &  string,
bool *  ok = nullptr 
)
static

Decodes a distance unit from a string.

Parameters
stringstring to decode
okoptional boolean, will be set to true if string was converted successfully
Returns
decoded units
See also
encodeUnit()

Definition at line 118 of file qgsunittypes.cpp.

◆ decodeLayoutUnit()

QgsUnitTypes::LayoutUnit QgsUnitTypes::decodeLayoutUnit ( const QString &  string,
bool *  ok = nullptr 
)
static

Decodes a layout unit from a string.

Parameters
stringstring to decode
okoptional boolean, will be set to true if string was converted successfully
Returns
decoded units
See also
encodeUnit()
Since
QGIS 3.0

Definition at line 1847 of file qgsunittypes.cpp.

◆ decodeRenderUnit()

QgsUnitTypes::RenderUnit QgsUnitTypes::decodeRenderUnit ( const QString &  string,
bool *  ok = nullptr 
)
static

Decodes a render unit from a string.

Parameters
stringstring to decode
okoptional boolean, will be set to true if string was converted successfully
Returns
decoded units
See also
encodeUnit()

Definition at line 1752 of file qgsunittypes.cpp.

◆ distanceToAreaUnit()

QgsUnitTypes::AreaUnit QgsUnitTypes::distanceToAreaUnit ( QgsUnitTypes::DistanceUnit  distanceUnit)
static

Converts a distance unit to its corresponding area unit, e.g., meters to square meters.

Parameters
distanceUnitdistance unit to convert
Returns
matching areal unit

Definition at line 1129 of file qgsunittypes.cpp.

◆ encodeUnit() [1/5]

QString QgsUnitTypes::encodeUnit ( QgsUnitTypes::DistanceUnit  unit)
static

Encodes a distance unit to a string.

Parameters
unitunit to encode
Returns
encoded string
See also
decodeDistanceUnit()

Definition at line 75 of file qgsunittypes.cpp.

◆ encodeUnit() [2/5]

QString QgsUnitTypes::encodeUnit ( QgsUnitTypes::AreaUnit  unit)
static

Encodes an areal unit to a string.

Parameters
unitunit to encode
Returns
encoded string
See also
decodeAreaUnit()

Definition at line 578 of file qgsunittypes.cpp.

◆ encodeUnit() [3/5]

QString QgsUnitTypes::encodeUnit ( QgsUnitTypes::AngleUnit  unit)
static

Encodes an angular unit to a string.

Parameters
unitunit to encode
Returns
encoded string
See also
decodeAngleUnit()

Definition at line 1167 of file qgsunittypes.cpp.

◆ encodeUnit() [4/5]

QString QgsUnitTypes::encodeUnit ( QgsUnitTypes::RenderUnit  unit)
static

Encodes a render unit to a string.

Parameters
unitunit to encode
Returns
encoded string
See also
decodeRenderUnit()

Definition at line 1728 of file qgsunittypes.cpp.

◆ encodeUnit() [5/5]

QString QgsUnitTypes::encodeUnit ( QgsUnitTypes::LayoutUnit  unit)
static

Encodes a layout unit to a string.

Parameters
unitunit to encode
Returns
encoded string
See also
decodeLayoutUnit()
Since
QGIS 3.0

Definition at line 1823 of file qgsunittypes.cpp.

◆ formatAngle()

QString QgsUnitTypes::formatAngle ( double  angle,
int  decimals,
QgsUnitTypes::AngleUnit  unit 
)
static

Returns an angle formatted as a friendly string.

Parameters
angleangle to format
decimalsnumber of decimal places to show
unitunit of angle
Returns
formatted angle string

Definition at line 1375 of file qgsunittypes.cpp.

◆ formatArea()

QString QgsUnitTypes::formatArea ( double  area,
int  decimals,
QgsUnitTypes::AreaUnit  unit,
bool  keepBaseUnit = false 
)
static

Returns an area formatted as a friendly string.

Parameters
areaarea to format
decimalsnumber of decimal places to show
unitunit of area
keepBaseUnitset to false to allow conversion of large areas to more suitable units, e.g., square meters to square kilometers
Returns
formatted area string
See also
formatDistance()
Since
QGIS 3.0

Definition at line 1716 of file qgsunittypes.cpp.

◆ formatDistance()

QString QgsUnitTypes::formatDistance ( double  distance,
int  decimals,
QgsUnitTypes::DistanceUnit  unit,
bool  keepBaseUnit = false 
)
static

Returns an distance formatted as a friendly string.

Parameters
distancedistance to format
decimalsnumber of decimal places to show
unitunit of distance
keepBaseUnitset to false to allow conversion of large distances to more suitable units, e.g., meters to kilometers
Returns
formatted distance string
See also
formatArea()
Since
QGIS 3.0

Definition at line 1704 of file qgsunittypes.cpp.

◆ fromUnitToUnitFactor() [1/3]

double QgsUnitTypes::fromUnitToUnitFactor ( QgsUnitTypes::DistanceUnit  fromUnit,
QgsUnitTypes::DistanceUnit  toUnit 
)
static

Returns the conversion factor between the specified distance units.

Parameters
fromUnitdistance unit to convert from
toUnitdistance unit to convert to
Returns
multiplication factor to convert between units

Definition at line 305 of file qgsunittypes.cpp.

◆ fromUnitToUnitFactor() [2/3]

double QgsUnitTypes::fromUnitToUnitFactor ( QgsUnitTypes::AreaUnit  fromUnit,
QgsUnitTypes::AreaUnit  toUnit 
)
static

Returns the conversion factor between the specified areal units.

Parameters
fromUnitarea unit to convert from
toUnitarea unit to convert to
Returns
multiplication factor to convert between units

Definition at line 749 of file qgsunittypes.cpp.

◆ fromUnitToUnitFactor() [3/3]

double QgsUnitTypes::fromUnitToUnitFactor ( QgsUnitTypes::AngleUnit  fromUnit,
QgsUnitTypes::AngleUnit  toUnit 
)
static

Returns the conversion factor between the specified angular units.

Parameters
fromUnitangle unit to convert from
toUnitangle unit to convert to
Returns
multiplication factor to convert between units

Definition at line 1238 of file qgsunittypes.cpp.

◆ scaledArea()

QgsUnitTypes::AreaValue QgsUnitTypes::scaledArea ( double  area,
QgsUnitTypes::AreaUnit  unit,
int  decimals,
bool  keepBaseUnit = false 
)
static

Will convert an area with a given unit to an area value which is nice to display.

It will convert between different units (e.g. from square meters to square kilometers) if appropriate, unless forced otherwise with keepBaseUnit. The value will also be rounded to decimals (be prepared that the returned value is still a double so it will require further formatting when converting to a string).

Since
QGIS 3.0

Definition at line 1518 of file qgsunittypes.cpp.

◆ scaledDistance()

QgsUnitTypes::DistanceValue QgsUnitTypes::scaledDistance ( double  distance,
QgsUnitTypes::DistanceUnit  unit,
int  decimals,
bool  keepBaseUnit = false 
)
static

Will convert a distance with a given unit to a distance value which is nice to display.

It will convert between different units (e.g. from meters to kilometers or millimeters) if appropriate, unless forced otherwise with keepBaseUnit. The value will also be rounded to decimals (be prepared that the returned value is still a double so it will require further formatting when converting to a string).

Since
QGIS 3.0

Definition at line 1407 of file qgsunittypes.cpp.

◆ stringToAreaUnit()

QgsUnitTypes::AreaUnit QgsUnitTypes::stringToAreaUnit ( const QString &  string,
bool *  ok = nullptr 
)
static

Converts a translated string to an areal unit.

Parameters
stringstring representing an areal unit
okoptional boolean, will be set to true if string was converted successfully
Returns
the area unit
See also
toString()

Definition at line 712 of file qgsunittypes.cpp.

◆ stringToDistanceUnit()

QgsUnitTypes::DistanceUnit QgsUnitTypes::stringToDistanceUnit ( const QString &  string,
bool *  ok = nullptr 
)
static

Converts a translated string to a distance unit.

Parameters
stringstring representing a distance unit
okoptional boolean, will be set to true if string was converted successfully
Returns
the distance unit
See also
toString()

Definition at line 265 of file qgsunittypes.cpp.

◆ toAbbreviatedString() [1/4]

QString QgsUnitTypes::toAbbreviatedString ( QgsUnitTypes::DistanceUnit  unit)
static

Returns a translated abbreviation representing a distance unit.

Parameters
unitunit to convert to string
See also
stringToDistanceUnit()
Since
QGIS 3.0

Definition at line 222 of file qgsunittypes.cpp.

◆ toAbbreviatedString() [2/4]

QString QgsUnitTypes::toAbbreviatedString ( QgsUnitTypes::AreaUnit  unit)
static

Returns a translated abbreviation representing an areal unit.

Parameters
unitunit to convert to string
See also
stringToAreaUnit()
Since
QGIS 3.0

Definition at line 680 of file qgsunittypes.cpp.

◆ toAbbreviatedString() [3/4]

QString QgsUnitTypes::toAbbreviatedString ( QgsUnitTypes::RenderUnit  unit)
static

Returns a translated abbreviation representing a render unit.

Parameters
unitunit to convert to string
Since
QGIS 3.8

Definition at line 189 of file qgsunittypes.cpp.

◆ toAbbreviatedString() [4/4]

QString QgsUnitTypes::toAbbreviatedString ( QgsUnitTypes::LayoutUnit  unit)
static

Returns a translated abbreviation representing a layout unit (e.g.

"mm").

Since
QGIS 3.0

Definition at line 1898 of file qgsunittypes.cpp.

◆ toString() [1/5]

QString QgsUnitTypes::toString ( QgsUnitTypes::DistanceUnit  unit)
static

Returns a translated string representing a distance unit.

Parameters
unitunit to convert to string
See also
stringToDistanceUnit()

Definition at line 152 of file qgsunittypes.cpp.

◆ toString() [2/5]

QString QgsUnitTypes::toString ( QgsUnitTypes::AreaUnit  unit)
static

Returns a translated string representing an areal unit.

Parameters
unitunit to convert to string
See also
stringToAreaUnit()

Definition at line 648 of file qgsunittypes.cpp.

◆ toString() [3/5]

QString QgsUnitTypes::toString ( QgsUnitTypes::AngleUnit  unit)
static

Returns a translated string representing an angular unit.

Parameters
unitunit to convert to string

Definition at line 1216 of file qgsunittypes.cpp.

◆ toString() [4/5]

QString QgsUnitTypes::toString ( QgsUnitTypes::RenderUnit  unit)
static

Returns a translated string representing a render unit.

Since
QGIS 3.0

Definition at line 1789 of file qgsunittypes.cpp.

◆ toString() [5/5]

QString QgsUnitTypes::toString ( QgsUnitTypes::LayoutUnit  unit)
static

Returns a translated string representing a layout unit.

Since
QGIS 3.0

Definition at line 1922 of file qgsunittypes.cpp.

◆ unitType() [1/3]

QgsUnitTypes::DistanceUnitType QgsUnitTypes::unitType ( QgsUnitTypes::DistanceUnit  unit)
static

Returns the type for a distance unit.

Definition at line 26 of file qgsunittypes.cpp.

◆ unitType() [2/3]

QgsUnitTypes::DistanceUnitType QgsUnitTypes::unitType ( QgsUnitTypes::AreaUnit  unit)
static

Returns the type for an areal unit.

Definition at line 49 of file qgsunittypes.cpp.

◆ unitType() [3/3]

QgsUnitTypes::LayoutUnitType QgsUnitTypes::unitType ( QgsUnitTypes::LayoutUnit  units)
static

Returns the type for a unit of measurement.

Since
QGIS 3.0

Definition at line 1878 of file qgsunittypes.cpp.


The documentation for this class was generated from the following files: