QGIS API Documentation  3.37.0-Master (a5b4d9743e8)
Classes | Macros | Typedefs | Functions | Variables
qgis.h File Reference
#include <QMetaEnum>
#include <cfloat>
#include <memory>
#include <cmath>
#include "qgis_core.h"
#include "qgis_sip.h"
Include dependency graph for qgis.h:
This graph shows which files directly or indirectly include this file:

Go to the source code of this file.

Classes

class  Qgis
 The Qgis class provides global constants for use throughout the application. More...
 
class  QgsSignalBlocker< Object >
 RAII signal blocking class. More...
 

Macros

#define BUILTIN_UNREACHABLE
 
#define cast_to_fptr(f)   f
 
#define CONSTLATIN1STRING   constexpr QLatin1String
 
#define MAYBE_UNUSED
 
#define NODISCARD   Q_REQUIRED_RESULT
 
#define Q_NOWARN_DEPRECATED_POP
 
#define Q_NOWARN_DEPRECATED_PUSH
 
#define Q_NOWARN_UNREACHABLE_POP
 
#define Q_NOWARN_UNREACHABLE_PUSH
 
#define QGISEXTERN   extern "C"
 
#define QHASH_FOR_CLASS_ENUM(T)
 

Typedefs

typedef unsigned long long qgssize
 Qgssize is used instead of size_t, because size_t is stdlib type, unknown by SIP, and it would be hard to define size_t correctly in SIP. More...
 
typedef QMap< QString, QString > QgsStringMap
 

Functions

CONSTLATIN1STRING geoEpsgCrsAuthId ()
 Geographic coord sys from EPSG authority. More...
 
CONSTLATIN1STRING geoNone ()
 Constant that holds the string representation for "No ellips/No CRS". More...
 
CONSTLATIN1STRING geoProj4 ()
 PROJ4 string that represents a geographic coord sys. More...
 
CONSTLATIN1STRING geoWkt ()
 Wkt string that represents a geographic coord sys. More...
 
bool operator< (const QVariant &v1, const QVariant &v2)
 Compares two QVariant values and returns whether the first is less than the second. More...
 
bool operator> (const QVariant &v1, const QVariant &v2)
 Compares two QVariant values and returns whether the first is greater than the second. More...
 
bool qgsDoubleNear (double a, double b, double epsilon=4 *std::numeric_limits< double >::epsilon())
 Compare two doubles (but allow some difference) More...
 
bool qgsDoubleNearSig (double a, double b, int significantDigits=10)
 Compare two doubles using specified number of significant digits. More...
 
QString qgsDoubleToString (double a, int precision=17)
 Returns a string representation of a double. More...
 
template<class T >
qgsEnumKeyToValue (const QString &key, const T &defaultValue, bool tryValueAsKey=true, bool *returnOk=nullptr)
 Returns the value corresponding to the given key of an enum. More...
 
template<class T >
const QList< T > qgsEnumList ()
 Returns a list all enum entries. More...
 
template<class T >
const QMap< T, QString > qgsEnumMap ()
 Returns a map of all enum entries. More...
 
template<class T >
QString qgsEnumValueToKey (const T &value, bool *returnOk=nullptr)
 Returns the value for the given key of an enum. More...
 
template<class T >
qgsFlagKeysToValue (const QString &keys, const T &defaultValue, bool tryValueAsKey=true, bool *returnOk=nullptr)
 Returns the value corresponding to the given keys of a flag. More...
 
template<class T >
QString qgsFlagValueToKeys (const T &value, bool *returnOk=nullptr)
 Returns the value for the given keys of a flag. More...
 
bool qgsFloatNear (float a, float b, float epsilon=4 *FLT_EPSILON)
 Compare two floats (but allow some difference) More...
 
void CORE_EXPORT qgsFree (void *ptr)
 Frees the memory space pointed to by ptr. More...
 
void CORE_EXPORT * qgsMalloc (size_t size)
 Allocates size bytes and returns a pointer to the allocated memory. More...
 
template<class Key , class Value >
QString qgsMapJoinKeys (const QMap< Key, Value > &map, const QString &separator)
 Joins all the map keys into a single string with each element separated by the given separator. More...
 
template<class Key , class Value >
QString qgsMapJoinValues (const QMap< Key, Value > &map, const QString &separator)
 Joins all the map values into a single string with each element separated by the given separator. More...
 
bool qgsNanCompatibleEquals (double a, double b)
 Compare two doubles, treating nan values as equal. More...
 
