QGIS API Documentation  3.9.0-Master (224899f119)
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 <QMetaEnum>
22 #include <cfloat>
23 #include <memory>
24 #include <cmath>
25 
26 #include "qgstolerance.h"
27 #include "qgis_core.h"
28 #include "qgis_sip.h"
29 
30 #ifdef SIP_RUN
31 % ModuleHeaderCode
32 #include <qgis.h>
33 % End
34 
35 % ModuleCode
36 int QgisEvent = QEvent::User + 1;
37 % End
38 #endif
39 
40 
45 class CORE_EXPORT Qgis
46 {
47  public:
48  // Version constants
49  //
51  static const QString QGIS_VERSION;
53  static const int QGIS_VERSION_INT;
55  static const QString QGIS_RELEASE_NAME;
57  static const char *QGIS_DEV_VERSION;
58 
59  // Enumerations
60  //
61 
67  {
68  Info = 0,
69  Warning = 1,
70  Critical = 2,
71  Success = 3,
72  None = 4
73  };
74 
79  enum DataType
80  {
81  UnknownDataType = 0,
82  Byte = 1,
83  UInt16 = 2,
84  Int16 = 3,
85  UInt32 = 4,
86  Int32 = 5,
87  Float32 = 6,
88  Float64 = 7,
89  CInt16 = 8,
90  CInt32 = 9,
91  CFloat32 = 10,
92  CFloat64 = 11,
93  ARGB32 = 12,
94  ARGB32_Premultiplied = 13
95  };
96 
100  static const double DEFAULT_SEARCH_RADIUS_MM;
101 
103  static const float DEFAULT_MAPTOPIXEL_THRESHOLD;
104 
109  static const QColor DEFAULT_HIGHLIGHT_COLOR;
110 
114  static const double DEFAULT_HIGHLIGHT_BUFFER_MM;
115 
119  static const double DEFAULT_HIGHLIGHT_MIN_WIDTH_MM;
120 
126  static const double SCALE_PRECISION;
127 
132  static const double DEFAULT_Z_COORDINATE;
133 
139  static const double UI_SCALE_FACTOR;
140 
145  static const double DEFAULT_SNAP_TOLERANCE;
146 
152 };
153 
154 // hack to workaround warnings when casting void pointers
155 // retrieved from QLibrary::resolve to function pointers.
156 // It's assumed that this works on all systems supporting
157 // QLibrary
158 #define cast_to_fptr(f) f
159 
160 
169 // based on Boojum's code from http://stackoverflow.com/questions/3556687/prevent-firing-signals-in-qt
170 template<class Object> class QgsSignalBlocker SIP_SKIP SIP_SKIP // clazy:exclude=rule-of-three
171 {
172  public:
173 
178  explicit QgsSignalBlocker( Object *object )
179  : mObject( object )
180  , mPreviousState( object->blockSignals( true ) )
181  {}
182 
184  {
185  mObject->blockSignals( mPreviousState );
186  }
187 
189  Object *operator->() { return mObject; }
190 
191  private:
192 
193  Object *mObject = nullptr;
194  bool mPreviousState;
195 
196 };
197 
211 // based on Boojum's code from http://stackoverflow.com/questions/3556687/prevent-firing-signals-in-qt
212 template<class Object> inline QgsSignalBlocker<Object> whileBlocking( Object *object ) SIP_SKIP SIP_SKIP
213 {
214  return QgsSignalBlocker<Object>( object );
215 }
216 
218 CORE_EXPORT uint qHash( const QVariant &variant );
219 
225 inline QString qgsDoubleToString( double a, int precision = 17 )
226 {
227  if ( precision )
228  {
229  QString str = QString::number( a, 'f', precision );
230  if ( str.contains( QLatin1Char( '.' ) ) )
231  {
232  // remove ending 0s
233  int idx = str.length() - 1;
234  while ( str.at( idx ) == '0' && idx > 1 )
235  {
236  idx--;
237  }
238  if ( idx < str.length() - 1 )
239  str.truncate( str.at( idx ) == '.' ? idx : idx + 1 );
240  }
241  return str;
242  }
243  else
244  {
245  // avoid printing -0
246  // see https://bugreports.qt.io/browse/QTBUG-71439
247  const QString str( QString::number( a, 'f', precision ) );
248  if ( str == QLatin1String( "-0" ) )
249  {
250  return QLatin1String( "0" );
251  }
252  else
253  {
254  return str;
255  }
256  }
257 }
258 
265 inline bool qgsDoubleNear( double a, double b, double epsilon = 4 * std::numeric_limits<double>::epsilon() )
266 {
267  if ( std::isnan( a ) || std::isnan( b ) )
268  return std::isnan( a ) && std::isnan( b ) ;
269 
270  const double diff = a - b;
271  return diff > -epsilon && diff <= epsilon;
272 }
273 
280 inline bool qgsFloatNear( float a, float b, float epsilon = 4 * FLT_EPSILON )
281 {
282  if ( std::isnan( a ) || std::isnan( b ) )
283  return std::isnan( a ) && std::isnan( b ) ;
284 
285  const float diff = a - b;
286  return diff > -epsilon && diff <= epsilon;
287 }
288 
290 inline bool qgsDoubleNearSig( double a, double b, int significantDigits = 10 )
291 {
292  if ( std::isnan( a ) || std::isnan( b ) )
293  return std::isnan( a ) && std::isnan( b ) ;
294 
295  // The most simple would be to print numbers as %.xe and compare as strings
296  // but that is probably too costly
297  // Then the fastest would be to set some bits directly, but little/big endian
298  // has to be considered (maybe TODO)
299  // Is there a better way?
300  int aexp, bexp;
301  double ar = std::frexp( a, &aexp );
302  double br = std::frexp( b, &bexp );
303 
304  return aexp == bexp &&
305  std::round( ar * std::pow( 10.0, significantDigits ) ) == std::round( br * std::pow( 10.0, significantDigits ) );
306 }
307 
313 inline double qgsRound( double number, int places )
314 {
315  double m = ( number < 0.0 ) ? -1.0 : 1.0;
316  double scaleFactor = std::pow( 10.0, places );
317  return ( std::round( number * m * scaleFactor ) / scaleFactor ) * m;
318 }
319 
320 
321 #ifndef SIP_RUN
322 
324 
334 namespace qgis
335 {
336  // as_const
337 
346  template <typename T> struct QgsAddConst { typedef const T Type; };
347 
348  template <typename T>
349  constexpr typename QgsAddConst<T>::Type &as_const( T &t ) noexcept { return t; }
350 
351  template <typename T>
352  void as_const( const T && ) = delete;
353 
354  // make_unique - from https://stackoverflow.com/a/17902439/1861260
355 
356  template<class T> struct _Unique_if
357  {
358  typedef std::unique_ptr<T> _Single_object;
359  };
360 
361  template<class T> struct _Unique_if<T[]>
362  {
363  typedef std::unique_ptr<T[]> _Unknown_bound;
364  };
365 
366  template<class T, size_t N> struct _Unique_if<T[N]>
367  {
368  typedef void _Known_bound;
369  };
370 
371  template<class T, class... Args>
372  typename _Unique_if<T>::_Single_object
373  make_unique( Args &&... args )
374  {
375  return std::unique_ptr<T>( new T( std::forward<Args>( args )... ) );
376  }
377 
378  template<class T>
379  typename _Unique_if<T>::_Unknown_bound
380  make_unique( size_t n )
381  {
382  typedef typename std::remove_extent<T>::type U;
383  return std::unique_ptr<T>( new U[n]() );
384  }
385 
386  template<class T, class... Args>
387  typename _Unique_if<T>::_Known_bound
388  make_unique( Args &&... ) = delete;
389 
402  template<typename... Args> struct overload
403  {
404  template<typename C, typename R>
405  static constexpr auto of( R( C::*pmf )( Args... ) ) -> decltype( pmf )
406  {
407  return pmf;
408  }
409  };
410 }
412 #endif
413 
419 template<class T> const QMap<T, QString> qgsEnumMap() SIP_SKIP
420 {
421  QMetaEnum metaEnum = QMetaEnum::fromType<T>();
422  Q_ASSERT( metaEnum.isValid() );
423  QMap<T, QString> enumMap;
424  for ( int idx = 0; idx < metaEnum.keyCount(); ++idx )
425  {
426  const char *enumKey = metaEnum.key( idx );
427  enumMap.insert( static_cast<T>( metaEnum.keyToValue( enumKey ) ), QString( enumKey ) );
428  }
429  return enumMap;
430 }
431 
436 template<class T> QString qgsEnumValueToKey( const T &value ) SIP_SKIP
437 {
438  QMetaEnum metaEnum = QMetaEnum::fromType<T>();
439  Q_ASSERT( metaEnum.isValid() );
440  return QString::fromUtf8( metaEnum.valueToKey( value ) );
441 }
442 
448 template<class T> T qgsEnumKeyToValue( const QString &key, const T &defaultValue ) SIP_SKIP
449 {
450  QMetaEnum metaEnum = QMetaEnum::fromType<T>();
451  Q_ASSERT( metaEnum.isValid() );
452  bool ok = false;
453  T v = static_cast<T>( metaEnum.keyToValue( key.toUtf8().data(), &ok ) );
454  if ( ok )
455  return v;
456  else
457  return defaultValue;
458 }
459 
460 
470 CORE_EXPORT double qgsPermissiveToDouble( QString string, bool &ok );
471 
481 CORE_EXPORT int qgsPermissiveToInt( QString string, bool &ok );
482 
492 CORE_EXPORT qlonglong qgsPermissiveToLongLong( QString string, bool &ok );
493 
503 CORE_EXPORT bool qgsVariantLessThan( const QVariant &lhs, const QVariant &rhs );
504 
513 CORE_EXPORT bool qgsVariantEqual( const QVariant &lhs, const QVariant &rhs );
514 
515 
522 CORE_EXPORT bool qgsVariantGreaterThan( const QVariant &lhs, const QVariant &rhs );
523 
524 CORE_EXPORT QString qgsVsiPrefix( const QString &path );
525 
531 void CORE_EXPORT *qgsMalloc( size_t size ) SIP_SKIP;
532 
540 void CORE_EXPORT *qgsCalloc( size_t nmemb, size_t size ) SIP_SKIP;
541 
546 void CORE_EXPORT qgsFree( void *ptr ) SIP_SKIP;
547 
552 extern CORE_EXPORT const QString GEOWKT;
553 extern CORE_EXPORT const QString PROJECT_SCALES;
554 
556 extern CORE_EXPORT const QString GEOPROJ4;
558 const long GEOSRID = 4326;
560 const long GEOCRS_ID = 3452;
562 const long GEO_EPSG_CRS_ID = 4326;
564 extern CORE_EXPORT const QString GEO_EPSG_CRS_AUTHID;
565 
569 const int USER_CRS_START_ID = 100000;
570 
572 extern CORE_EXPORT const QString GEO_NONE;
573 
574 //
575 // Constants for point symbols
576 //
577 
579 const double DEFAULT_POINT_SIZE = 2.0;
580 const double DEFAULT_LINE_WIDTH = 0.26;
581 
583 const double DEFAULT_SEGMENT_EPSILON = 1e-8;
584 
586 #ifndef SIP_RUN
587 
589 const int PREVIEW_JOB_DELAY_MS = 250;
590 
592 const int MAXIMUM_LAYER_PREVIEW_TIME_MS = 250;
593 #endif
594 
596 
597 typedef QMap<QString, QString> QgsStringMap SIP_SKIP;
598 
606 typedef unsigned long long qgssize;
607 
608 #ifndef SIP_RUN
609 #if (__GNUC__ > 4 || (__GNUC__ == 4 && __GNUC_MINOR__ >= 6)) || defined(__clang__)
610 
611 #define Q_NOWARN_DEPRECATED_PUSH \
612  _Pragma("GCC diagnostic push") \
613  _Pragma("GCC diagnostic ignored \"-Wdeprecated-declarations\"");
614 #define Q_NOWARN_DEPRECATED_POP \
615  _Pragma("GCC diagnostic pop");
616 #define Q_NOWARN_UNREACHABLE_PUSH
617 #define Q_NOWARN_UNREACHABLE_POP
618 
619 #elif defined(_MSC_VER)
620 
621 #define Q_NOWARN_DEPRECATED_PUSH \
622  __pragma(warning(push)) \
623  __pragma(warning(disable:4996))
624 #define Q_NOWARN_DEPRECATED_POP \
625  __pragma(warning(pop))
626 #define Q_NOWARN_UNREACHABLE_PUSH \
627  __pragma(warning(push)) \
628  __pragma(warning(disable:4702))
629 #define Q_NOWARN_UNREACHABLE_POP \
630  __pragma(warning(pop))
631 
632 #else
633 
634 #define Q_NOWARN_DEPRECATED_PUSH
635 #define Q_NOWARN_DEPRECATED_POP
636 #define Q_NOWARN_UNREACHABLE_PUSH
637 #define Q_NOWARN_UNREACHABLE_POP
638 
639 #endif
640 #endif
641 
642 #ifndef QGISEXTERN
643 #ifdef Q_OS_WIN
644 # define QGISEXTERN extern "C" __declspec( dllexport )
645 # ifdef _MSC_VER
646 // do not warn about C bindings returning QString
647 # pragma warning(disable:4190)
648 # endif
649 #else
650 # if defined(__GNUC__) || defined(__clang__)
651 # define QGISEXTERN extern "C" __attribute__ ((visibility ("default")))
652 # else
653 # define QGISEXTERN extern "C"
654 # endif
655 #endif
656 #endif
657 #endif
658 
659 #if __cplusplus >= 201500
660 #define FALLTHROUGH [[fallthrough]];
661 #elif defined(__clang__)
662 #define FALLTHROUGH [[clang::fallthrough]];
663 #elif defined(__GNUC__) && __GNUC__ >= 7
664 #define FALLTHROUGH [[gnu::fallthrough]];
665 #else
666 #define FALLTHROUGH
667 #endif
668 
669 // see https://infektor.net/posts/2017-01-19-using-cpp17-attributes-today.html#using-the-nodiscard-attribute
670 #if __cplusplus >= 201703L
671 #define NODISCARD [[nodiscard]]
672 #elif defined(__clang__)
673 #define NODISCARD [[nodiscard]]
674 #elif defined(_MSC_VER)
675 #define NODISCARD // no support
676 #elif defined(__has_cpp_attribute)
677 #if __has_cpp_attribute(nodiscard)
678 #define NODISCARD [[nodiscard]]
679 #elif __has_cpp_attribute(gnu::warn_unused_result)
680 #define NODISCARD [[gnu::warn_unused_result]]
681 #else
682 #define NODISCARD Q_REQUIRED_RESULT
683 #endif
684 #else
685 #define NODISCARD Q_REQUIRED_RESULT
686 #endif
687 
688 #if __cplusplus >= 201703L
689 #define MAYBE_UNUSED [[maybe_unused]]
690 #elif defined(__clang__)
691 #define MAYBE_UNUSED [[maybe_unused]]
692 #elif defined(_MSC_VER)
693 #define MAYBE_UNUSED // no support
694 #elif defined(__has_cpp_attribute)
695 #if __has_cpp_attribute(gnu::unused)
696 #define MAYBE_UNUSED [[gnu::unused]]
697 #else
698 #define MAYBE_UNUSED
699 #endif
700 #else
701 #define MAYBE_UNUSED
702 #endif
703 
704 #ifndef FINAL
705 #define FINAL final
706 #endif
707 
708 
CORE_EXPORT QString qgsVsiPrefix(const QString &path)
Definition: qgis.cpp:227
int precision
static const QString QGIS_VERSION
Version string.
Definition: qgis.h:51
static const char * QGIS_DEV_VERSION
The development version.
Definition: qgis.h:57
static const double UI_SCALE_FACTOR
UI scaling factor.
Definition: qgis.h:139
bool qgsFloatNear(float a, float b, float epsilon=4 *FLT_EPSILON)
Compare two floats (but allow some difference)
Definition: qgis.h:280
CORE_EXPORT bool qgsVariantEqual(const QVariant &lhs, const QVariant &rhs)
Compares two QVariant values and returns whether they are equal, two NULL values are always treated a...
Definition: qgis.cpp:298
QString qgsEnumValueToKey(const T &value)
Returns the value for the given key of an enum.
Definition: qgis.h:436
bool qgsDoubleNear(double a, double b, double epsilon=4 *std::numeric_limits< double >::epsilon())
Compare two doubles (but allow some difference)
Definition: qgis.h:265
DataType
Raster data types.
Definition: qgis.h:79
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:109
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:134
MessageLevel
Level for messages This will be used both for message log and message bar in application.
Definition: qgis.h:66
static const int QGIS_VERSION_INT
Version number used for comparing versions using the "Check QGIS Version" function.
Definition: qgis.h:53
QMap< QString, QString > QgsStringMap
Definition: qgis.h:597
~QgsSignalBlocker()
Definition: qgis.h:183
The Qgis class provides global constants for use throughout the application.
Definition: qgis.h:45
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:154
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:132
QgsSignalBlocker(Object *object)
Constructor for QgsSignalBlocker.
Definition: qgis.h:178
T qgsEnumKeyToValue(const QString &key, const T &defaultValue)
Returns the value corresponding to the given key of an enum.
Definition: qgis.h:448
static const double DEFAULT_SNAP_TOLERANCE
Default snapping distance tolerance.
Definition: qgis.h:145
CORE_EXPORT const QString GEO_NONE
Constant that holds the string representation for "No ellips/No CRS".
Definition: qgis.cpp:72
const double DEFAULT_SEGMENT_EPSILON
Default snapping tolerance for segments.
Definition: qgis.h:583
#define SIP_SKIP
Definition: qgis_sip.h:126
QString qgsDoubleToString(double a, int precision=17)
Returns a string representation of a double.
Definition: qgis.h:225
const long GEOCRS_ID
Magic number for a geographic coord sys in QGIS srs.db tbl_srs.srs_id.
Definition: qgis.h:560
static const double DEFAULT_SEARCH_RADIUS_MM
Identify search radius in mm.
Definition: qgis.h:100
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:98
CORE_EXPORT const QString GEOPROJ4
PROJ4 string that represents a geographic coord sys.
Definition: qgis.cpp:51
RAII signal blocking class.
Definition: qgis.h:170
static const QgsTolerance::UnitType DEFAULT_SNAP_UNITS
Default snapping distance units.
Definition: qgis.h:151
void CORE_EXPORT qgsFree(void *ptr)
Frees the memory space pointed to by ptr.
Definition: qgis.cpp:149
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:112
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:606
const double DEFAULT_POINT_SIZE
Magic number that determines the default point size for point symbols.
Definition: qgis.h:579
static const float DEFAULT_MAPTOPIXEL_THRESHOLD
Default threshold between map coordinates and device coordinates for map2pixel simplification.
Definition: qgis.h:103
const int USER_CRS_START_ID
Magick number that determines whether a projection crsid is a system (srs.db) or user (~/...
Definition: qgis.h:569
const QMap< T, QString > qgsEnumMap()
Returns a map of all enum entries.
Definition: qgis.h:419
QgsSignalBlocker< Object > whileBlocking(Object *object)
Temporarily blocks signals from a QObject while calling a single method from the object.
Definition: qgis.h:212
const long GEOSRID
Magic number for a geographic coord sys in POSTGIS SRID.
Definition: qgis.h:558
static const QString QGIS_RELEASE_NAME
Release name.
Definition: qgis.h:55
double qgsRound(double number, int places)
Returns a double number, rounded (as close as possible) to the specified number of places...
Definition: qgis.h:313
bool qgsDoubleNearSig(double a, double b, int significantDigits=10)
Compare two doubles using specified number of significant digits.
Definition: qgis.h:290
const double DEFAULT_LINE_WIDTH
Definition: qgis.h:580
CORE_EXPORT const QString PROJECT_SCALES
Definition: qgis.cpp:66
CORE_EXPORT uint qHash(const QVariant &variant)
Hash for QVariant.
Definition: qgis.cpp:252
static const double DEFAULT_HIGHLIGHT_MIN_WIDTH_MM
Default highlight line/stroke minimum width in mm.
Definition: qgis.h:119
static const double DEFAULT_HIGHLIGHT_BUFFER_MM
Default highlight buffer in mm.
Definition: qgis.h:114
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:105
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:222
void CORE_EXPORT * qgsMalloc(size_t size)
Allocates size bytes and returns a pointer to the allocated memory.
Definition: qgis.cpp:119
Object * operator->()
Returns pointer to blocked QObject.
Definition: qgis.h:189
const long GEO_EPSG_CRS_ID
Magic number for a geographic coord sys in EpsgCrsId ID format.
Definition: qgis.h:562
static const double SCALE_PRECISION
Fudge factor used to compare two scales.
Definition: qgis.h:126
CORE_EXPORT const QString GEO_EPSG_CRS_AUTHID
Geographic coord sys from EPSG authority.
Definition: qgis.cpp:70
CORE_EXPORT const QString GEOWKT
Wkt string that represents a geographic coord sys.
Definition: qgis.cpp:53