QGIS API Documentation  2.99.0-Master (a411669)
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 "qgis_sip.h"
23 #include <QString>
24 #include <QRegExp>
25 #include <QMetaType>
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 "qgswkbtypes.h"
39 #include "qgis_core.h"
40 #include "qgis_sip.h"
41 
42 #ifdef SIP_RUN
43 % ModuleHeaderCode
44 #include <qgis.h>
45 % End
46 
47 % ModuleCode
48 int QgisEvent = QEvent::User + 1;
49 % End
50 #endif
51 
52 
57 class CORE_EXPORT Qgis
58 {
59  public:
60  // Version constants
61  //
63  static const QString QGIS_VERSION;
65  static const int QGIS_VERSION_INT;
67  static const QString QGIS_RELEASE_NAME;
69  static const char *QGIS_DEV_VERSION;
70 
71  // Enumerations
72  //
73 
78  enum DataType
79  {
80  UnknownDataType = 0,
81  Byte = 1,
82  UInt16 = 2,
83  Int16 = 3,
84  UInt32 = 4,
85  Int32 = 5,
86  Float32 = 6,
87  Float64 = 7,
88  CInt16 = 8,
89  CInt32 = 9,
90  CFloat32 = 10,
91  CFloat64 = 11,
92  ARGB32 = 12,
93  ARGB32_Premultiplied = 13
94  };
95 
99  static const double DEFAULT_SEARCH_RADIUS_MM;
100 
102  static const float DEFAULT_MAPTOPIXEL_THRESHOLD;
103 
108  static const QColor DEFAULT_HIGHLIGHT_COLOR;
109 
113  static const double DEFAULT_HIGHLIGHT_BUFFER_MM;
114 
118  static const double DEFAULT_HIGHLIGHT_MIN_WIDTH_MM;
119 
125  static const double SCALE_PRECISION;
126 
131  static const double DEFAULT_Z_COORDINATE;
132 
138  static const double UI_SCALE_FACTOR;
139 
140 };
141 
142 // hack to workaround warnings when casting void pointers
143 // retrieved from QLibrary::resolve to function pointers.
144 // It's assumed that this works on all systems supporting
145 // QLibrary
146 #define cast_to_fptr(f) f
147 
148 
157 // based on Boojum's code from http://stackoverflow.com/questions/3556687/prevent-firing-signals-in-qt
158 template<class Object> class QgsSignalBlocker SIP_SKIP SIP_SKIP // clazy:exclude=rule-of-three
159 {
160  public:
161 
166  explicit QgsSignalBlocker( Object *object )
167  : mObject( object )
168  , mPreviousState( object->blockSignals( true ) )
169  {}
170 
172  {
173  mObject->blockSignals( mPreviousState );
174  }
175 
177  Object *operator->() { return mObject; }
178 
179  private:
180 
181  Object *mObject = nullptr;
182  bool mPreviousState;
183 
184 };
185 
199 // based on Boojum's code from http://stackoverflow.com/questions/3556687/prevent-firing-signals-in-qt
200 template<class Object> inline QgsSignalBlocker<Object> whileBlocking( Object *object ) SIP_SKIP SIP_SKIP
201 {
202  return QgsSignalBlocker<Object>( object );
203 }
204 
206 CORE_EXPORT uint qHash( const QVariant &variant );
207 
213 inline QString qgsDoubleToString( double a, int precision = 17 )
214 {
215  if ( precision )
216  return QString::number( a, 'f', precision ).remove( QRegExp( "\\.?0+$" ) );
217  else
218  return QString::number( a, 'f', precision );
219 }
220 
227 inline bool qgsDoubleNear( double a, double b, double epsilon = 4 * DBL_EPSILON )
228 {
229  const double diff = a - b;
230  return diff > -epsilon && diff <= epsilon;
231 }
232 
239 inline bool qgsFloatNear( float a, float b, float epsilon = 4 * FLT_EPSILON )
240 {
241  const float diff = a - b;
242  return diff > -epsilon && diff <= epsilon;
243 }
244 
246 inline bool qgsDoubleNearSig( double a, double b, int significantDigits = 10 )
247 {
248  // The most simple would be to print numbers as %.xe and compare as strings
249  // but that is probably too costly
250  // Then the fastest would be to set some bits directly, but little/big endian
251  // has to be considered (maybe TODO)
252  // Is there a better way?
253  int aexp, bexp;
254  double ar = std::frexp( a, &aexp );
255  double br = std::frexp( b, &bexp );
256 
257  return aexp == bexp &&
258  std::round( ar * std::pow( 10.0, significantDigits ) ) == std::round( br * std::pow( 10.0, significantDigits ) );
259 }
260 
266 inline double qgsRound( double number, double places )
267 {
268  int scaleFactor = std::pow( 10, places );
269  return static_cast<double>( static_cast<qlonglong>( number * scaleFactor + 0.5 ) ) / scaleFactor;
270 }
271 
272 
273 #ifndef SIP_RUN
274 
276 
285 namespace qgis
286 {
287  // as_const
288 
297  template <typename T> struct QgsAddConst { typedef const T Type; };
298 
299  template <typename T>
300  constexpr typename QgsAddConst<T>::Type &as_const( T &t ) noexcept { return t; }
301 
302  template <typename T>
303  void as_const( const T && ) = delete;
304 
305  // make_unique - from https://stackoverflow.com/a/17902439/1861260
306 
307  template<class T> struct _Unique_if
308  {
309  typedef std::unique_ptr<T> _Single_object;
310  };
311 
312  template<class T> struct _Unique_if<T[]>
313  {
314  typedef std::unique_ptr<T[]> _Unknown_bound;
315  };
316 
317  template<class T, size_t N> struct _Unique_if<T[N]>
318  {
319  typedef void _Known_bound;
320  };
321 
322  template<class T, class... Args>
323  typename _Unique_if<T>::_Single_object
324  make_unique( Args &&... args )
325  {
326  return std::unique_ptr<T>( new T( std::forward<Args>( args )... ) );
327  }
328 
329  template<class T>
330  typename _Unique_if<T>::_Unknown_bound
331  make_unique( size_t n )
332  {
333  typedef typename std::remove_extent<T>::type U;
334  return std::unique_ptr<T>( new U[n]() );
335  }
336 
337  template<class T, class... Args>
338  typename _Unique_if<T>::_Known_bound
339  make_unique( Args &&... ) = delete;
340 }
342 #endif
343 
353 CORE_EXPORT double qgsPermissiveToDouble( QString string, bool &ok );
354 
364 CORE_EXPORT int qgsPermissiveToInt( QString string, bool &ok );
365 
372 CORE_EXPORT bool qgsVariantLessThan( const QVariant &lhs, const QVariant &rhs );
373 
380 CORE_EXPORT bool qgsVariantGreaterThan( const QVariant &lhs, const QVariant &rhs );
381 
382 CORE_EXPORT QString qgsVsiPrefix( const QString &path );
383 
389 void CORE_EXPORT *qgsMalloc( size_t size ) SIP_SKIP;
390 
398 void CORE_EXPORT *qgsCalloc( size_t nmemb, size_t size ) SIP_SKIP;
399 
404 void CORE_EXPORT qgsFree( void *ptr ) SIP_SKIP;
405 
410 extern CORE_EXPORT const QString GEOWKT;
411 extern CORE_EXPORT const QString PROJECT_SCALES;
412 
414 extern CORE_EXPORT const QString GEOPROJ4;
416 const long GEOSRID = 4326;
418 const long GEOCRS_ID = 3452;
420 const long GEO_EPSG_CRS_ID = 4326;
422 extern CORE_EXPORT const QString GEO_EPSG_CRS_AUTHID;
423 
427 const int USER_CRS_START_ID = 100000;
428 
430 extern CORE_EXPORT const QString GEO_NONE;
431 
432 //
433 // Constants for point symbols
434 //
435 
437 const double DEFAULT_POINT_SIZE = 2.0;
438 const double DEFAULT_LINE_WIDTH = 0.26;
439 
441 const double DEFAULT_SEGMENT_EPSILON = 1e-8;
442 
443 typedef QMap<QString, QString> QgsStringMap SIP_SKIP;
444 
452 typedef unsigned long long qgssize;
453 
454 #ifndef SIP_RUN
455 #if (__GNUC__ > 4 || (__GNUC__ == 4 && __GNUC_MINOR__ >= 6)) || defined(__clang__)
456 
457 #define Q_NOWARN_DEPRECATED_PUSH \
458  _Pragma("GCC diagnostic push") \
459  _Pragma("GCC diagnostic ignored \"-Wdeprecated-declarations\"");
460 #define Q_NOWARN_DEPRECATED_POP \
461  _Pragma("GCC diagnostic pop");
462 #define Q_NOWARN_UNREACHABLE_PUSH
463 #define Q_NOWARN_UNREACHABLE_POP
464 
465 #elif defined(_MSC_VER)
466 
467 #define Q_NOWARN_DEPRECATED_PUSH \
468  __pragma(warning(push)) \
469  __pragma(warning(disable:4996))
470 #define Q_NOWARN_DEPRECATED_POP \
471  __pragma(warning(pop))
472 #define Q_NOWARN_UNREACHABLE_PUSH \
473  __pragma(warning(push)) \
474  __pragma(warning(disable:4702))
475 #define Q_NOWARN_UNREACHABLE_POP \
476  __pragma(warning(pop))
477 
478 #else
479 
480 #define Q_NOWARN_DEPRECATED_PUSH
481 #define Q_NOWARN_DEPRECATED_POP
482 #define Q_NOWARN_UNREACHABLE_PUSH
483 #define Q_NOWARN_UNREACHABLE_POP
484 
485 #endif
486 #endif
487 
488 #ifndef QGISEXTERN
489 #ifdef Q_OS_WIN
490 # define QGISEXTERN extern "C" __declspec( dllexport )
491 # ifdef _MSC_VER
492 // do not warn about C bindings returning QString
493 # pragma warning(disable:4190)
494 # endif
495 #else
496 # if defined(__GNUC__) || defined(__clang__)
497 # define QGISEXTERN extern "C" __attribute__ ((visibility ("default")))
498 # else
499 # define QGISEXTERN extern "C"
500 # endif
501 #endif
502 #endif
503 #endif
504 
505 #if __cplusplus >= 201500
506 #define FALLTHROUGH [[fallthrough]];
507 #elif defined(__clang__)
508 #define FALLTHROUGH //[[clang::fallthrough]]
509 #elif defined(__GNUC__) && __GNUC__ >= 7
510 #define FALLTHROUGH [[gnu::fallthrough]];
511 #else
512 #define FALLTHROUGH
513 #endif
514 
515 
CORE_EXPORT QString qgsVsiPrefix(const QString &path)
Definition: qgis.cpp:215
static const QString QGIS_VERSION
Version string.
Definition: qgis.h:63
static const char * QGIS_DEV_VERSION
The development version.
Definition: qgis.h:69
static const double UI_SCALE_FACTOR
UI scaling factor.
Definition: qgis.h:138
bool qgsFloatNear(float a, float b, float epsilon=4 *FLT_EPSILON)
Compare two floats (but allow some difference)
Definition: qgis.h:239
DataType
Raster data types.
Definition: qgis.h:78
static const QColor DEFAULT_HIGHLIGHT_COLOR
Default highlight color.
Definition: qgis.h:108
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:122
static const int QGIS_VERSION_INT
Version number used for comparing versions using the "Check QGIS Version" function.
Definition: qgis.h:65
QMap< QString, QString > QgsStringMap
Definition: qgis.h:443
~QgsSignalBlocker()
Definition: qgis.h:171
bool qgsDoubleNear(double a, double b, double epsilon=4 *DBL_EPSILON)
Compare two doubles (but allow some difference)
Definition: qgis.h:227
double qgsRound(double number, double places)
Returns a double number, rounded (as close as possible) to the specified number of places...
Definition: qgis.h:266
The Qgis class provides global constants for use throughout the application.
Definition: qgis.h:57
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:142
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:131
QgsSignalBlocker(Object *object)
Constructor for QgsSignalBlocker.
Definition: qgis.h:166
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:441
#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:213
const long GEOCRS_ID
Magic number for a geographic coord sys in QGIS srs.db tbl_srs.srs_id.
Definition: qgis.h:418
static const double DEFAULT_SEARCH_RADIUS_MM
Identify search radius in mm.
Definition: qgis.h:99
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:93
CORE_EXPORT const QString GEOPROJ4
PROJ4 string that represents a geographic coord sys.
Definition: qgis.cpp:50
RAII signal blocking class.
Definition: qgis.h:158
void CORE_EXPORT qgsFree(void *ptr)
Frees the memory space pointed to by ptr.
Definition: qgis.cpp:137
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:452
const double DEFAULT_POINT_SIZE
Magic number that determines the default point size for point symbols.
Definition: qgis.h:437
static const float DEFAULT_MAPTOPIXEL_THRESHOLD
Default threshold between map coordinates and device coordinates for map2pixel simplification.
Definition: qgis.h:102
const int USER_CRS_START_ID
Magick number that determines whether a projection crsid is a system (srs.db) or user (~/...
Definition: qgis.h:427
QgsSignalBlocker< Object > whileBlocking(Object *object)
Temporarily blocks signals from a QObject while calling a single method from the object.
Definition: qgis.h:200
const long GEOSRID
Magic number for a geographic coord sys in POSTGIS SRID.
Definition: qgis.h:416
static const QString QGIS_RELEASE_NAME
Release name.
Definition: qgis.h:67
bool qgsDoubleNearSig(double a, double b, int significantDigits=10)
Compare two doubles using specified number of significant digits.
Definition: qgis.h:246
const double DEFAULT_LINE_WIDTH
Definition: qgis.h:438
CORE_EXPORT const QString PROJECT_SCALES
Definition: qgis.cpp:65
CORE_EXPORT uint qHash(const QVariant &variant)
Hash for QVariant.
Definition: qgis.cpp:232
static const double DEFAULT_HIGHLIGHT_MIN_WIDTH_MM
Default highlight line/stroke minimum width in mm.
Definition: qgis.h:118
static const double DEFAULT_HIGHLIGHT_BUFFER_MM
Default highlight buffer in mm.
Definition: qgis.h:113
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:100
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:210
void CORE_EXPORT * qgsMalloc(size_t size)
Allocates size bytes and returns a pointer to the allocated memory.
Definition: qgis.cpp:107
Object * operator->()
Returns pointer to blocked QObject.
Definition: qgis.h:177
const long GEO_EPSG_CRS_ID
Magic number for a geographic coord sys in EpsgCrsId ID format.
Definition: qgis.h:420
static const double SCALE_PRECISION
Fudge factor used to compare two scales.
Definition: qgis.h:125
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