template<typename T >
bool qgsNumberNear (T a, T b, T epsilon=std::numeric_limits< T >::epsilon() *4)
 Compare two numbers of type T (but allow some difference) More...
 
CORE_EXPORT double qgsPermissiveToDouble (QString string, bool &ok)
 Converts a string to a double in a permissive way, e.g., allowing for incorrect numbers of digits between thousand separators. More...
 
CORE_EXPORT int qgsPermissiveToInt (QString string, bool &ok)
 Converts a string to an integer in a permissive way, e.g., allowing for incorrect numbers of digits between thousand separators. More...
 
CORE_EXPORT qlonglong qgsPermissiveToLongLong (QString string, bool &ok)
 Converts a string to an qlonglong in a permissive way, e.g., allowing for incorrect numbers of digits between thousand separators. More...
 
double qgsRound (double number, int places)
 Returns a double number, rounded (as close as possible) to the specified number of places. More...
 
template<class T >
QString qgsSetJoin (const QSet< T > &set, const QString &separator)
 Joins all the set values into a single string with each element separated by the given separator. More...
 
CORE_EXPORT bool qgsVariantEqual (const QVariant &lhs, const QVariant &rhs)
 Compares two QVariant values and returns whether they are equal, two NULL values are always treated as equal and 0 is not treated as equal with NULL. More...
 
CORE_EXPORT bool qgsVariantGreaterThan (const QVariant &lhs, const QVariant &rhs)
 Compares two QVariant values and returns whether the first is greater than the second. More...
 
CORE_EXPORT bool qgsVariantLessThan (const QVariant &lhs, const QVariant &rhs)
 Compares two QVariant values and returns whether the first is less than the second. More...
 
CORE_EXPORT QString qgsVsiPrefix (const QString &path)
 
CORE_EXPORT uint qHash (const QVariant &variant)
 Hash for QVariant. More...
 
template<class Object >
QgsSignalBlocker< Object > whileBlocking (Object *object)
 Temporarily blocks signals from a QObject while calling a single method from the object. More...
 

Variables

const double DEFAULT_LINE_WIDTH = 0.26
 
const double DEFAULT_POINT_SIZE = 2.0
 Magic number that determines the default point size for point symbols. More...
 
const double DEFAULT_SEGMENT_EPSILON = 1e-8
 Default snapping tolerance for segments. More...
 
const long GEO_EPSG_CRS_ID = 4326
 Magic number for a geographic coord sys in EpsgCrsId ID format. More...
 
const long GEOCRS_ID = 3452
 Magic number for a geographic coord sys in QGIS srs.db tbl_srs.srs_id. More...
 
const long GEOSRID = 4326
 Magic number for a geographic coord sys in POSTGIS SRID. More...
 
const int USER_CRS_START_ID = 100000
 Magick number that determines whether a projection crsid is a system (srs.db) or user (~/.qgis.qgis.db) defined projection. More...
 

Macro Definition Documentation

◆ BUILTIN_UNREACHABLE

#define BUILTIN_UNREACHABLE

Definition at line 5818 of file qgis.h.

◆ cast_to_fptr

#define cast_to_fptr (   f)    f

Definition at line 5024 of file qgis.h.

◆ CONSTLATIN1STRING

#define CONSTLATIN1STRING   constexpr QLatin1String

Definition at line 5600 of file qgis.h.

◆ MAYBE_UNUSED

#define MAYBE_UNUSED

Definition at line 5793 of file qgis.h.

◆ NODISCARD

#define NODISCARD   Q_REQUIRED_RESULT

Definition at line 5777 of file qgis.h.

◆ Q_NOWARN_DEPRECATED_POP

#define Q_NOWARN_DEPRECATED_POP

Definition at line 5741 of file qgis.h.

◆ Q_NOWARN_DEPRECATED_PUSH

#define Q_NOWARN_DEPRECATED_PUSH

Definition at line 5740 of file qgis.h.

◆ Q_NOWARN_UNREACHABLE_POP

#define Q_NOWARN_UNREACHABLE_POP

Definition at line 5743 of file qgis.h.

◆ Q_NOWARN_UNREACHABLE_PUSH

#define Q_NOWARN_UNREACHABLE_PUSH

Definition at line 5742 of file qgis.h.

◆ QGISEXTERN

#define QGISEXTERN   extern "C"

Definition at line 5755 of file qgis.h.

◆ QHASH_FOR_CLASS_ENUM

