QgsUnitTypes class

Helper functions for various unit types.

Contents

Public types

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

Public static functions

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

Enum documentation

enum QgsUnitTypes::AngleUnit

Units of angles.

Enumerators
AngleDegrees

Degrees.
AngleRadians

Square kilometers.
AngleGon

Gon/gradian.
AngleMinutesOfArc

Minutes of arc.
AngleSecondsOfArc

Seconds of arc.
AngleTurn

Turn/revolutions.
AngleUnknownUnit

Unknown angle unit.

enum QgsUnitTypes::AreaUnit

Units of area.

Enumerators
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

enum QgsUnitTypes::DistanceUnit

Units of distance.

Enumerators
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.

enum QgsUnitTypes::DistanceUnitType

Types of distance units.

Enumerators
Standard

Unit is a standard measurement unit.
Geographic

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

Unknown unit type.

enum QgsUnitTypes::LayoutUnit

Layout measurement units.

Enumerators
LayoutMillimeters

Millimeters.
LayoutCentimeters

Centimeters.
LayoutMeters

Meters.
LayoutInches

Inches.
LayoutFeet

Feet.
LayoutPoints

Typographic points.
LayoutPicas

Typographic picas.
LayoutPixels

Pixels.

enum QgsUnitTypes::LayoutUnitType

Types of layout units.

Enumerators
LayoutPaperUnits

Unit is a paper based measurement unit.
LayoutScreenUnits

Unit is a screen based measurement unit.

enum QgsUnitTypes::RenderUnit

Rendering size units.

Enumerators
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.

enum QgsUnitTypes::SystemOfMeasurement

Systems of unit measurement.

Enumerators
UnknownSystem

Unknown system of measurement.
MetricSystem

International System of Units (SI)
ImperialSystem

British Imperial.
USCSSystem

United States customary system.

Function documentation

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

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

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

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

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

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

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

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

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

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

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

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

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

Encodes a distance unit to a string.

Parameters
unit unit to encode
Returns encoded string

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

Encodes an areal unit to a string.

Parameters
unit unit to encode
Returns encoded string

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

Encodes an angular unit to a string.

Parameters
unit unit to encode
Returns encoded string

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

Encodes a render unit to a string.

Parameters
unit unit to encode
Returns encoded string

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

Encodes a layout unit to a string.

Parameters
unit unit to encode
Returns encoded string

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

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

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

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

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

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

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

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

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

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

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

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

static Q_INVOKABLE QgsUnitTypes::AreaValue QgsUnitTypes::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.

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).

static Q_INVOKABLE QgsUnitTypes::DistanceValue QgsUnitTypes::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.

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).

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

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
Returns the area unit

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

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
Returns the distance unit

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

Returns a translated abbreviation representing a distance unit.

Parameters
unit unit to convert to string

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

Returns a translated abbreviation representing an areal unit.

Parameters
unit unit to convert to string

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

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

"mm").

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

Returns a translated string representing a distance unit.

Parameters
unit unit to convert to string

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

Returns a translated string representing an areal unit.

Parameters
unit unit to convert to string

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

Returns a translated string representing an angular unit.

Parameters
unit unit to convert to string

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

Returns a translated string representing a render unit.

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

Returns a translated string representing a layout unit.

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

Returns the type for a unit of measurement.