QGIS API Documentation  3.8.0-Zanzibar (11aff65)
qgis.h
Go to the documentation of this file.
1 /***************************************************************************
2  qgis.h - QGIS namespace
3  -------------------
4  begin : Sat Jun 30 2002
5  copyright : (C) 2002 by Gary E.Sherman
6  email : sherman at mrcc.com
7  ***************************************************************************/
8 
9 /***************************************************************************
10  * *
11  * This program is free software; you can redistribute it and/or modify *
12  * it under the terms of the GNU General Public License as published by *
13  * the Free Software Foundation; either version 2 of the License, or *
14  * (at your option) any later version. *
15  * *
16  ***************************************************************************/
17 
18 #ifndef QGIS_H
19 #define QGIS_H
20 
21 #include <QMetaEnum>
22 #include <cfloat>
23 #include <memory>
24 #include <cmath>
25 
26 #include "qgstolerance.h"
27 #include "qgis_core.h"
28 #include "qgis_sip.h"
29 
30 #ifdef SIP_RUN
31 % ModuleHeaderCode
32 #include <qgis.h>
33 % End
34 
35 % ModuleCode
36 int QgisEvent = QEvent::User + 1;
37 % End
38 #endif
39 
40 
45 class CORE_EXPORT Qgis
46 {
47  public:
48  // Version constants
49  //
51  static const QString QGIS_VERSION;
53  static const int QGIS_VERSION_INT;
55  static const QString QGIS_RELEASE_NAME;
57  static const char *QGIS_DEV_VERSION;
58 
59  // Enumerations
60  //
61 
67  {
68  Info = 0,
69  Warning = 1,
70  Critical = 2,
71  Success = 3,
72  None = 4
73  };
74 
79  enum DataType
80  {
81  UnknownDataType = 0,
82  Byte = 1,
83  UInt16 = 2,
84  Int16 = 3,
85  UInt32 = 4,
86  Int32 = 5,
87  Float32 = 6,
88  Float64 = 7,
89  CInt16 = 8,
90  CInt32 = 9,
91  CFloat32 = 10,
92  CFloat64 = 11,
93  ARGB32 = 12,
94  ARGB32_Premultiplied = 13
95  };
96 
100  static const double DEFAULT_SEARCH_RADIUS_MM;
101 
103  static const float DEFAULT_MAPTOPIXEL_THRESHOLD;
104 
109  static const QColor DEFAULT_HIGHLIGHT_COLOR;
110 
114  static const double DEFAULT_HIGHLIGHT_BUFFER_MM;
115 
119  static const double DEFAULT_HIGHLIGHT_MIN_WIDTH_MM;
120 
126  static const double SCALE_PRECISION;
127 
132  static const double DEFAULT_Z_COORDINATE;
133 
139  static const double UI_SCALE_FACTOR;
140 
145  static const double DEFAULT_SNAP_TOLERANCE;
146 
152 };
153 
154 // hack to workaround warnings when casting void pointers
155 // retrieved from QLibrary::resolve to function pointers.
156 // It's assumed that this works on all systems supporting
157 // QLibrary
158 #define cast_to_fptr(f) f
159 
160 
169 // based on Boojum's code from http://stackoverflow.com/questions/3556687/prevent-firing-signals-in-qt
170 template<class Object> class QgsSignalBlocker SIP_SKIP SIP_SKIP // clazy:exclude=rule-of-three
171 {
172  public:
173 
178  explicit QgsSignalBlocker( Object *object )
179  : mObject( object )
180  , mPreviousState( object->blockSignals( true ) )
181  {}
182 
184  {
185  mObject->blockSignals( mPreviousState );
186  }
187 
189  Object *operator->() { return mObject; }
190 
191  private:
192 
193  Object *mObject = nullptr;
194  bool mPreviousState;
195 
196 };
197 
211 // based on Boojum's code from http://stackoverflow.com/questions/3556687/prevent-firing-signals-in-qt
212 template<class Object> inline QgsSignalBlocker<Object> whileBlocking( Object *object ) SIP_SKIP SIP_SKIP
213 {
214  return QgsSignalBlocker<Object>( object );
215 }
216 
218 CORE_EXPORT uint qHash( const QVariant &variant );
219 
225 inline QString qgsDoubleToString( double a, int precision = 17 )
226 {
227  if ( precision )
228  {
229  QString str = QString::number( a, 'f', precision );
230  if ( str.contains( QLatin1Char( '.' ) ) )
231  {
232  // remove ending 0s
233  int idx = str.length() - 1;
234  while ( str.at( idx ) == '0' && idx > 1 )
235  {
236  idx--;
237  }
238  if ( idx < str.length() - 1 )
239  str.truncate( str.at( idx ) == '.' ? idx : idx + 1 );
240  }
241  return str;
242  }
243  else
244  {
245  // avoid printing -0
246  // see https://bugreports.qt.io/browse/QTBUG-71439
247  const QString str( QString::number( a, 'f', precision ) );
248  if ( str == QLatin1String( "-0" ) )
249  {
250  return QLatin1String( "0" );
251  }
252  else
253  {
254  return str;
255  }
256  }
257 }
258 
265 inline bool qgsDoubleNear( double a, double b, double epsilon = 4 * std::numeric_limits<double>::epsilon() )
266 {
267  const double diff = a - b;
268  return diff > -epsilon && diff <= epsilon;
269 }
270 
277 inline bool qgsFloatNear( float a, float b, float epsilon = 4 * FLT_EPSILON )
278 {
279  const float diff = a - b;
280  return diff > -epsilon && diff <= epsilon;
281 }
282 
284 inline bool qgsDoubleNearSig( double a, double b, int significantDigits = 10 )
285 {
286  // The most simple would be to print numbers as %.xe and compare as strings
287  // but that is probably too costly
288  // Then the fastest would be to set some bits directly, but little/big endian
289  // has to be considered (maybe TODO)
290  // Is there a better way?
291  int aexp, bexp;
292  double ar = std::frexp( a, &aexp );
293  double br = std::frexp( b, &bexp );
294 
295  return aexp == bexp &&
296  std::round( ar * std::pow( 10.0, significantDigits ) ) == std::round( br * std::pow( 10.0, significantDigits ) );
297 }
298 
304 inline double qgsRound( double number, int places )
305 {
306  double m = ( number < 0.0 ) ? -1.0 : 1.0;
307  double scaleFactor = std::pow( 10.0, places );
308  return ( std::round( number * m * scaleFactor ) / scaleFactor ) * m;
309 }
310 
311 
312 #ifndef SIP_RUN
313 
315 
325 namespace qgis
326 {
327  // as_const
328 
337  template <typename T> struct QgsAddConst { typedef const T Type; };
338 
339  template <typename T>
340  constexpr typename QgsAddConst<T>::Type &as_const( T &t ) noexcept { return t; }
341 
342  template <typename T>
343  void as_const( const T && ) = delete;
344 
345  // make_unique - from https://stackoverflow.com/a/17902439/1861260
346 
347  template<class T> struct _Unique_if
348  {
349  typedef std::unique_ptr<T> _Single_object;
350  };
351 
352  template<class T> struct _Unique_if<T[]>
353  {
354  typedef std::unique_ptr<T[]> _Unknown_bound;
355  };
356 
357  template<class T, size_t N> struct _Unique_if<T[N]>
358  {
359  typedef void _Known_bound;
360  };
361 
362  template<class T, class... Args>
363  typename _Unique_if<T>::_Single_object
364  make_unique( Args &&... args )
365  {
366  return std::unique_ptr<T>( new T( std::forward<Args>( args )... ) );
367  }
368 
369  template<class T>
370  typename _Unique_if<T>::_Unknown_bound
371  make_unique( size_t n )
372  {
373  typedef typename std::remove_extent<T>::type U;
374  return std::unique_ptr<T>( new U[n]() );
375  }
376 
377  template<class T, class... Args>
378  typename _Unique_if<T>::_Known_bound
379  make_unique( Args &&... ) = delete;
380 
393  template<typename... Args> struct overload
394  {
395  template<typename C, typename R>
396  static constexpr auto of( R( C::*pmf )( Args... ) ) -> decltype( pmf )
397  {
398  return pmf;
399  }
400  };
401 }
403 #endif
404 
410 template<class T> const QMap<T, QString> qgsEnumMap() SIP_SKIP
411 {
412  QMetaEnum metaEnum = QMetaEnum::fromType<T>();
413  Q_ASSERT( metaEnum.isValid() );
414  QMap<T, QString> enumMap;
415  for ( int idx = 0; idx < metaEnum.keyCount(); ++idx )
416  {
417  const char *enumKey = metaEnum.key( idx );
418  enumMap.insert( static_cast<T>( metaEnum.keyToValue( enumKey ) ), QString( enumKey ) );
419  }
420  return enumMap;
421 }
422 
427 template<class T> QString qgsEnumValueToKey( const T &value ) SIP_SKIP
428 {
429  QMetaEnum metaEnum = QMetaEnum::fromType<T>();
430  Q_ASSERT( metaEnum.isValid() );
431  return QString::fromUtf8( metaEnum.valueToKey( value ) );
432 }
433 
439 template<class T> T qgsEnumKeyToValue( const QString &key, const T &defaultValue ) SIP_SKIP
440 {
441  QMetaEnum metaEnum = QMetaEnum::fromType<T>();
442  Q_ASSERT( metaEnum.isValid() );
443  bool ok = false;
444  T v = static_cast<T>( metaEnum.keyToValue( key.toUtf8().data(), &ok ) );
445  if ( ok )
446  return v;
447  else
448  return defaultValue;
449 }
450 
451 
461 CORE_EXPORT double qgsPermissiveToDouble( QString string, bool &ok );
462 
472 CORE_EXPORT int qgsPermissiveToInt( QString string, bool &ok );
473 
483 CORE_EXPORT qlonglong qgsPermissiveToLongLong( QString string, bool &ok );
484 
494 CORE_EXPORT bool qgsVariantLessThan( const QVariant &lhs, const QVariant &rhs );
495 
503 CORE_EXPORT bool qgsVariantEqual( const QVariant &lhs, const QVariant &rhs );
504 
505 
512 CORE_EXPORT bool qgsVariantGreaterThan( const QVariant &lhs, const QVariant &rhs );
513 
514 CORE_EXPORT QString qgsVsiPrefix( const QString &path );
515 
521 void CORE_EXPORT *qgsMalloc( size_t size ) SIP_SKIP;
522 
530 void CORE_EXPORT *qgsCalloc( size_t nmemb, size_t size ) SIP_SKIP;
531 
536 void CORE_EXPORT qgsFree( void *ptr ) SIP_SKIP;
537 
542 extern CORE_EXPORT const QString GEOWKT;
543 extern CORE_EXPORT const QString PROJECT_SCALES;
544 
546 extern CORE_EXPORT const QString GEOPROJ4;
548 const long GEOSRID = 4326;
550 const long GEOCRS_ID = 3452;
552 const long GEO_EPSG_CRS_ID = 4326;
554 extern CORE_EXPORT const QString GEO_EPSG_CRS_AUTHID;
555 
559 const int USER_CRS_START_ID = 100000;
560 
562 extern CORE_EXPORT const QString GEO_NONE;
563 
564 //
565 // Constants for point symbols
566 //
567 
569 const double DEFAULT_POINT_SIZE = 2.0;
570 const double DEFAULT_LINE_WIDTH = 0.26;
571 
573 const double DEFAULT_SEGMENT_EPSILON = 1e-8;
574 
576 #ifndef SIP_RUN
577 
579 const int PREVIEW_JOB_DELAY_MS = 250;
580 
582 const int MAXIMUM_LAYER_PREVIEW_TIME_MS = 250;
583 #endif
584 
586 
587 typedef QMap<QString, QString> QgsStringMap SIP_SKIP;
588 
596 typedef unsigned long long qgssize;
597 
598 #ifndef SIP_RUN
599 #if (__GNUC__ > 4 || (__GNUC__ == 4 && __GNUC_MINOR__ >= 6)) || defined(__clang__)
600 
601 #define Q_NOWARN_DEPRECATED_PUSH \
602  _Pragma("GCC diagnostic push") \
603  _Pragma("GCC diagnostic ignored \"-Wdeprecated-declarations\"");
604 #define Q_NOWARN_DEPRECATED_POP \
605  _Pragma("GCC diagnostic pop");
606 #define Q_NOWARN_UNREACHABLE_PUSH
607 #define Q_NOWARN_UNREACHABLE_POP
608 
609 #elif defined(_MSC_VER)
610 
611 #define Q_NOWARN_DEPRECATED_PUSH \
612  __pragma(warning(push)) \
613  __pragma(warning(disable:4996))
614 #define Q_NOWARN_DEPRECATED_POP \
615  __pragma(warning(pop))
616 #define Q_NOWARN_UNREACHABLE_PUSH \
617  __pragma(warning(push)) \
618  __pragma(warning(disable:4702))
619 #define Q_NOWARN_UNREACHABLE_POP \
620  __pragma(warning(pop))
621 
622 #else
623 
624 #define Q_NOWARN_DEPRECATED_PUSH
625 #define Q_NOWARN_DEPRECATED_POP
626 #define Q_NOWARN_UNREACHABLE_PUSH
627 #define Q_NOWARN_UNREACHABLE_POP
628 
629 #endif
630 #endif
631 
632 #ifndef QGISEXTERN
633 #ifdef Q_OS_WIN
634 # define QGISEXTERN extern "C" __declspec( dllexport )
635 # ifdef _MSC_VER
636 // do not warn about C bindings returning QString
637 # pragma warning(disable:4190)
638 # endif
639 #else
640 # if defined(__GNUC__) || defined(__clang__)
641 # define QGISEXTERN extern "C" __attribute__ ((visibility ("default")))
642 # else
643 # define QGISEXTERN extern "C"
644 # endif
645 #endif
646 #endif
647 #endif
648 
649 #if __cplusplus >= 201500
650 #define FALLTHROUGH [[fallthrough]];
651 #elif defined(__clang__)
652 #define FALLTHROUGH [[clang::fallthrough]];
653 #elif defined(__GNUC__) && __GNUC__ >= 7
654 #define FALLTHROUGH [[gnu::fallthrough]];
655 #else
656 #define FALLTHROUGH
657 #endif
658 
659 // see https://infektor.net/posts/2017-01-19-using-cpp17-attributes-today.html#using-the-nodiscard-attribute
660 #if __cplusplus >= 201703L
661 #define NODISCARD [[nodiscard]]
662 #elif defined(__clang__)
663 #define NODISCARD [[nodiscard]]
664 #elif defined(_MSC_VER)
665 #define NODISCARD // no support
666 #elif defined(__has_cpp_attribute)
667 #if __has_cpp_attribute(nodiscard)
668 #define NODISCARD [[nodiscard]]
669 #elif __has_cpp_attribute(gnu::warn_unused_result)
670 #define NODISCARD [[gnu::warn_unused_result]]
671 #else
672 #define NODISCARD Q_REQUIRED_RESULT
673 #endif
674 #else
675 #define NODISCARD Q_REQUIRED_RESULT
676 #endif
677 
678 #if __cplusplus >= 201703L
679 #define MAYBE_UNUSED [[maybe_unused]]
680 #elif defined(__clang__)
681 #define MAYBE_UNUSED [[maybe_unused]]
682 #elif defined(_MSC_VER)
683 #define MAYBE_UNUSED // no support
684 #elif defined(__has_cpp_attribute)
685 #if __has_cpp_attribute(gnu::unused)
686 #define MAYBE_UNUSED [[gnu::unused]]
687 #else
688 #define MAYBE_UNUSED
689 #endif
690 #else
691 #define MAYBE_UNUSED
692 #endif
693 
694 #ifndef FINAL
695 #define FINAL final
696 #endif
697 
698 
CORE_EXPORT QString qgsVsiPrefix(const QString &path)
Definition: qgis.cpp:226
int precision
static const QString QGIS_VERSION
Version string.
Definition: qgis.h:51
static const char * QGIS_DEV_VERSION
The development version.
Definition: qgis.h:57
static const double UI_SCALE_FACTOR
UI scaling factor.
Definition: qgis.h:139
bool qgsFloatNear(float a, float b, float epsilon=4 *FLT_EPSILON)
Compare two floats (but allow some difference)
Definition: qgis.h:277
CORE_EXPORT bool qgsVariantEqual(const QVariant &lhs, const QVariant &rhs)
Compares two QVariant values and returns whether they are equal, NULL values are treated as equal...
Definition: qgis.cpp:289
QString qgsEnumValueToKey(const T &value)
Returns the value for the given key of an enum.
Definition: qgis.h:427
bool qgsDoubleNear(double a, double b, double epsilon=4 *std::numeric_limits< double >::epsilon())
Compare two doubles (but allow some difference)
Definition: qgis.h:265
DataType
Raster data types.
Definition: qgis.h:79
UnitType
Type of unit of tolerance value from settings.
Definition: qgstolerance.h:40
static const QColor DEFAULT_HIGHLIGHT_COLOR
Default highlight color.
Definition: qgis.h:109
void CORE_EXPORT * qgsCalloc(size_t nmemb, size_t size)
Allocates memory for an array of nmemb elements of size bytes each and returns a pointer to the alloc...
Definition: qgis.cpp:133
MessageLevel
Level for messages This will be used both for message log and message bar in application.
Definition: qgis.h:66
static const int QGIS_VERSION_INT
Version number used for comparing versions using the "Check QGIS Version" function.
Definition: qgis.h:53
QMap< QString, QString > QgsStringMap
Definition: qgis.h:587
~QgsSignalBlocker()
Definition: qgis.h:183
The Qgis class provides global constants for use throughout the application.
Definition: qgis.h:45
CORE_EXPORT bool qgsVariantLessThan(const QVariant &lhs, const QVariant &rhs)
Compares two QVariant values and returns whether the first is less than the second.
Definition: qgis.cpp:153
static const double DEFAULT_Z_COORDINATE
Default Z coordinate value for 2.5d geometry This value have to be assigned to the Z coordinate for t...
Definition: qgis.h:132
QgsSignalBlocker(Object *object)
Constructor for QgsSignalBlocker.
Definition: qgis.h:178
T qgsEnumKeyToValue(const QString &key, const T &defaultValue)
Returns the value corresponding to the given key of an enum.
Definition: qgis.h:439
static const double DEFAULT_SNAP_TOLERANCE
Default snapping distance tolerance.
Definition: qgis.h:145
CORE_EXPORT const QString GEO_NONE
Constant that holds the string representation for "No ellips/No CRS".
Definition: qgis.cpp:71
const double DEFAULT_SEGMENT_EPSILON
Default snapping tolerance for segments.
Definition: qgis.h:573
#define SIP_SKIP
Definition: qgis_sip.h:119
QString qgsDoubleToString(double a, int precision=17)
Returns a string representation of a double.
Definition: qgis.h:225
const long GEOCRS_ID
Magic number for a geographic coord sys in QGIS srs.db tbl_srs.srs_id.
Definition: qgis.h:550
static const double DEFAULT_SEARCH_RADIUS_MM
Identify search radius in mm.
Definition: qgis.h:100
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 bet...
Definition: qgis.cpp:97
CORE_EXPORT const QString GEOPROJ4
PROJ4 string that represents a geographic coord sys.
Definition: qgis.cpp:50
RAII signal blocking class.
Definition: qgis.h:170
static const QgsTolerance::UnitType DEFAULT_SNAP_UNITS
Default snapping distance units.
Definition: qgis.h:151
void CORE_EXPORT qgsFree(void *ptr)
Frees the memory space pointed to by ptr.
Definition: qgis.cpp:148
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...
Definition: qgis.cpp:111
unsigned long long qgssize
Qgssize is used instead of size_t, because size_t is stdlib type, unknown by SIP, and it would be har...
Definition: qgis.h:596
const double DEFAULT_POINT_SIZE
Magic number that determines the default point size for point symbols.
Definition: qgis.h:569
static const float DEFAULT_MAPTOPIXEL_THRESHOLD
Default threshold between map coordinates and device coordinates for map2pixel simplification.
Definition: qgis.h:103
const int USER_CRS_START_ID
Magick number that determines whether a projection crsid is a system (srs.db) or user (~/...
Definition: qgis.h:559
const QMap< T, QString > qgsEnumMap()
Returns a map of all enum entries.
Definition: qgis.h:410
QgsSignalBlocker< Object > whileBlocking(Object *object)
Temporarily blocks signals from a QObject while calling a single method from the object.
Definition: qgis.h:212
const long GEOSRID
Magic number for a geographic coord sys in POSTGIS SRID.
Definition: qgis.h:548
static const QString QGIS_RELEASE_NAME
Release name.
Definition: qgis.h:55
double qgsRound(double number, int places)
Returns a double number, rounded (as close as possible) to the specified number of places...
Definition: qgis.h:304
bool qgsDoubleNearSig(double a, double b, int significantDigits=10)
Compare two doubles using specified number of significant digits.
Definition: qgis.h:284
const double DEFAULT_LINE_WIDTH
Definition: qgis.h:570
CORE_EXPORT const QString PROJECT_SCALES
Definition: qgis.cpp:65
CORE_EXPORT uint qHash(const QVariant &variant)
Hash for QVariant.
Definition: qgis.cpp:243
static const double DEFAULT_HIGHLIGHT_MIN_WIDTH_MM
Default highlight line/stroke minimum width in mm.
Definition: qgis.h:119
static const double DEFAULT_HIGHLIGHT_BUFFER_MM
Default highlight buffer in mm.
Definition: qgis.h:114
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 b...
Definition: qgis.cpp:104
CORE_EXPORT bool qgsVariantGreaterThan(const QVariant &lhs, const QVariant &rhs)
Compares two QVariant values and returns whether the first is greater than the second.
Definition: qgis.cpp:221
void CORE_EXPORT * qgsMalloc(size_t size)
Allocates size bytes and returns a pointer to the allocated memory.
Definition: qgis.cpp:118
Object * operator->()
Returns pointer to blocked QObject.
Definition: qgis.h:189
const long GEO_EPSG_CRS_ID
Magic number for a geographic coord sys in EpsgCrsId ID format.
Definition: qgis.h:552
static const double SCALE_PRECISION
Fudge factor used to compare two scales.
Definition: qgis.h:126
CORE_EXPORT const QString GEO_EPSG_CRS_AUTHID
Geographic coord sys from EPSG authority.
Definition: qgis.cpp:69
CORE_EXPORT const QString GEOWKT
Wkt string that represents a geographic coord sys.
Definition: qgis.cpp:52