#define QHASH_FOR_CLASS_ENUM (   T)
Value:
inline uint qHash(const T &t, uint seed) { \
return ::qHash(static_cast<typename std::underlying_type<T>::type>(t), seed); \
}
CORE_EXPORT uint qHash(const QVariant &variant)
Hash for QVariant.
Definition: qgis.cpp:198

Definition at line 43 of file qgis.h.

Typedef Documentation

◆ qgssize

typedef unsigned long long qgssize

Qgssize is used instead of size_t, because size_t is stdlib type, unknown by SIP, and it would be hard to define size_t correctly in SIP.

Currently used "unsigned long long" was introduced in C++11 (2011) but it was supported already before C++11 on common platforms. "unsigned long long int" gives syntax error in SIP. KEEP IN SYNC WITH qgssize defined in SIP!

Definition at line 5712 of file qgis.h.

◆ QgsStringMap

typedef QMap<QString, QString> QgsStringMap

Definition at line 5702 of file qgis.h.

Function Documentation

◆ geoEpsgCrsAuthId()

CONSTLATIN1STRING geoEpsgCrsAuthId ( )

Geographic coord sys from EPSG authority.

Definition at line 5653 of file qgis.h.

◆ geoNone()

CONSTLATIN1STRING geoNone ( )

Constant that holds the string representation for "No ellips/No CRS".

Definition at line 5659 of file qgis.h.

◆ geoProj4()

CONSTLATIN1STRING geoProj4 ( )

PROJ4 string that represents a geographic coord sys.

Definition at line 5647 of file qgis.h.

◆ geoWkt()

CONSTLATIN1STRING geoWkt ( )

Wkt string that represents a geographic coord sys.

Since
QGIS GEOWkt

Definition at line 5639 of file qgis.h.

◆ operator<()

bool operator< ( const QVariant &  v1,
const QVariant &  v2 
)
inline

Compares two QVariant values and returns whether the first is less than the second.

Useful for sorting lists of variants, correctly handling sorting of the various QVariant data types (such as strings, numeric values, dates and times)

Invalid < NULL < Values

See also
qgsVariantGreaterThan()

Definition at line 5565 of file qgis.h.

◆ operator>()

bool operator> ( const QVariant &  v1,
const QVariant &  v2 
)
inline

Compares two QVariant values and returns whether the first is greater than the second.

Useful for sorting lists of variants, correctly handling sorting of the various QVariant data types (such as strings, numeric values, dates and times)

See also
qgsVariantLessThan()

Definition at line 5551 of file qgis.h.

◆ qgsDoubleNear()

bool qgsDoubleNear ( double  a,
double  b,
double  epsilon = 4 * std::numeric_limits<double>::epsilon() 
)
inline

Compare two doubles (but allow some difference)

Parameters
afirst double
bsecond double
epsilonmaximum difference allowable between doubles

Definition at line 5172 of file qgis.h.

◆ qgsDoubleNearSig()

bool qgsDoubleNearSig ( double  a,
double  b,
int  significantDigits = 10 
)
inline

Compare two doubles using specified number of significant digits.

Definition at line 5189 of file qgis.h.

◆ qgsDoubleToString()

QString qgsDoubleToString ( double  a,
int  precision = 17 
)
inline

Returns a string representation of a double.

Parameters
adouble value
precisionnumber of decimal places to retain

Definition at line 5089 of file qgis.h.

◆ qgsEnumKeyToValue()

template<class T >
T qgsEnumKeyToValue ( const QString &  key,
const T &  defaultValue,
bool  tryValueAsKey = true,
bool *  returnOk = nullptr 
)

Returns the value corresponding to the given key of an enum.

If the key is invalid, it will return the defaultValue. If tryValueAsKey is true, it will try to convert the string key to an enum value If returnOk is given, it defines if the key could be converted to the value or if it had returned the default

Since
QGIS 3.6

Definition at line 5382 of file qgis.h.

◆ qgsEnumList()

template<class T >
const QList<T> qgsEnumList ( )

Returns a list all enum entries.

The enum must have been declared using Q_ENUM or Q_FLAG.

Definition at line 5329 of file qgis.h.

◆ qgsEnumMap()

template<class T >
const QMap<T, QString> qgsEnumMap ( )

Returns a map of all enum entries.

The map has the enum values (int) as keys and the enum keys (QString) as values. The enum must have been declared using Q_ENUM or Q_FLAG.

