QGIS API Documentation  2.99.0-Master (cb63e82)
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 <QRegExp>
24 #include <QMetaType>
25 #include <QVariant>
26 #include <QDateTime>
27 #include <QDate>
28 #include <QTime>
29 #include <QHash>
30 #include <stdlib.h>
31 #include <cfloat>
32 #include <cmath>
33 #include <qnumeric.h>
34 
35 #include "qgswkbtypes.h"
36 #include "qgis_core.h"
37 
41 class CORE_EXPORT Qgis
42 {
43  public:
44  // Version constants
45  //
47  static const QString QGIS_VERSION;
49  static const int QGIS_VERSION_INT;
51  static const QString QGIS_RELEASE_NAME;
53  static const char *QGIS_DEV_VERSION;
54 
55  // Enumerations
56  //
57 
61  enum DataType
62  {
63  UnknownDataType = 0,
64  Byte = 1,
65  UInt16 = 2,
66  Int16 = 3,
67  UInt32 = 4,
68  Int32 = 5,
69  Float32 = 6,
70  Float64 = 7,
71  CInt16 = 8,
72  CInt32 = 9,
73  CFloat32 = 10,
74  CFloat64 = 11,
75  ARGB32 = 12,
76  ARGB32_Premultiplied = 13
77  };
78 
80  enum UserEvent
81  {
82  // These first two are useful for threads to alert their parent data providers
83 
85  ProviderExtentCalcEvent = ( QEvent::User + 1 ),
86 
88  ProviderCountCalcEvent
89  };
90 
93  static const double DEFAULT_SEARCH_RADIUS_MM;
94 
96  static const float DEFAULT_MAPTOPIXEL_THRESHOLD;
97 
101  static const QColor DEFAULT_HIGHLIGHT_COLOR;
102 
105  static const double DEFAULT_HIGHLIGHT_BUFFER_MM;
106 
109  static const double DEFAULT_HIGHLIGHT_MIN_WIDTH_MM;
110 
115  static const double SCALE_PRECISION;
116 
120  static const double DEFAULT_Z_COORDINATE;
121 
122 };
123 
124 // hack to workaround warnings when casting void pointers
125 // retrieved from QLibrary::resolve to function pointers.
126 // It's assumed that this works on all systems supporting
127 // QLibrary
128 #define cast_to_fptr(f) f
129 
137 // based on Boojum's code from http://stackoverflow.com/questions/3556687/prevent-firing-signals-in-qt
138 template<class Object> class QgsSignalBlocker // clazy:exclude=rule-of-three
139 {
140  public:
141 
145  explicit QgsSignalBlocker( Object *object )
146  : mObject( object )
147  , mPreviousState( object->blockSignals( true ) )
148  {}
149 
151  {
152  mObject->blockSignals( mPreviousState );
153  }
154 
156  Object *operator->() { return mObject; }
157 
158  private:
159 
160  Object *mObject = nullptr;
161  bool mPreviousState;
162 
163 };
164 
177 // based on Boojum's code from http://stackoverflow.com/questions/3556687/prevent-firing-signals-in-qt
178 template<class Object> inline QgsSignalBlocker<Object> whileBlocking( Object *object )
179 {
180  return QgsSignalBlocker<Object>( object );
181 }
182 
184 uint qHash( const QVariant &variant );
185 
189 inline QString qgsDoubleToString( double a, int precision = 17 )
190 {
191  if ( precision )
192  return QString::number( a, 'f', precision ).remove( QRegExp( "\\.?0+$" ) );
193  else
194  return QString::number( a, 'f', precision );
195 }
196 
201 inline bool qgsDoubleNear( double a, double b, double epsilon = 4 * DBL_EPSILON )
202 {
203  const double diff = a - b;
204  return diff > -epsilon && diff <= epsilon;
205 }
206 
211 inline bool qgsFloatNear( float a, float b, float epsilon = 4 * FLT_EPSILON )
212 {
213  const float diff = a - b;
214  return diff > -epsilon && diff <= epsilon;
215 }
216 
218 inline bool qgsDoubleNearSig( double a, double b, int significantDigits = 10 )
219 {
220  // The most simple would be to print numbers as %.xe and compare as strings
221  // but that is probably too costly
222  // Then the fastest would be to set some bits directly, but little/big endian
223  // has to be considered (maybe TODO)
224  // Is there a better way?
225  int aexp, bexp;
226  double ar = frexp( a, &aexp );
227  double br = frexp( b, &bexp );
228 
229  return aexp == bexp &&
230  qRound( ar * pow( 10.0, significantDigits ) ) == qRound( br * pow( 10.0, significantDigits ) );
231 }
232 
234 inline double qgsRound( double x )
235 {
236  return x < 0.0 ? std::ceil( x - 0.5 ) : std::floor( x + 0.5 );
237 }
238 
244 inline double qgsRound( double number, double places )
245 {
246  int scaleFactor = pow( 10, places );
247  return static_cast<double>( static_cast<qlonglong>( number * scaleFactor + 0.5 ) ) / scaleFactor;
248 }
249 
258 CORE_EXPORT double qgsPermissiveToDouble( QString string, bool &ok );
259 
268 CORE_EXPORT int qgsPermissiveToInt( QString string, bool &ok );
269 
274 CORE_EXPORT bool qgsVariantLessThan( const QVariant &lhs, const QVariant &rhs );
275 
280 CORE_EXPORT bool qgsVariantGreaterThan( const QVariant &lhs, const QVariant &rhs );
281 
282 CORE_EXPORT QString qgsVsiPrefix( const QString &path );
283 
288 void CORE_EXPORT *qgsMalloc( size_t size );
289 
296 void CORE_EXPORT *qgsCalloc( size_t nmemb, size_t size );
297 
301 void CORE_EXPORT qgsFree( void *ptr );
302 
306 extern CORE_EXPORT const QString GEOWKT;
307 extern CORE_EXPORT const QString PROJECT_SCALES;
308 
310 extern CORE_EXPORT const QString GEOPROJ4;
312 const long GEOSRID = 4326;
314 const long GEOCRS_ID = 3452;
316 const long GEO_EPSG_CRS_ID = 4326;
318 extern CORE_EXPORT const QString GEO_EPSG_CRS_AUTHID;
320 const int PROJ_PREFIX_LEN = 6;
322 const int ELLPS_PREFIX_LEN = 7;
324 const int LAT_PREFIX_LEN = 7;
325 
328 const int USER_CRS_START_ID = 100000;
329 
331 extern CORE_EXPORT const QString GEO_NONE;
332 
333 //
334 // Constants for point symbols
335 //
336 
338 const double DEFAULT_POINT_SIZE = 2.0;
339 const double DEFAULT_LINE_WIDTH = 0.26;
340 
342 const double DEFAULT_SEGMENT_EPSILON = 1e-8;
343 
344 typedef QMap<QString, QString> QgsStringMap;
345 
352 typedef unsigned long long qgssize;
353 
354 #if (__GNUC__ > 4 || (__GNUC__ == 4 && __GNUC_MINOR__ >= 6)) || defined(__clang__)
355 #define Q_NOWARN_DEPRECATED_PUSH \
356  _Pragma("GCC diagnostic push") \
357  _Pragma("GCC diagnostic ignored \"-Wdeprecated-declarations\"");
358 #define Q_NOWARN_DEPRECATED_POP \
359  _Pragma("GCC diagnostic pop");
360 #elif defined(_MSC_VER)
361 #define Q_NOWARN_DEPRECATED_PUSH \
362  __pragma(warning(push)) \
363  __pragma(warning(disable:4996))
364 #define Q_NOWARN_DEPRECATED_POP \
365  __pragma(warning(pop))
366 #else
367 #define Q_NOWARN_DEPRECATED_PUSH
368 #define Q_NOWARN_DEPRECATED_POP
369 #endif
370 
371 #ifndef QGISEXTERN
372 #ifdef Q_OS_WIN
373 # define QGISEXTERN extern "C" __declspec( dllexport )
374 # ifdef _MSC_VER
375 // do not warn about C bindings returning QString
376 # pragma warning(disable:4190)
377 # endif
378 #else
379 # if defined(__GNUC__) || defined(__clang__)
380 # define QGISEXTERN extern "C" __attribute__ ((visibility ("default")))
381 # else
382 # define QGISEXTERN extern "C"
383 # endif
384 #endif
385 #endif
386 #endif
387 
388 #if defined(__clang__)
389 #define FALLTHROUGH //[[clang::fallthrough]]
390 #else
391 #define FALLTHROUGH
392 #endif
393 
394 /*
395  * http://pyqt.sourceforge.net/Docs/sip4/annotations.html?highlight=keepreference#function-annotation-Transfer
396  *
397  * Example QgsVectorLayer::setDiagramRenderer
398  */
399 #define SIP_TRANSFER
400 
401 /*
402  * http://pyqt.sourceforge.net/Docs/sip4/annotations.html?highlight=keepreference#function-annotation-TransferBack
403  */
404 #define SIP_TRANSFERBACK
405 
406 /*
407  * http://pyqt.sourceforge.net/Docs/sip4/annotations.html?highlight=keepreference#function-annotation-TransferThis
408  */
409 #define SIP_TRANSFERTHIS
410 
411 /*
412  * http://pyqt.sourceforge.net/Docs/sip4/annotations.html?highlight=keepreference#argument-annotation-Out
413  */
414 #define SIP_OUT
415 
416 /*
417  * http://pyqt.sourceforge.net/Docs/sip4/annotations.html?highlight=keepreference#argument-annotation-In
418  */
419 #define SIP_IN
420 
421 /*
422  * Combination of
423  * http://pyqt.sourceforge.net/Docs/sip4/annotations.html?highlight=keepreference#argument-annotation-In
424  * and
425  * http://pyqt.sourceforge.net/Docs/sip4/annotations.html?highlight=keepreference#argument-annotation-Out
426  */
427 #define SIP_INOUT
428 
429 /*
430  * http://pyqt.sourceforge.net/Docs/sip4/annotations.html?highlight=keepreference#function-annotation-Factory
431  */
432 #define SIP_FACTORY
433 
434 /*
435  * http://pyqt.sourceforge.net/Docs/sip4/annotations.html?highlight=keepreference#function-annotation-PyName
436  */
437 #define SIP_PYNAME(name)
438 
439 /*
440  * http://pyqt.sourceforge.net/Docs/sip4/annotations.html?highlight=keepreference#argument-annotation-KeepReference
441  */
442 #define SIP_KEEPREFERENCE
443 
444 /*
445  * http://pyqt.sourceforge.net/Docs/sip4/annotations.html#argument-annotation-Array
446  */
447 #define SIP_ARRAY
448 
449 /*
450  * http://pyqt.sourceforge.net/Docs/sip4/annotations.html#argument-annotation-ArraySize
451  */
452 #define SIP_ARRAYSIZE
453 
454 /*
455  * discard line
456  */
457 #define SIP_SKIP
458 
459 /*
460  * force a private line to be written
461  */
462 #define SIP_FORCE
463 
464 /*
465  * specify an alternative type for SIP argument
466  */
467 #define SIP_PYARGTYPE(type)
468 
469 /*
470  * specify an alternative default value for SIP argument
471  */
472 #define SIP_PYARGDEFAULT(value)
473 
474 /*
475  * remove argument in SIP method
476  */
477 #define SIP_PYARGREMOVE
478 
479 
480 /*
481  * http://pyqt.sourceforge.net/Docs/sip4/annotations.html?highlight=keepreference#function-annotation-ReleaseGIL
482  */
483 #define SIP_RELEASEGIL
484 
485 /*
486  * Will insert a `%Feature feature` directive in sip files
487  */
488 #define SIP_FEATURE(feature)
489 
490 /*
491  * Will insert a `%If feature` directive in sip files
492  */
493 #define SIP_IF_FEATURE(feature)
494 
495 /*
496  * Convert to subclass code
497  */
498 #define SIP_CONVERT_TO_SUBCLASS_CODE(code)
499 
500 /*
501  * Will insert a `%End` directive in sip files
502  */
503 #define SIP_END
504 
505 /*
506  * Class level annotation for abstract classes
507  */
508 #define SIP_ABSTRACT
CORE_EXPORT QString qgsVsiPrefix(const QString &path)
Definition: qgis.cpp:209
static const QString QGIS_VERSION
Version string.
Definition: qgis.h:47
static const char * QGIS_DEV_VERSION
The development version.
Definition: qgis.h:53
bool qgsFloatNear(float a, float b, float epsilon=4 *FLT_EPSILON)
Compare two floats (but allow some difference)
Definition: qgis.h:211
DataType
Raster data types.
Definition: qgis.h:61
static const QColor DEFAULT_HIGHLIGHT_COLOR
Default highlight color.
Definition: qgis.h:101
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:116
static const int QGIS_VERSION_INT
Version number used for comparing versions using the "Check QGIS Version" function.
Definition: qgis.h:49
QMap< QString, QString > QgsStringMap
Definition: qgis.h:344
~QgsSignalBlocker()
Definition: qgis.h:150
bool qgsDoubleNear(double a, double b, double epsilon=4 *DBL_EPSILON)
Compare two doubles (but allow some difference)
Definition: qgis.h:201
The Qgis class provides global constants for use throughout the application.
Definition: qgis.h:41
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:136
UserEvent
User defined event types.
Definition: qgis.h:80
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:120
double qgsRound(double x)
A round function which returns a double to guard against overflows.
Definition: qgis.h:234
QgsSignalBlocker(Object *object)
Constructor for QgsSignalBlocker.
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:342
QString qgsDoubleToString(double a, int precision=17)
Returns a string representation of a double.
Definition: qgis.h:189
const int ELLPS_PREFIX_LEN
The length of the string "+ellps=".
Definition: qgis.h:322
uint qHash(const QVariant &variant)
Hash for QVariant.
Definition: qgis.cpp:226
const long GEOCRS_ID
Magic number for a geographic coord sys in QGIS srs.db tbl_srs.srs_id.
Definition: qgis.h:314
static const double DEFAULT_SEARCH_RADIUS_MM
Identify search radius in mm.
Definition: qgis.h:93
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:87
CORE_EXPORT const QString GEOPROJ4
PROJ4 string that represents a geographic coord sys.
Definition: qgis.cpp:50
RAII signal blocking class.
Definition: qgis.h:138
void CORE_EXPORT qgsFree(void *ptr)
Frees the memory space pointed to by ptr.
Definition: qgis.cpp:131
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:352
const double DEFAULT_POINT_SIZE
Magic number that determines the default point size for point symbols.
Definition: qgis.h:338
static const float DEFAULT_MAPTOPIXEL_THRESHOLD
Default threshold between map coordinates and device coordinates for map2pixel simplification.
Definition: qgis.h:96
const int USER_CRS_START_ID
Magick number that determines whether a projection crsid is a system (srs.db) or user (~/...
Definition: qgis.h:328
QgsSignalBlocker< Object > whileBlocking(Object *object)
Temporarily blocks signals from a QObject while calling a single method from the object.
Definition: qgis.h:178
const long GEOSRID
Magic number for a geographic coord sys in POSTGIS SRID.
Definition: qgis.h:312
static const QString QGIS_RELEASE_NAME
Release name.
Definition: qgis.h:51
bool qgsDoubleNearSig(double a, double b, int significantDigits=10)
Compare two doubles using specified number of significant digits.
Definition: qgis.h:218
const double DEFAULT_LINE_WIDTH
Definition: qgis.h:339
CORE_EXPORT const QString PROJECT_SCALES
Definition: qgis.cpp:65
const int LAT_PREFIX_LEN
The length of the string "+lat_1=".
Definition: qgis.h:324
static const double DEFAULT_HIGHLIGHT_MIN_WIDTH_MM
Default highlight line/stroke minimum width in mm.
Definition: qgis.h:109
const int PROJ_PREFIX_LEN
The length of the string "+proj=".
Definition: qgis.h:320
static const double DEFAULT_HIGHLIGHT_BUFFER_MM
Default highlight buffer in mm.
Definition: qgis.h:105
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:94
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:204
void CORE_EXPORT * qgsMalloc(size_t size)
Allocates size bytes and returns a pointer to the allocated memory.
Definition: qgis.cpp:101
Object * operator->()
Returns pointer to blocked QObject.
Definition: qgis.h:156
const long GEO_EPSG_CRS_ID
Magic number for a geographic coord sys in EpsgCrsId ID format.
Definition: qgis.h:316
static const double SCALE_PRECISION
Fudge factor used to compare two scales.
Definition: qgis.h:115
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