QGIS API Documentation  2.17.0-Master (0497e4a)
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 
40 class CORE_EXPORT QGis
41 {
42  public:
43  // Version constants
44  //
45  // Version string
47  // Version number used for comparing versions using the "Check QGIS Version" function
48  static const int QGIS_VERSION_INT;
49  // Release name
51  // The development version
52  static const char* QGIS_DEV_VERSION;
53 
54  // Enumerations
55  //
56 
58  // Feature types
59  // @deprecated use QgsWKBTypes::Type
60  /* Q_DECL_DEPRECATED */
61  enum WkbType
62  {
63  WKBUnknown = 0,
64  WKBPoint = 1,
70  WKBNoGeometry = 100, //attributes only
71  WKBPoint25D = 0x80000001,
77  };
78 
80  // @deprecated use QgsWKBTypes::singleType
81  /* Q_DECL_DEPRECATED */
82  static WkbType singleType( WkbType type );
83 
85  // @deprecated use QgsWKBTypes::multiType
86  /* Q_DECL_DEPRECATED */
87  static WkbType multiType( WkbType type );
88 
90  // @deprecated use QgsWKBTypes::flatType
91  /* Q_DECL_DEPRECATED */
92  static WkbType flatType( WkbType type );
93 
95  // @deprecated use QgsWKBTypes::isSingleType
96  /* Q_DECL_DEPRECATED */
97  static bool isSingleType( WkbType type );
98 
100  // @deprecated use QgsWKBTypes::isMultiType
101  /* Q_DECL_DEPRECATED */
102  static bool isMultiType( WkbType type );
103 
104  // get dimension of points
105  // @deprecated use QgsWKBTypes::coordDimensions()
106  /* Q_DECL_DEPRECATED */
107  static int wkbDimensions( WkbType type );
108 
110  static QgsWKBTypes::Type fromOldWkbType( QGis::WkbType type );
111 
113  static QGis::WkbType fromNewWkbType( QgsWKBTypes::Type type );
114 
116  {
121  NoGeometry
122  };
123 
125  static const char *vectorGeometryType( GeometryType type );
126 
128  static const char *featureType( WkbType type );
129 
133  enum DataType
134  { 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
151  };
152 
153 
158  //TODO QGIS 3.0 - clean up and move to QgsUnitTypes and rename to DistanceUnit
159  enum UnitType
160  {
161  Meters = 0,
162  Feet = 1,
163  Degrees = 2, //for 1.0 api backwards compatibility
164  NauticalMiles = 7,
165  Kilometers = 8,
166  Yards = 9,
167  Miles = 10,
169  UnknownUnit = 3,
171  // for [1.4;1.8] api compatibility
172  DecimalDegrees = 2, // was 2
173  DegreesMinutesSeconds = 2, // was 4
174  DegreesDecimalMinutes = 2, // was 5
175  };
176 
179  Q_DECL_DEPRECATED static QString toLiteral( QGis::UnitType unit );
180 
183  Q_DECL_DEPRECATED static UnitType fromLiteral( const QString& literal, QGis::UnitType defaultType = UnknownUnit );
184 
187  Q_DECL_DEPRECATED static QString tr( QGis::UnitType unit );
188 
191  Q_DECL_DEPRECATED static UnitType fromTr( const QString& literal, QGis::UnitType defaultType = UnknownUnit );
192 
195  Q_DECL_DEPRECATED static double fromUnitToUnitFactor( QGis::UnitType fromUnit, QGis::UnitType toUnit );
196 
205  static double permissiveToDouble( QString string, bool& ok );
206 
215  static int permissiveToInt( QString string, bool& ok );
216 
219  {
220  // These first two are useful for threads to alert their parent data providers
221 
223  ProviderExtentCalcEvent = ( QEvent::User + 1 ),
224 
226  ProviderCountCalcEvent
227  };
228 
231  Q_DECL_DEPRECATED static const double DEFAULT_IDENTIFY_RADIUS;
232 
235  static const double DEFAULT_SEARCH_RADIUS_MM;
236 
238  static const float DEFAULT_MAPTOPIXEL_THRESHOLD;
239 
244 
248 
252 
257  static double SCALE_PRECISION;
258 
259  private:
260  // String representation of unit types (set in qgis.cpp)
261  static const char *qgisUnitTypes[];
262 
263 };
264 
265 // hack to workaround warnings when casting void pointers
266 // retrieved from QLibrary::resolve to function pointers.
267 // It's assumed that this works on all systems supporting
268 // QLibrary
269 #if QT_VERSION >= 0x050000
270 #define cast_to_fptr(f) f
271 #else
272 inline void ( *cast_to_fptr( void *p ) )()
273 {
274  union
275  {
276  void *p;
277  void ( *f )();
278  } u;
279 
280  u.p = p;
281  return u.f;
282 }
283 #endif
284 
292 // based on Boojum's code from http://stackoverflow.com/questions/3556687/prevent-firing-signals-in-qt
293 template<class Object> class QgsSignalBlocker
294 {
295  public:
296 
300  explicit QgsSignalBlocker( Object* object )
301  : mObject( object )
302  , mPreviousState( object->blockSignals( true ) )
303  {}
304 
306  {
307  mObject->blockSignals( mPreviousState );
308  }
309 
311  Object* operator->() { return mObject; }
312 
313  private:
314 
315  Object* mObject;
316  bool mPreviousState;
317 
318 };
319 
332 // based on Boojum's code from http://stackoverflow.com/questions/3556687/prevent-firing-signals-in-qt
333 template<class Object> inline QgsSignalBlocker<Object> whileBlocking( Object* object )
334 {
335  return QgsSignalBlocker<Object>( object );
336 }
337 
341 inline QString qgsDoubleToString( double a, int precision = 17 )
342 {
343  if ( precision )
344  return QString::number( a, 'f', precision ).remove( QRegExp( "\\.?0+$" ) );
345  else
346  return QString::number( a, 'f', precision );
347 }
348 
353 inline bool qgsDoubleNear( double a, double b, double epsilon = 4 * DBL_EPSILON )
354 {
355  const double diff = a - b;
356  return diff > -epsilon && diff <= epsilon;
357 }
358 
363 inline bool qgsFloatNear( float a, float b, float epsilon = 4 * FLT_EPSILON )
364 {
365  const float diff = a - b;
366  return diff > -epsilon && diff <= epsilon;
367 }
368 
370 inline bool qgsDoubleNearSig( double a, double b, int significantDigits = 10 )
371 {
372  // The most simple would be to print numbers as %.xe and compare as strings
373  // but that is probably too costly
374  // Then the fastest would be to set some bits directly, but little/big endian
375  // has to be considered (maybe TODO)
376  // Is there a better way?
377  int aexp, bexp;
378  double ar = frexp( a, &aexp );
379  double br = frexp( b, &bexp );
380 
381  return aexp == bexp &&
382  qRound( ar * pow( 10.0, significantDigits ) ) == qRound( br * pow( 10.0, significantDigits ) );
383 }
384 
386 inline double qgsRound( double x )
387 {
388  return x < 0.0 ? std::ceil( x - 0.5 ) : std::floor( x + 0.5 );
389 }
390 
391 // Add missing qHash implementation for QDate, QTime, QDateTime
392 // implementations taken from upstream Qt5 versions
393 #if QT_VERSION < 0x050000
394 
397 inline uint qHash( const QDateTime &key )
398 {
399  return qHash( key.toMSecsSinceEpoch() );
400 }
401 
404 inline uint qHash( const QDate &key )
405 {
406  return qHash( key.toJulianDay() );
407 }
408 
411 inline uint qHash( const QTime &key )
412 {
413  return QTime( 0, 0, 0, 0 ).msecsTo( key );
414 }
415 #endif
416 
421 CORE_EXPORT bool qgsVariantLessThan( const QVariant& lhs, const QVariant& rhs );
422 
427 CORE_EXPORT bool qgsVariantGreaterThan( const QVariant& lhs, const QVariant& rhs );
428 
429 CORE_EXPORT QString qgsVsiPrefix( const QString& path );
430 
435 void CORE_EXPORT *qgsMalloc( size_t size );
436 
443 void CORE_EXPORT *qgsCalloc( size_t nmemb, size_t size );
444 
448 void CORE_EXPORT qgsFree( void *ptr );
449 
453 extern CORE_EXPORT const QString GEOWKT;
454 extern CORE_EXPORT const QString PROJECT_SCALES;
455 
457 extern CORE_EXPORT const QString GEOPROJ4;
459 const long GEOSRID = 4326;
461 const long GEOCRS_ID = 3452;
463 const long GEO_EPSG_CRS_ID = 4326;
465 extern CORE_EXPORT const QString GEO_EPSG_CRS_AUTHID;
467 const int PROJ_PREFIX_LEN = 6;
469 const int ELLPS_PREFIX_LEN = 7;
471 const int LAT_PREFIX_LEN = 7;
474 const int USER_CRS_START_ID = 100000;
475 
477 extern CORE_EXPORT const QString GEO_NONE;
478 
479 //
480 // Constants for point symbols
481 //
482 
484 const double MINIMUM_POINT_SIZE = 0.1;
486 const double DEFAULT_POINT_SIZE = 2.0;
487 const double DEFAULT_LINE_WIDTH = 0.26;
488 
490 const double DEFAULT_SEGMENT_EPSILON = 1e-8;
491 
493 
500 typedef unsigned long long qgssize;
501 
502 #if (__GNUC__ > 4 || (__GNUC__ == 4 && __GNUC_MINOR__ >= 6)) || defined(__clang__)
503 #define Q_NOWARN_DEPRECATED_PUSH \
504  _Pragma("GCC diagnostic push") \
505  _Pragma("GCC diagnostic ignored \"-Wdeprecated-declarations\"");
506 #define Q_NOWARN_DEPRECATED_POP \
507  _Pragma("GCC diagnostic pop");
508 #elif defined(_MSC_VER)
509 #define Q_NOWARN_DEPRECATED_PUSH \
510  __pragma(warning(push)) \
511  __pragma(warning(disable:4996))
512 #define Q_NOWARN_DEPRECATED_POP \
513  __pragma(warning(pop))
514 #else
515 #define Q_NOWARN_DEPRECATED_PUSH
516 #define Q_NOWARN_DEPRECATED_POP
517 #endif
518 
519 #ifndef QGISEXTERN
520 #ifdef Q_OS_WIN
521 # define QGISEXTERN extern "C" __declspec( dllexport )
522 # ifdef _MSC_VER
523 // do not warn about C bindings returing QString
524 # pragma warning(disable:4190)
525 # endif
526 #else
527 # if defined(__GNUC__) || defined(__clang__)
528 # define QGISEXTERN extern "C" __attribute__ ((visibility ("default")))
529 # else
530 # define QGISEXTERN extern "C"
531 # endif
532 #endif
533 #endif
534 #endif
535 
536 #if defined(__clang__)
537 #define FALLTHROUGH [[clang::fallthrough]]
538 #else
539 #define FALLTHROUGH
540 #endif
CORE_EXPORT QString qgsVsiPrefix(const QString &path)
Definition: qgis.cpp:342
static double DEFAULT_HIGHLIGHT_BUFFER_MM
Default highlight buffer in mm.
Definition: qgis.h:247
static const QColor DEFAULT_HIGHLIGHT_COLOR
Default highlight color.
Definition: qgis.h:243
qint64 toMSecsSinceEpoch() const
GeometryType
Definition: qgis.h:115
bool qgsFloatNear(float a, float b, float epsilon=4 *FLT_EPSILON)
Compare two floats (but allow some difference)
Definition: qgis.h:363
uint qHash(const QDateTime &key)
Hash implementation for QDateTime.
Definition: qgis.h:397
int msecsTo(const QTime &t) const
WkbType
Used for symbology operations.
Definition: qgis.h:61
static Q_DECL_DEPRECATED const double DEFAULT_IDENTIFY_RADIUS
Old search radius in % of canvas width.
Definition: qgis.h:231
The QGis class provides global constants for use throughout the application.
Definition: qgis.h:40
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:249
QMap< QString, QString > QgsStringMap
Definition: qgis.h:492
~QgsSignalBlocker()
Definition: qgis.h:305
bool qgsDoubleNear(double a, double b, double epsilon=4 *DBL_EPSILON)
Compare two doubles (but allow some difference)
Definition: qgis.h:353
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:269
double qgsRound(double x)
A round function which returns a double to guard against overflows.
Definition: qgis.h:386
QgsSignalBlocker(Object *object)
Constructor for QgsSignalBlocker.
Definition: qgis.h:300
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:490
static const char * QGIS_DEV_VERSION
Definition: qgis.h:52
int toJulianDay() const
QString qgsDoubleToString(double a, int precision=17)
Returns a string representation of a double.
Definition: qgis.h:341
const int ELLPS_PREFIX_LEN
The length of the string "+ellps=".
Definition: qgis.h:469
static const float DEFAULT_MAPTOPIXEL_THRESHOLD
Default threshold between map coordinates and device coordinates for map2pixel simplification.
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:461
CORE_EXPORT const QString GEOPROJ4
PROJ4 string that represents a geographic coord sys.
Definition: qgis.cpp:54
RAII signal blocking class.
Definition: qgis.h:293
void CORE_EXPORT qgsFree(void *ptr)
Frees the memory space pointed to by ptr.
Definition: qgis.cpp:264
UserEvent
User defined event types.
Definition: qgis.h:218
static QString QGIS_VERSION
Definition: qgis.h:46
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:500
static const double DEFAULT_SEARCH_RADIUS_MM
Identify search radius in mm.
Definition: qgis.h:235
const double DEFAULT_POINT_SIZE
Magic number that determines the default point size for point symbols.
Definition: qgis.h:486
const int USER_CRS_START_ID
Magick number that determines whether a projection crsid is a system (srs.db) or user (~/...
Definition: qgis.h:474
QgsSignalBlocker< Object > whileBlocking(Object *object)
Temporarily blocks signals from a QObject while calling a single method from the object.
Definition: qgis.h:333
const long GEOSRID
Magic number for a geographic coord sys in POSTGIS SRID.
Definition: qgis.h:459
const double MINIMUM_POINT_SIZE
Magic number that determines the minimum allowable point size for point symbols.
Definition: qgis.h:484
bool qgsDoubleNearSig(double a, double b, int significantDigits=10)
Compare two doubles using specified number of significant digits.
Definition: qgis.h:370
const double DEFAULT_LINE_WIDTH
Definition: qgis.h:487
CORE_EXPORT const QString PROJECT_SCALES
Definition: qgis.cpp:70
DataType
Raster data types.
Definition: qgis.h:133
const int LAT_PREFIX_LEN
The length of the string "+lat_1=".
Definition: qgis.h:471
UnitType
Map units that qgis supports.
Definition: qgis.h:159
void(*)() cast_to_fptr(void *p)
Definition: qgis.h:272
const int PROJ_PREFIX_LEN
The length of the string "+proj=".
Definition: qgis.h:467
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:337
static QString QGIS_RELEASE_NAME
Definition: qgis.h:50
static double SCALE_PRECISION
Fudge factor used to compare two scales.
Definition: qgis.h:257
static const int QGIS_VERSION_INT
Definition: qgis.h:48
void CORE_EXPORT * qgsMalloc(size_t size)
Allocates size bytes and returns a pointer to the allocated memory.
Definition: qgis.cpp:234
static double DEFAULT_HIGHLIGHT_MIN_WIDTH_MM
Default highlight line/outline minimum width in mm.
Definition: qgis.h:251
Object * operator->()
Returns pointer to blocked QObject.
Definition: qgis.h:311
const long GEO_EPSG_CRS_ID
Magic number for a geographic coord sys in EpsgCrsId ID format.
Definition: qgis.h:463
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