QGIS API Documentation  3.4.3-Madeira (2f64a3c)
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 <QEvent>
22 #include <QString>
23 #include <QMetaType>
24 #include <QMap>
25 #include <QMetaEnum>
26 #include <QVariant>
27 #include <QDateTime>
28 #include <QDate>
29 #include <QTime>
30 #include <QHash>
31 #include <cstdlib>
32 #include <cfloat>
33 #include <memory>
34 #include <type_traits>
35 #include <cmath>
36 #include <qnumeric.h>
37 
38 #include "qgstolerance.h"
39 #include "qgswkbtypes.h"
40 #include "qgis_core.h"
41 #include "qgis_sip.h"
42 
43 #ifdef SIP_RUN
44 % ModuleHeaderCode
45 #include <qgis.h>
46 % End
47 
48 % ModuleCode
49 int QgisEvent = QEvent::User + 1;
50 % End
51 #endif
52 
53 
58 class CORE_EXPORT Qgis
59 {
60  public:
61  // Version constants
62  //
64  static const QString QGIS_VERSION;
66  static const int QGIS_VERSION_INT;
68  static const QString QGIS_RELEASE_NAME;
70  static const char *QGIS_DEV_VERSION;
71 
72  // Enumerations
73  //
74 
80  {
81  Info = 0,
82  Warning = 1,
83  Critical = 2,
84  Success = 3,
85  None = 4
86  };
87 
92  enum DataType
93  {
94  UnknownDataType = 0,
95  Byte = 1,
96  UInt16 = 2,
97  Int16 = 3,
98  UInt32 = 4,
99  Int32 = 5,
100  Float32 = 6,
101  Float64 = 7,
102  CInt16 = 8,
103  CInt32 = 9,
104  CFloat32 = 10,
105  CFloat64 = 11,
106  ARGB32 = 12,
107  ARGB32_Premultiplied = 13
108  };
109 
113  static const double DEFAULT_SEARCH_RADIUS_MM;
114 
116  static const float DEFAULT_MAPTOPIXEL_THRESHOLD;
117 
122  static const QColor DEFAULT_HIGHLIGHT_COLOR;
123 
127  static const double DEFAULT_HIGHLIGHT_BUFFER_MM;
128 
132  static const double DEFAULT_HIGHLIGHT_MIN_WIDTH_MM;
133 
139  static const double SCALE_PRECISION;
140 
145  static const double DEFAULT_Z_COORDINATE;
146 
152  static const double UI_SCALE_FACTOR;
153 
158  static const double DEFAULT_SNAP_TOLERANCE;
159 
165 };
166 
167 // hack to workaround warnings when casting void pointers
168 // retrieved from QLibrary::resolve to function pointers.
169 // It's assumed that this works on all systems supporting
170 // QLibrary
171 #define cast_to_fptr(f) f
172 
173 
182 // based on Boojum's code from http://stackoverflow.com/questions/3556687/prevent-firing-signals-in-qt
183 template<class Object> class QgsSignalBlocker SIP_SKIP SIP_SKIP // clazy:exclude=rule-of-three
184 {
185  public:
186 
191  explicit QgsSignalBlocker( Object *object )
192  : mObject( object )
193  , mPreviousState( object->blockSignals( true ) )
194  {}
195 
197  {
198  mObject->blockSignals( mPreviousState );
199  }
200 
202  Object *operator->() { return mObject; }
203 
204  private:
205 
206  Object *mObject = nullptr;
207  bool mPreviousState;
208 
209 };
210 
224 // based on Boojum's code from http://stackoverflow.com/questions/3556687/prevent-firing-signals-in-qt
225 template<class Object> inline QgsSignalBlocker<Object> whileBlocking( Object *object ) SIP_SKIP SIP_SKIP
226 {
227  return QgsSignalBlocker<Object>( object );
228 }
229 
231 CORE_EXPORT uint qHash( const QVariant &variant );
232 
238 inline QString qgsDoubleToString( double a, int precision = 17 )
239 {
240  if ( precision )
241  {
242  QString str = QString::number( a, 'f', precision );
243  if ( str.contains( QLatin1Char( '.' ) ) )
244  {
245  // remove ending 0s
246  int idx = str.length() - 1;
247  while ( str.at( idx ) == '0' && idx > 1 )
248  {
249  idx--;
250  }
251  if ( idx < str.length() - 1 )
252  str.truncate( str.at( idx ) == '.' ? idx : idx + 1 );
253  }
254  return str;
255  }
256  else
257  {
258  // avoid printing -0
259  // see https://bugreports.qt.io/browse/QTBUG-71439
260  const QString str( QString::number( a, 'f', precision ) );
261  if ( str == QLatin1String( "-0" ) )
262  {
263  return QLatin1String( "0" );
264  }
265  else
266  {
267  return str;
268  }
269  }
270 }
271 
278 inline bool qgsDoubleNear( double a, double b, double epsilon = 4 * std::numeric_limits<double>::epsilon() )
279 {
280  const double diff = a - b;
281  return diff > -epsilon && diff <= epsilon;
282 }
283 
290 inline bool qgsFloatNear( float a, float b, float epsilon = 4 * FLT_EPSILON )
291 {
292  const float diff = a - b;
293  return diff > -epsilon && diff <= epsilon;
294 }
295 
297 inline bool qgsDoubleNearSig( double a, double b, int significantDigits = 10 )
298 {
299  // The most simple would be to print numbers as %.xe and compare as strings
300  // but that is probably too costly
301  // Then the fastest would be to set some bits directly, but little/big endian
302  // has to be considered (maybe TODO)
303  // Is there a better way?
304  int aexp, bexp;
305  double ar = std::frexp( a, &aexp );
306  double br = std::frexp( b, &bexp );
307 
308  return aexp == bexp &&
309  std::round( ar * std::pow( 10.0, significantDigits ) ) == std::round( br * std::pow( 10.0, significantDigits ) );
310 }
311 
317 inline double qgsRound( double number, double places )
318 {
319  double scaleFactor = std::pow( 10.0, places );
320  return std::trunc( number * scaleFactor + 0.5 ) / scaleFactor;
321 }
322 
323 
324 #ifndef SIP_RUN
325 
327 
337 namespace qgis
338 {
339  // as_const
340 
349  template <typename T> struct QgsAddConst { typedef const T Type; };
350 
351  template <typename T>
352  constexpr typename QgsAddConst<T>::Type &as_const( T &t ) noexcept { return t; }
353 
354  template <typename T>
355  void as_const( const T && ) = delete;
356 
357  // make_unique - from https://stackoverflow.com/a/17902439/1861260
358 
359  template<class T> struct _Unique_if
360  {
361  typedef std::unique_ptr<T> _Single_object;
362  };
363 
364  template<class T> struct _Unique_if<T[]>
365  {
366  typedef std::unique_ptr<T[]> _Unknown_bound;
367  };
368 
369  template<class T, size_t N> struct _Unique_if<T[N]>
370  {
371  typedef void _Known_bound;
372  };
373 
374  template<class T, class... Args>
375  typename _Unique_if<T>::_Single_object
376  make_unique( Args &&... args )
377  {
378  return std::unique_ptr<T>( new T( std::forward<Args>( args )... ) );
379  }
380 
381  template<class T>
382  typename _Unique_if<T>::_Unknown_bound
383  make_unique( size_t n )
384  {
385  typedef typename std::remove_extent<T>::type U;
386  return std::unique_ptr<T>( new U[n]() );
387  }
388 
389  template<class T, class... Args>
390  typename _Unique_if<T>::_Known_bound
391  make_unique( Args &&... ) = delete;
392 
405  template<typename... Args> struct overload
406  {
407  template<typename C, typename R>
408  static constexpr auto of( R( C::*pmf )( Args... ) ) -> decltype( pmf )
409  {
410  return pmf;
411  }
412  };
413 }
415 #endif
416 
422 template<class T> const QMap<T, QString> qgsEnumMap() SIP_SKIP
423 {
424  QMetaEnum metaEnum = QMetaEnum::fromType<T>();
425  Q_ASSERT( metaEnum.isValid() );
426  QMap<T, QString> enumMap;
427  for ( int idx = 0; idx < metaEnum.keyCount(); ++idx )
428  {
429  const char *enumKey = metaEnum.key( idx );
430  enumMap.insert( static_cast<T>( metaEnum.keyToValue( enumKey ) ), QString( enumKey ) );
431  }
432  return enumMap;
433 };
434 
444 CORE_EXPORT double qgsPermissiveToDouble( QString string, bool &ok );
445 
455 CORE_EXPORT int qgsPermissiveToInt( QString string, bool &ok );
456 
466 CORE_EXPORT qlonglong qgsPermissiveToLongLong( QString string, bool &ok );
467 
477 CORE_EXPORT bool qgsVariantLessThan( const QVariant &lhs, const QVariant &rhs );
478 
486 CORE_EXPORT bool qgsVariantEqual( const QVariant &lhs, const QVariant &rhs );
487 
488 
495 CORE_EXPORT bool qgsVariantGreaterThan( const QVariant &lhs, const QVariant &rhs );
496 
497 CORE_EXPORT QString qgsVsiPrefix( const QString &path );
498 
504 void CORE_EXPORT *qgsMalloc( size_t size ) SIP_SKIP;
505 
513 void CORE_EXPORT *qgsCalloc( size_t nmemb, size_t size ) SIP_SKIP;
514 
519 void CORE_EXPORT qgsFree( void *ptr ) SIP_SKIP;
520 
525 extern CORE_EXPORT const QString GEOWKT;
526 extern CORE_EXPORT const QString PROJECT_SCALES;
527 
529 extern CORE_EXPORT const QString GEOPROJ4;
531 const long GEOSRID = 4326;
533 const long GEOCRS_ID = 3452;
535 const long GEO_EPSG_CRS_ID = 4326;
537 extern CORE_EXPORT const QString GEO_EPSG_CRS_AUTHID;
538 
542 const int USER_CRS_START_ID = 100000;
543 
545 extern CORE_EXPORT const QString GEO_NONE;
546 
547 //
548 // Constants for point symbols
549 //
550 
552 const double DEFAULT_POINT_SIZE = 2.0;
553 const double DEFAULT_LINE_WIDTH = 0.26;
554 
556 const double DEFAULT_SEGMENT_EPSILON = 1e-8;
557 
559 #ifndef SIP_RUN
560 
562 const int PREVIEW_JOB_DELAY_MS = 250;
563 
565 const int MAXIMUM_LAYER_PREVIEW_TIME_MS = 250;
566 #endif
567 
569 
570 typedef QMap<QString, QString> QgsStringMap SIP_SKIP;
571 
579 typedef unsigned long long qgssize;
580 
581 #ifndef SIP_RUN
582 #if (__GNUC__ > 4 || (__GNUC__ == 4 && __GNUC_MINOR__ >= 6)) || defined(__clang__)
583 
584 #define Q_NOWARN_DEPRECATED_PUSH \
585  _Pragma("GCC diagnostic push") \
586  _Pragma("GCC diagnostic ignored \"-Wdeprecated-declarations\"");
587 #define Q_NOWARN_DEPRECATED_POP \
588  _Pragma("GCC diagnostic pop");
589 #define Q_NOWARN_UNREACHABLE_PUSH
590 #define Q_NOWARN_UNREACHABLE_POP
591 
592 #elif defined(_MSC_VER)
593 
594 #define Q_NOWARN_DEPRECATED_PUSH \
595  __pragma(warning(push)) \
596  __pragma(warning(disable:4996))
597 #define Q_NOWARN_DEPRECATED_POP \
598  __pragma(warning(pop))
599 #define Q_NOWARN_UNREACHABLE_PUSH \
600  __pragma(warning(push)) \
601  __pragma(warning(disable:4702))
602 #define Q_NOWARN_UNREACHABLE_POP \
603  __pragma(warning(pop))
604 
605 #else
606 
607 #define Q_NOWARN_DEPRECATED_PUSH
608 #define Q_NOWARN_DEPRECATED_POP
609 #define Q_NOWARN_UNREACHABLE_PUSH
610 #define Q_NOWARN_UNREACHABLE_POP
611 
612 #endif
613 #endif
614 
615 #ifndef QGISEXTERN
616 #ifdef Q_OS_WIN
617 # define QGISEXTERN extern "C" __declspec( dllexport )
618 # ifdef _MSC_VER
619 // do not warn about C bindings returning QString
620 # pragma warning(disable:4190)
621 # endif
622 #else
623 # if defined(__GNUC__) || defined(__clang__)
624 # define QGISEXTERN extern "C" __attribute__ ((visibility ("default")))
625 # else
626 # define QGISEXTERN extern "C"
627 # endif
628 #endif
629 #endif
630 #endif
631 
632 #if __cplusplus >= 201500
633 #define FALLTHROUGH [[fallthrough]];
634 #elif defined(__clang__)
635 #define FALLTHROUGH [[clang::fallthrough]];
636 #elif defined(__GNUC__) && __GNUC__ >= 7
637 #define FALLTHROUGH [[gnu::fallthrough]];
638 #else
639 #define FALLTHROUGH
640 #endif
641 
642 // see https://infektor.net/posts/2017-01-19-using-cpp17-attributes-today.html#using-the-nodiscard-attribute
643 #if __cplusplus >= 201703L
644 #define NODISCARD [[nodiscard]]
645 #elif defined(__clang__)
646 #define NODISCARD [[nodiscard]]
647 #elif defined(_MSC_VER)
648 #define NODISCARD // no support
649 #elif defined(__has_cpp_attribute)
650 #if __has_cpp_attribute(nodiscard)
651 #define NODISCARD [[nodiscard]]
652 #elif __has_cpp_attribute(gnu::warn_unused_result)
653 #define NODISCARD [[gnu::warn_unused_result]]
654 #else
655 #define NODISCARD Q_REQUIRED_RESULT
656 #endif
657 #else
658 #define NODISCARD Q_REQUIRED_RESULT
659 #endif
660 
661 #if __cplusplus >= 201703L
662 #define MAYBE_UNUSED [[maybe_unused]]
663 #elif defined(__clang__)
664 #define MAYBE_UNUSED [[maybe_unused]]
665 #elif defined(_MSC_VER)
666 #define MAYBE_UNUSED // no support
667 #elif defined(__has_cpp_attribute)
668 #if __has_cpp_attribute(gnu::unused)
669 #define MAYBE_UNUSED [[gnu::unused]]
670 #else
671 #define MAYBE_UNUSED
672 #endif
673 #else
674 #define MAYBE_UNUSED
675 #endif
676 
677 #ifndef FINAL
678 #define FINAL final
679 #endif
680 
681 
CORE_EXPORT QString qgsVsiPrefix(const QString &path)
Definition: qgis.cpp:226
int precision
static const QString QGIS_VERSION
Version string.
Definition: qgis.h:64
static const char * QGIS_DEV_VERSION
The development version.
Definition: qgis.h:70
static const double UI_SCALE_FACTOR
UI scaling factor.
Definition: qgis.h:152
bool qgsFloatNear(float a, float b, float epsilon=4 *FLT_EPSILON)
Compare two floats (but allow some difference)
Definition: qgis.h:290
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:310
bool qgsDoubleNear(double a, double b, double epsilon=4 *std::numeric_limits< double >::epsilon())
Compare two doubles (but allow some difference)
Definition: qgis.h:278
DataType
Raster data types.
Definition: qgis.h:92
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:122
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:79
static const int QGIS_VERSION_INT
Version number used for comparing versions using the "Check QGIS Version" function.
Definition: qgis.h:66
QMap< QString, QString > QgsStringMap
Definition: qgis.h:570
~QgsSignalBlocker()
Definition: qgis.h:196
double qgsRound(double number, double places)
Returns a double number, rounded (as close as possible) to the specified number of places...
Definition: qgis.h:317
The Qgis class provides global constants for use throughout the application.
Definition: qgis.h:58
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:145
QgsSignalBlocker(Object *object)
Constructor for QgsSignalBlocker.
Definition: qgis.h:191
static const double DEFAULT_SNAP_TOLERANCE
Default snapping distance tolerance.
Definition: qgis.h:158
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:556
#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:238
const long GEOCRS_ID
Magic number for a geographic coord sys in QGIS srs.db tbl_srs.srs_id.
Definition: qgis.h:533
static const double DEFAULT_SEARCH_RADIUS_MM
Identify search radius in mm.
Definition: qgis.h:113
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:183
static const QgsTolerance::UnitType DEFAULT_SNAP_UNITS
Default snapping distance units.
Definition: qgis.h:164
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:579
const double DEFAULT_POINT_SIZE
Magic number that determines the default point size for point symbols.
Definition: qgis.h:552
static const float DEFAULT_MAPTOPIXEL_THRESHOLD
Default threshold between map coordinates and device coordinates for map2pixel simplification.
Definition: qgis.h:116
const int USER_CRS_START_ID
Magick number that determines whether a projection crsid is a system (srs.db) or user (~/...
Definition: qgis.h:542
const QMap< T, QString > qgsEnumMap()
Returns a map of all enum entries.
Definition: qgis.h:422
QgsSignalBlocker< Object > whileBlocking(Object *object)
Temporarily blocks signals from a QObject while calling a single method from the object.
Definition: qgis.h:225
const long GEOSRID
Magic number for a geographic coord sys in POSTGIS SRID.
Definition: qgis.h:531
static const QString QGIS_RELEASE_NAME
Release name.
Definition: qgis.h:68
bool qgsDoubleNearSig(double a, double b, int significantDigits=10)
Compare two doubles using specified number of significant digits.
Definition: qgis.h:297
const double DEFAULT_LINE_WIDTH
Definition: qgis.h:553
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:132
static const double DEFAULT_HIGHLIGHT_BUFFER_MM
Default highlight buffer in mm.
Definition: qgis.h:127
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:202
const long GEO_EPSG_CRS_ID
Magic number for a geographic coord sys in EpsgCrsId ID format.
Definition: qgis.h:535
static const double SCALE_PRECISION
Fudge factor used to compare two scales.
Definition: qgis.h:139
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