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::RenderUnit >	RenderUnitList
	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 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 37 of file qgsunittypes.h.

Member Typedef Documentation

typedef QList<QgsUnitTypes::RenderUnit> QgsUnitTypes::RenderUnitList

List of render units.

Definition at line 183 of file qgsunittypes.h.

Member Enumeration Documentation

enum QgsUnitTypes::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 97 of file qgsunittypes.h.

enum QgsUnitTypes::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 79 of file qgsunittypes.h.

enum QgsUnitTypes::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 53 of file qgsunittypes.h.

enum QgsUnitTypes::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 71 of file qgsunittypes.h.

enum QgsUnitTypes::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 124 of file qgsunittypes.h.

enum QgsUnitTypes::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 138 of file qgsunittypes.h.

enum QgsUnitTypes::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 110 of file qgsunittypes.h.

enum QgsUnitTypes::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 43 of file qgsunittypes.h.

Member Function Documentation

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

static

Decodes an angular unit from a string.

Parameters

string	string to decode
ok	optional 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.

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

static

Decodes an areal unit from a string.

Parameters

string	string to decode
ok	optional 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.

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

static

Decodes a distance unit from a string.

Parameters

string	string to decode
ok	optional 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.

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

static

Decodes a layout unit from a string.

Parameters

string	string to decode
ok	optional 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.

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

static

Decodes a render unit from a string.

Parameters

string	string to decode
ok	optional 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.

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

static

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

Parameters

distanceUnit

distance unit to convert

Returns

matching areal unit

Definition at line 1096 of file qgsunittypes.cpp.

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

static

Encodes a distance unit to a string.

Parameters

unit	unit to encode

Returns

encoded string

See also

decodeDistanceUnit()

Definition at line 75 of file qgsunittypes.cpp.

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

static

Encodes an areal unit to a string.

Parameters

unit	unit to encode

Returns

encoded string

See also

decodeAreaUnit()

Definition at line 545 of file qgsunittypes.cpp.

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

static

Encodes an angular unit to a string.

Parameters

unit	unit to encode

Returns

encoded string

See also

decodeAngleUnit()

Definition at line 1134 of file qgsunittypes.cpp.

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

static

Encodes a render unit to a string.

Parameters

unit	unit to encode

Returns

encoded string

See also

decodeRenderUnit()

Definition at line 1695 of file qgsunittypes.cpp.

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

static

Encodes a layout unit to a string.

Parameters

unit	unit to encode

Returns

encoded string

See also

decodeLayoutUnit()

Since

QGIS 3.0

Definition at line 1790 of file qgsunittypes.cpp.

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

static

Returns an angle formatted as a friendly string.

Parameters

angle	angle to format
decimals	number of decimal places to show
unit	unit of angle

Returns

formatted angle string

Definition at line 1342 of file qgsunittypes.cpp.

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

static

Returns an area formatted as a friendly string.

Parameters

area	area to format
decimals	number of decimal places to show
unit	unit of area
keepBaseUnit	set 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.

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

static

Returns an distance formatted as a friendly string.

Parameters

distance	distance to format
decimals	number of decimal places to show
unit	unit of distance
keepBaseUnit	set 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.

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

static

Returns the conversion factor between the specified distance units.

Parameters

fromUnit	distance unit to convert from
toUnit	distance unit to convert to

Returns

multiplication factor to convert between units

Definition at line 272 of file qgsunittypes.cpp.

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

static

Returns the conversion factor between the specified areal units.

Parameters

fromUnit	area unit to convert from
toUnit	area unit to convert to

Returns

multiplication factor to convert between units

Definition at line 716 of file qgsunittypes.cpp.

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

static

Returns the conversion factor between the specified angular units.

Parameters

fromUnit	angle unit to convert from
toUnit	angle unit to convert to

Returns

multiplication factor to convert between units

Definition at line 1205 of file qgsunittypes.cpp.

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.

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.

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

static

Converts a translated string to an areal unit.

Parameters

string	string representing an areal unit
ok	optional boolean, will be set to true if string was converted successfully

See also

toString()

Definition at line 679 of file qgsunittypes.cpp.

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

static

Converts a translated string to a distance unit.

Parameters

string	string representing a distance unit
ok	optional boolean, will be set to true if string was converted successfully

See also

toString()

Definition at line 232 of file qgsunittypes.cpp.

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

static

Returns a translated abbreviation representing a distance unit.

Parameters

unit	unit to convert to string

See also

stringToDistanceUnit()

Since

QGIS 3.0

Definition at line 189 of file qgsunittypes.cpp.

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

static

Returns a translated abbreviation representing an areal unit.

Parameters

unit	unit to convert to string

See also

stringToAreaUnit()

Since

QGIS 3.0

Definition at line 647 of file qgsunittypes.cpp.

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.

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

static

Returns a translated string representing a distance unit.

Parameters

unit	unit to convert to string

See also

stringToDistanceUnit()

Definition at line 152 of file qgsunittypes.cpp.

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

static

Returns a translated string representing an areal unit.

Parameters

unit	unit to convert to string

See also

stringToAreaUnit()

Definition at line 615 of file qgsunittypes.cpp.

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

static

Returns a translated string representing an angular unit.

Parameters

unit	unit to convert to string

Definition at line 1183 of file qgsunittypes.cpp.

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.

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.

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

static

Returns the type for a distance unit.

Definition at line 26 of file qgsunittypes.cpp.

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

static

Returns the type for an areal unit.

Definition at line 49 of file qgsunittypes.cpp.

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:

• /build/qgis-3.4.15+24xenial/src/core/qgsunittypes.h
• /build/qgis-3.4.15+24xenial/src/core/qgsunittypes.cpp