Definition at line 5346 of file qgis.h.

◆ qgsEnumValueToKey()

template<class T >
QString qgsEnumValueToKey ( const T &  value,
bool *  returnOk = nullptr 
)

Returns the value for the given key of an enum.

If returnOk is given, it defines if the value could be converted to the key

Since
QGIS 3.6

Definition at line 5363 of file qgis.h.

◆ qgsFlagKeysToValue()

template<class T >
T qgsFlagKeysToValue ( const QString &  keys,
const T &  defaultValue,
bool  tryValueAsKey = true,
bool *  returnOk = nullptr 
)

Returns the value corresponding to the given keys of a flag.

If the keys are invalid, it will return the defaultValue. If tryValueAsKey is true, it will try to convert the string key to an enum value. If returnOk is given, it defines if the key could be converted to the value or if it had returned the default

Since
QGIS 3.16

Definition at line 5443 of file qgis.h.

◆ qgsFlagValueToKeys()

template<class T >
QString qgsFlagValueToKeys ( const T &  value,
bool *  returnOk = nullptr 
)

Returns the value for the given keys of a flag.

If returnOk is given, it defines if the value could be converted to the keys

Since
QGIS 3.16

Definition at line 5421 of file qgis.h.

◆ qgsFloatNear()

bool qgsFloatNear ( float  a,
float  b,
float  epsilon = 4 * FLT_EPSILON 
)
inline

Compare two floats (but allow some difference)

Parameters
afirst float
bsecond float
epsilonmaximum difference allowable between floats

Definition at line 5183 of file qgis.h.

◆ qgsFree()

void CORE_EXPORT qgsFree ( void *  ptr)

Frees the memory space pointed to by ptr.

Works like C free().

Parameters
ptrpointer to memory space

Definition at line 115 of file qgis.cpp.

◆ qgsMalloc()

void CORE_EXPORT* qgsMalloc ( size_t  size)

Allocates size bytes and returns a pointer to the allocated memory.

Works like C malloc() but prints debug message by QgsLogger if allocation fails.

Parameters
sizesize in bytes

Definition at line 93 of file qgis.cpp.

◆ qgsMapJoinKeys()

template<class Key , class Value >
QString qgsMapJoinKeys ( const QMap< Key, Value > &  map,
const QString &  separator 
)

Joins all the map keys into a single string with each element separated by the given separator.

This method avoid calling keys() before joining because it creates an unneeded temporary list see clazy container-anti-pattern

Definition at line 5229 of file qgis.h.

◆ qgsMapJoinValues()

template<class Key , class Value >
QString qgsMapJoinValues ( const QMap< Key, Value > &  map,
const QString &  separator 
)

Joins all the map values into a single string with each element separated by the given separator.

This method avoid calling values() before joining because it creates an unneeded temporary list see clazy container-anti-pattern

Definition at line 5246 of file qgis.h.

◆ qgsNanCompatibleEquals()

bool qgsNanCompatibleEquals ( double  a,
double  b 
)
inline

Compare two doubles, treating nan values as equal.

Parameters
afirst double
bsecond double
Since
QGIS 3.20

Definition at line 5134 of file qgis.h.

◆ qgsNumberNear()

template<typename T >
bool qgsNumberNear ( a,
b,
epsilon = std::numeric_limits<T>::epsilon() * 4 
)
inline

Compare two numbers of type T (but allow some difference)

Parameters
afirst number
bsecond number
epsilonmaximum difference allowable between numbers
Since
QGIS 3.36

Definition at line 5154 of file qgis.h.

◆ qgsPermissiveToDouble()

CORE_EXPORT double qgsPermissiveToDouble ( QString  string,
bool &  ok 
)

Converts a string to a double in a permissive way, e.g., allowing for incorrect numbers of digits between thousand separators.

Parameters
stringstring to convert
okwill be set to true if conversion was successful
Returns
string converted to double if possible
See also
permissiveToInt

Definition at line 72 of file qgis.cpp.

◆ qgsPermissiveToInt()

CORE_EXPORT int qgsPermissiveToInt ( QString  string,
bool &  ok 
)

Converts a string to an integer in a permissive way, e.g., allowing for incorrect numbers of digits between thousand separators.

Parameters
stringstring to convert
okwill be set to true if conversion was successful
Returns
string converted to int if possible
See also
permissiveToDouble

Definition at line 79 of file qgis.cpp.

◆ qgsPermissiveToLongLong()

