QGIS API Documentation  3.2.0-Bonn (bc43194)
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...
 

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 Q_INVOKABLE QString toAbbreviatedString (QgsUnitTypes::AreaUnit unit)
 Returns a translated abbreviation representing an areal unit. More...
 
static Q_INVOKABLE 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 Q_INVOKABLE QString toString (QgsUnitTypes::AreaUnit unit)
 Returns a translated string representing an areal unit. More...
 
static Q_INVOKABLE QString toString (QgsUnitTypes::AngleUnit unit)
 Returns a translated string representing an angular unit. More...
 
static Q_INVOKABLE QString toString (QgsUnitTypes::RenderUnit unit)
 Returns a translated string representing a render unit. More...
 
static Q_INVOKABLE 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 37 of file qgsunittypes.h.

Member Typedef Documentation

◆ RenderUnitList

List of render units.

Definition at line 173 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 87 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 
AreaSquareMillimeters 

Square centimeters.

AreaUnknownUnit 

Square millimeters.

Unknown areal unit

Definition at line 69 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 43 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 61 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 114 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 128 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 
RenderInches 

points (e.g., for font sizes)

RenderUnknownUnit 

Inches.

Mixed or unknown units

RenderMetersInMapUnits 

Meters value as Map units.

Definition at line 100 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 1156 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 577 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 1814 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 1719 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 1096 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 545 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 1134 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 1695 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 1790 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 1342 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 1683 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 1671 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 272 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 716 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 1205 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 1485 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 1374 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
See also
toString()

Definition at line 679 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
See also
toString()

Definition at line 232 of file qgsunittypes.cpp.

◆ toAbbreviatedString() [1/3]

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 189 of file qgsunittypes.cpp.

◆ toAbbreviatedString() [2/3]

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 647 of file qgsunittypes.cpp.

◆ toAbbreviatedString() [3/3]

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 1865 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 615 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 1183 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 1756 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 1889 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 1845 of file qgsunittypes.cpp.


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