QGIS API Documentation
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 <stdlib.h>
27 #include <cfloat>
28 #include <cmath>
29 #include <qnumeric.h>
30 
31 #include <qgswkbtypes.h>
32 
36 class CORE_EXPORT QGis
37 {
38  public:
39  // Version constants
40  //
41  // Version string
42  static const char* QGIS_VERSION;
43  // Version number used for comparing versions using the "Check QGIS Version" function
44  static const int QGIS_VERSION_INT;
45  // Release name
46  static const char* QGIS_RELEASE_NAME;
47  // The development version
48  static const char* QGIS_DEV_VERSION;
49 
50  // Enumerations
51  //
52 
54  // Feature types
55  // @deprecated use QgsWKBTypes::Type
56  /* Q_DECL_DEPRECATED */
57  enum WkbType
58  {
59  WKBUnknown = 0,
60  WKBPoint = 1,
66  WKBNoGeometry = 100, //attributes only
67  WKBPoint25D = 0x80000001,
73  };
74 
76  // @deprecated use QgsWKBTypes::singleType
77  /* Q_DECL_DEPRECATED */
78  static WkbType singleType( WkbType type );
79 
81  // @deprecated use QgsWKBTypes::multiType
82  /* Q_DECL_DEPRECATED */
83  static WkbType multiType( WkbType type );
84 
86  // @deprecated use QgsWKBTypes::flatType
87  /* Q_DECL_DEPRECATED */
88  static WkbType flatType( WkbType type );
89 
91  // @deprecated use QgsWKBTypes::isSingleType
92  /* Q_DECL_DEPRECATED */
93  static bool isSingleType( WkbType type );
94 
96  // @deprecated use QgsWKBTypes::isMultiType
97  /* Q_DECL_DEPRECATED */
98  static bool isMultiType( WkbType type );
99 
100  // get dimension of points
101  // @deprecated use QgsWKBTypes::coordDimensions()
102  /* Q_DECL_DEPRECATED */
103  static int wkbDimensions( WkbType type );
104 
106  static QgsWKBTypes::Type fromOldWkbType( QGis::WkbType type );
107 
109  static QGis::WkbType fromNewWkbType( QgsWKBTypes::Type type );
110 
112  {
117  NoGeometry
118  };
119 
121  static const char *vectorGeometryType( GeometryType type );
122 
124  static const char *featureType( WkbType type );
125 
129  enum DataType
130  { UnknownDataType = 0, Byte = 1, UInt16 = 2, Int16 = 3, UInt32 = 4, Int32 = 5, Float32 = 6, Float64 = 7, CInt16 = 8, CInt32 = 9, CFloat32 = 10, CFloat64 = 11, ARGB32 = 12, ARGB32_Premultiplied = 13
147  };
148 
149 
154  //TODO QGIS 3.0 - clean up and move to QgsUnitTypes and rename to DistanceUnit
155  enum UnitType
156  {
157  Meters = 0,
158  Feet = 1,
159  Degrees = 2, //for 1.0 api backwards compatibility
160  NauticalMiles = 7,
161  Kilometers = 8,
162  Yards = 9,
163  Miles = 10,
165  UnknownUnit = 3,
167  // for [1.4;1.8] api compatibility
168  DecimalDegrees = 2, // was 2
169  DegreesMinutesSeconds = 2, // was 4
170  DegreesDecimalMinutes = 2, // was 5
171  };
172 
175  Q_DECL_DEPRECATED static QString toLiteral( QGis::UnitType unit );
176 
179  Q_DECL_DEPRECATED static UnitType fromLiteral( const QString& literal, QGis::UnitType defaultType = UnknownUnit );
180 
183  Q_DECL_DEPRECATED static QString tr( QGis::UnitType unit );
184 
187  Q_DECL_DEPRECATED static UnitType fromTr( const QString& literal, QGis::UnitType defaultType = UnknownUnit );
188 
191  Q_DECL_DEPRECATED static double fromUnitToUnitFactor( QGis::UnitType fromUnit, QGis::UnitType toUnit );
192 
201  static double permissiveToDouble( QString string, bool& ok );
202 
211  static int permissiveToInt( QString string, bool& ok );
212 
215  {
216  // These first two are useful for threads to alert their parent data providers
217 
219  ProviderExtentCalcEvent = ( QEvent::User + 1 ),
220 
222  ProviderCountCalcEvent
223  };
224 
227  Q_DECL_DEPRECATED static const double DEFAULT_IDENTIFY_RADIUS;
228 
231  static const double DEFAULT_SEARCH_RADIUS_MM;
232 
234  static const float DEFAULT_MAPTOPIXEL_THRESHOLD;
235 
240 
244 
248 
253  static double SCALE_PRECISION;
254 
255  private:
256  // String representation of unit types (set in qgis.cpp)
257  static const char *qgisUnitTypes[];
258 
259 };
260 
261 // hack to workaround warnings when casting void pointers
262 // retrieved from QLibrary::resolve to function pointers.
263 // It's assumed that this works on all systems supporting
264 // QLibrary
265 #if QT_VERSION >= 0x050000
266 #define cast_to_fptr(f) f
267 #else
268 inline void ( *cast_to_fptr( void *p ) )()
269 {
270  union
271  {
272  void *p;
273  void ( *f )();
274  } u;
275 
276  u.p = p;
277  return u.f;
278 }
279 #endif
280 
287 // based on Boojum's code from http://stackoverflow.com/questions/3556687/prevent-firing-signals-in-qt
288 template<class Object> class QgsSignalBlocker
289 {
290  public:
291 
295  QgsSignalBlocker( Object* object )
296  : mObject( object )
297  , mPreviousState( object->blockSignals( true ) )
298  {}
299 
301  {
302  mObject->blockSignals( mPreviousState );
303  }
304 
306  Object* operator->() { return mObject; }
307 
308  private:
309 
310  Object* mObject;
311  bool mPreviousState;
312 
313 };
314 
327 // based on Boojum's code from http://stackoverflow.com/questions/3556687/prevent-firing-signals-in-qt
328 template<class Object> inline QgsSignalBlocker<Object> whileBlocking( Object* object )
329 {
330  return QgsSignalBlocker<Object>( object );
331 }
332 
336 inline QString qgsDoubleToString( double a, int precision = 17 )
337 {
338  if ( precision )
339  return QString::number( a, 'f', precision ).remove( QRegExp( "\\.?0+$" ) );
340  else
341  return QString::number( a, 'f', precision );
342 }
343 
348 inline bool qgsDoubleNear( double a, double b, double epsilon = 4 * DBL_EPSILON )
349 {
350  const double diff = a - b;
351  return diff > -epsilon && diff <= epsilon;
352 }
353 
355 inline bool qgsDoubleNearSig( double a, double b, int significantDigits = 10 )
356 {
357  // The most simple would be to print numbers as %.xe and compare as strings
358  // but that is probably too costly
359  // Then the fastest would be to set some bits directly, but little/big endian
360  // has to be considered (maybe TODO)
361  // Is there a better way?
362  int aexp, bexp;
363  double ar = frexp( a, &aexp );
364  double br = frexp( b, &bexp );
365 
366  return aexp == bexp &&
367  qRound( ar * pow( 10.0, significantDigits ) ) == qRound( br * pow( 10.0, significantDigits ) );
368 }
369 
371 inline double qgsRound( double x )
372 {
373  return x < 0.0 ? std::ceil( x - 0.5 ) : std::floor( x + 0.5 );
374 }
375 
380 CORE_EXPORT bool qgsVariantLessThan( const QVariant& lhs, const QVariant& rhs );
381 
386 CORE_EXPORT bool qgsVariantGreaterThan( const QVariant& lhs, const QVariant& rhs );
387 
388 CORE_EXPORT QString qgsVsiPrefix( const QString& path );
389 
394 void CORE_EXPORT *qgsMalloc( size_t size );
395 
402 void CORE_EXPORT *qgsCalloc( size_t nmemb, size_t size );
403 
407 void CORE_EXPORT qgsFree( void *ptr );
408 
412 extern CORE_EXPORT const QString GEOWKT;
413 extern CORE_EXPORT const QString PROJECT_SCALES;
414 
416 extern CORE_EXPORT const QString GEOPROJ4;
418 const long GEOSRID = 4326;
420 const long GEOCRS_ID = 3452;
422 const long GEO_EPSG_CRS_ID = 4326;
424 extern CORE_EXPORT const QString GEO_EPSG_CRS_AUTHID;
426 const int PROJ_PREFIX_LEN = 6;
428 const int ELLPS_PREFIX_LEN = 7;
430 const int LAT_PREFIX_LEN = 7;
433 const int USER_CRS_START_ID = 100000;
434 
436 extern CORE_EXPORT const QString GEO_NONE;
437 
438 //
439 // Constants for point symbols
440 //
441 
443 const double MINIMUM_POINT_SIZE = 0.1;
445 const double DEFAULT_POINT_SIZE = 2.0;
446 const double DEFAULT_LINE_WIDTH = 0.26;
447 
449 const double DEFAULT_SEGMENT_EPSILON = 1e-8;
450 
452 
459 typedef unsigned long long qgssize;
460 
461 #if (__GNUC__ > 4 || (__GNUC__ == 4 && __GNUC_MINOR__ >= 6)) || defined(__clang__)
462 #define Q_NOWARN_DEPRECATED_PUSH \
463  _Pragma("GCC diagnostic push") \
464  _Pragma("GCC diagnostic ignored \"-Wdeprecated-declarations\"");
465 #define Q_NOWARN_DEPRECATED_POP \
466  _Pragma("GCC diagnostic pop");
467 #elif defined(_MSC_VER)
468 #define Q_NOWARN_DEPRECATED_PUSH \
469  __pragma(warning(push)) \
470  __pragma(warning(disable:4996))
471 #define Q_NOWARN_DEPRECATED_POP \
472  __pragma(warning(pop))
473 #else
474 #define Q_NOWARN_DEPRECATED_PUSH
475 #define Q_NOWARN_DEPRECATED_POP
476 #endif
477 
478 #ifndef QGISEXTERN
479 #ifdef Q_OS_WIN
480 # define QGISEXTERN extern "C" __declspec( dllexport )
481 # ifdef _MSC_VER
482 // do not warn about C bindings returing QString
483 # pragma warning(disable:4190)
484 # endif
485 #else
486 # if defined(__GNUC__) || defined(__clang__)
487 # define QGISEXTERN extern "C" __attribute__ ((visibility ("default")))
488 # else
489 # define QGISEXTERN extern "C"
490 # endif
491 #endif
492 #endif
493 #endif
494 
495 #if defined(__clang__)
496 #define FALLTHROUGH [[clang::fallthrough]]
497 #else
498 #define FALLTHROUGH
499 #endif
static const char * QGIS_VERSION
Definition: qgis.h:42
CORE_EXPORT QString qgsVsiPrefix(const QString &path)
Definition: qgis.cpp:336
static double DEFAULT_HIGHLIGHT_BUFFER_MM
Default highlight buffer in mm.
Definition: qgis.h:243
static const QColor DEFAULT_HIGHLIGHT_COLOR
Default highlight color.
Definition: qgis.h:239
GeometryType
Definition: qgis.h:111
WkbType
Used for symbology operations.
Definition: qgis.h:57
static Q_DECL_DEPRECATED const double DEFAULT_IDENTIFY_RADIUS
Old search radius in % of canvas width.
Definition: qgis.h:227
The QGis class provides global constants for use throughout the application.
Definition: qgis.h:36
QString & remove(int position, int n)
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:243
QMap< QString, QString > QgsStringMap
Definition: qgis.h:451
~QgsSignalBlocker()
Definition: qgis.h:300
bool qgsDoubleNear(double a, double b, double epsilon=4 *DBL_EPSILON)
Compare two doubles (but allow some difference)
Definition: qgis.h:348
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:263
double qgsRound(double x)
A round function which returns a double to guard against overflows.
Definition: qgis.h:371
QgsSignalBlocker(Object *object)
Constructor for QgsSignalBlocker.
Definition: qgis.h:295
QString number(int n, int base)
CORE_EXPORT const QString GEO_NONE
Constant that holds the string representation for "No ellips/No CRS".
Definition: qgis.cpp:76
const double DEFAULT_SEGMENT_EPSILON
Default snapping tolerance for segments.
Definition: qgis.h:449
static const char * QGIS_DEV_VERSION
Definition: qgis.h:48
QString qgsDoubleToString(double a, int precision=17)
Returns a string representation of a double.
Definition: qgis.h:336
const int ELLPS_PREFIX_LEN
The length of the string "+ellps=".
Definition: qgis.h:428
static const float DEFAULT_MAPTOPIXEL_THRESHOLD
Default threshold between map coordinates and device coordinates for map2pixel simplification.
Definition: qgis.h:234
const long GEOCRS_ID
Magic number for a geographic coord sys in QGIS srs.db tbl_srs.srs_id.
Definition: qgis.h:420
CORE_EXPORT const QString GEOPROJ4
PROJ4 string that represents a geographic coord sys.
Definition: qgis.cpp:54
RAII signal blocking class.
Definition: qgis.h:288
void CORE_EXPORT qgsFree(void *ptr)
Frees the memory space pointed to by ptr.
Definition: qgis.cpp:258
UserEvent
User defined event types.
Definition: qgis.h:214
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:459
static const double DEFAULT_SEARCH_RADIUS_MM
Identify search radius in mm.
Definition: qgis.h:231
static const char * QGIS_RELEASE_NAME
Definition: qgis.h:46
const double DEFAULT_POINT_SIZE
Magic number that determines the default point size for point symbols.
Definition: qgis.h:445
const int USER_CRS_START_ID
Magick number that determines whether a projection crsid is a system (srs.db) or user (~/...
Definition: qgis.h:433
QgsSignalBlocker< Object > whileBlocking(Object *object)
Temporarily blocks signals from a QObject while calling a single method from the object.
Definition: qgis.h:328
const long GEOSRID
Magic number for a geographic coord sys in POSTGIS SRID.
Definition: qgis.h:418
const double MINIMUM_POINT_SIZE
Magic number that determines the minimum allowable point size for point symbols.
Definition: qgis.h:443
bool qgsDoubleNearSig(double a, double b, int significantDigits=10)
Compare two doubles using specified number of significant digits.
Definition: qgis.h:355
const double DEFAULT_LINE_WIDTH
Definition: qgis.h:446
CORE_EXPORT const QString PROJECT_SCALES
Definition: qgis.cpp:70
DataType
Raster data types.
Definition: qgis.h:129
const int LAT_PREFIX_LEN
The length of the string "+lat_1=".
Definition: qgis.h:430
UnitType
Map units that qgis supports.
Definition: qgis.h:155
void(*)() cast_to_fptr(void *p)
Definition: qgis.h:268
const int PROJ_PREFIX_LEN
The length of the string "+proj=".
Definition: qgis.h:426
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:331
static double SCALE_PRECISION
Fudge factor used to compare two scales.
Definition: qgis.h:253
static const int QGIS_VERSION_INT
Definition: qgis.h:44
void CORE_EXPORT * qgsMalloc(size_t size)
Allocates size bytes and returns a pointer to the allocated memory.
Definition: qgis.cpp:228
static double DEFAULT_HIGHLIGHT_MIN_WIDTH_MM
Default highlight line/outline minimum width in mm.
Definition: qgis.h:247
Object * operator->()
Returns pointer to blocked QObject.
Definition: qgis.h:306
const long GEO_EPSG_CRS_ID
Magic number for a geographic coord sys in EpsgCrsId ID format.
Definition: qgis.h:422
CORE_EXPORT const QString GEO_EPSG_CRS_AUTHID
Geographic coord sys from EPSG authority.
Definition: qgis.cpp:74
CORE_EXPORT const QString GEOWKT
Wkt string that represents a geographic coord sys.
Definition: qgis.cpp:57
#define tr(sourceText)