CORE_EXPORT qlonglong qgsPermissiveToLongLong ( QString  string,
bool &  ok 
)

Converts a string to an qlonglong in a permissive way, e.g., allowing for incorrect numbers of digits between thousand separators.

Parameters
stringstring to convert
okwill be set to true if conversion was successful
Returns
string converted to int if possible
See also
permissiveToInt
Since
QGIS 3.4

Definition at line 86 of file qgis.cpp.

◆ qgsRound()

double qgsRound ( double  number,
int  places 
)
inline

Returns a double number, rounded (as close as possible) to the specified number of places.

Definition at line 5213 of file qgis.h.

◆ qgsSetJoin()

template<class T >
QString qgsSetJoin ( const QSet< T > &  set,
const QString &  separator 
)

Joins all the set values into a single string with each element separated by the given separator.

This method avoid calling values() before joining because it creates an unneeded temporary list see clazy container-anti-pattern

Definition at line 5263 of file qgis.h.

◆ qgsVariantEqual()

CORE_EXPORT bool qgsVariantEqual ( const QVariant &  lhs,
const QVariant &  rhs 
)

Compares two QVariant values and returns whether they are equal, two NULL values are always treated as equal and 0 is not treated as equal with NULL.

Parameters
lhsfirst value
rhssecond value
Returns
true if values are equal

Definition at line 247 of file qgis.cpp.

◆ qgsVariantGreaterThan()

CORE_EXPORT bool qgsVariantGreaterThan ( const QVariant &  lhs,
const QVariant &  rhs 
)

Compares two QVariant values and returns whether the first is greater than the second.

Useful for sorting lists of variants, correctly handling sorting of the various QVariant data types (such as strings, numeric values, dates and times)

See also
qgsVariantLessThan()

Definition at line 188 of file qgis.cpp.

◆ qgsVariantLessThan()

CORE_EXPORT bool qgsVariantLessThan ( const QVariant &  lhs,
const QVariant &  rhs 
)

Compares two QVariant values and returns whether the first is less than the second.

Useful for sorting lists of variants, correctly handling sorting of the various QVariant data types (such as strings, numeric values, dates and times)

Invalid < NULL < Values

See also
qgsVariantGreaterThan()

Definition at line 120 of file qgis.cpp.

◆ qgsVsiPrefix()

CORE_EXPORT QString qgsVsiPrefix ( const QString &  path)

Definition at line 193 of file qgis.cpp.

◆ qHash()

CORE_EXPORT uint qHash ( const QVariant &  variant)

Hash for QVariant.

Definition at line 198 of file qgis.cpp.

◆ whileBlocking()

template<class Object >
QgsSignalBlocker<Object> whileBlocking ( Object *  object)
inline

Temporarily blocks signals from a QObject while calling a single method from the object.

Usage: whileBlocking( checkBox )->setChecked( true ); whileBlocking( spinBox )->setValue( 50 );

No signals will be emitted when calling these methods.

See also
QgsSignalBlocker
Note
not available in Python bindings

Definition at line 5076 of file qgis.h.

Variable Documentation

◆ DEFAULT_LINE_WIDTH

const double DEFAULT_LINE_WIDTH = 0.26

Definition at line 5697 of file qgis.h.

◆ DEFAULT_POINT_SIZE

const double DEFAULT_POINT_SIZE = 2.0

Magic number that determines the default point size for point symbols.

Definition at line 5696 of file qgis.h.

◆ DEFAULT_SEGMENT_EPSILON

const double DEFAULT_SEGMENT_EPSILON = 1e-8

Default snapping tolerance for segments.

Definition at line 5700 of file qgis.h.

◆ GEO_EPSG_CRS_ID

const long GEO_EPSG_CRS_ID = 4326

Magic number for a geographic coord sys in EpsgCrsId ID format.

Definition at line 5683 of file qgis.h.

◆ GEOCRS_ID

const long GEOCRS_ID = 3452

Magic number for a geographic coord sys in QGIS srs.db tbl_srs.srs_id.

Definition at line 5680 of file qgis.h.

◆ GEOSRID

const long GEOSRID = 4326

Magic number for a geographic coord sys in POSTGIS SRID.

Definition at line 5677 of file qgis.h.

◆ USER_CRS_START_ID

const int USER_CRS_START_ID = 100000

Magick number that determines whether a projection crsid is a system (srs.db) or user (~/.qgis.qgis.db) defined projection.

Definition at line 5689 of file qgis.h.