QGIS API Documentation  3.21.0-Master (56b4176581)
qgsfeaturerequest.h
Go to the documentation of this file.
1 /***************************************************************************
2  qgsfeaturerequest.h
3  ---------------------
4  begin : Mai 2012
5  copyright : (C) 2012 by Martin Dobias
6  email : wonder dot sk at gmail dot com
7  ***************************************************************************
8  * *
9  * This program is free software; you can redistribute it and/or modify *
10  * it under the terms of the GNU General Public License as published by *
11  * the Free Software Foundation; either version 2 of the License, or *
12  * (at your option) any later version. *
13  * *
14  ***************************************************************************/
15 #ifndef QGSFEATUREREQUEST_H
16 #define QGSFEATUREREQUEST_H
17 
18 #include "qgis_core.h"
19 #include "qgis_sip.h"
20 #include <QFlags>
21 #include <QList>
22 #include <memory>
23 
24 #include "qgis.h"
25 #include "qgsfeature.h"
26 #include "qgsrectangle.h"
27 #include "qgsexpression.h"
28 #include "qgsexpressioncontext.h"
29 #include "qgssimplifymethod.h"
32 
33 
83 class CORE_EXPORT QgsFeatureRequest
84 {
85  public:
86  enum Flag
87  {
88  NoFlags = 0,
89  NoGeometry = 1,
90  SubsetOfAttributes = 2,
91  ExactIntersect = 4,
92  IgnoreStaticNodesDuringExpressionCompilation = 8,
93  EmbeddedSymbols = 16,
94  };
95  Q_DECLARE_FLAGS( Flags, Flag )
96 
97 
101  {
105  FilterFids
106  };
107 
110  {
111  GeometryNoCheck = 0,
112  GeometrySkipInvalid = 1,
113  GeometryAbortOnInvalid = 2,
114  };
115 
139  class CORE_EXPORT OrderByClause
140  {
141  public:
142 
151  OrderByClause( const QString &expression, bool ascending = true );
152 
160  OrderByClause( const QString &expression, bool ascending, bool nullsfirst );
161 
170  OrderByClause( const QgsExpression &expression, bool ascending = true );
171 
179  OrderByClause( const QgsExpression &expression, bool ascending, bool nullsfirst );
180 
185  QgsExpression expression() const;
186 
194  bool prepare( QgsExpressionContext *context );
195 
200  bool ascending() const;
201 
205  void setAscending( bool ascending );
206 
211  bool nullsFirst() const;
212 
216  void setNullsFirst( bool nullsFirst );
217 
221  QString dump() const;
222 
223  // friend inline int qHash(const OrderByClause &a) { return qHash(a.mExpression.expression()) ^ qHash(a.mAscending) ^ qHash( a.mNullsFirst); }
224 
225  private:
226  QgsExpression mExpression;
227  bool mAscending;
228  bool mNullsFirst;
229  };
230 
231 
239  class OrderBy : public QList<QgsFeatureRequest::OrderByClause>
240  {
241  public:
242 
246  CORE_EXPORT OrderBy();
247 
251  CORE_EXPORT OrderBy( const QList<QgsFeatureRequest::OrderByClause> &other );
252 
259  QList<QgsFeatureRequest::OrderByClause> CORE_EXPORT list() const;
260 
264  void CORE_EXPORT save( QDomElement &elem ) const;
265 
269  void CORE_EXPORT load( const QDomElement &elem );
270 
275  QSet<QString> CORE_EXPORT usedAttributes() const;
276 
281  QSet<int> CORE_EXPORT usedAttributeIndices( const QgsFields &fields ) const;
282 
286  QString CORE_EXPORT dump() const;
287  };
288 
292  static const QString ALL_ATTRIBUTES;
293 
297  explicit QgsFeatureRequest( QgsFeatureId fid );
299  explicit QgsFeatureRequest( const QgsFeatureIds &fids );
300 
308  explicit QgsFeatureRequest( const QgsRectangle &rectangle );
309 
311  explicit QgsFeatureRequest( const QgsExpression &expr, const QgsExpressionContext &context = QgsExpressionContext() );
315  QgsFeatureRequest &operator=( const QgsFeatureRequest &rh );
316 
318 
330  FilterType filterType() const { return mFilter; }
331 
344  Qgis::SpatialFilterType spatialFilterType() const { return mSpatialFilter; }
345 
358  QgsFeatureRequest &setFilterRect( const QgsRectangle &rectangle );
359 
375  QgsRectangle filterRect() const;
376 
392  QgsFeatureRequest &setDistanceWithin( const QgsGeometry &geometry, double distance );
393 
408  QgsGeometry referenceGeometry() const { return mReferenceGeometry; }
409 
421  double distanceWithin() const { return mDistanceWithin; }
422 
431  QgsFeatureRequest &setFilterFid( QgsFeatureId fid );
432 
439  QgsFeatureId filterFid() const { return mFilterFid; }
440 
449  QgsFeatureRequest &setFilterFids( const QgsFeatureIds &fids );
450 
457  const QgsFeatureIds &filterFids() const { return mFilterFids; }
458 
466  QgsFeatureRequest &setInvalidGeometryCheck( InvalidGeometryCheck check );
467 
473  InvalidGeometryCheck invalidGeometryCheck() const { return mInvalidGeometryFilter; }
474 
482 #ifndef SIP_RUN
483  QgsFeatureRequest &setInvalidGeometryCallback( const std::function< void( const QgsFeature & )> &callback );
484 #else
485  QgsFeatureRequest &setInvalidGeometryCallback( SIP_PYCALLABLE / AllowNone / );
486  % MethodCode
487  Py_BEGIN_ALLOW_THREADS
488 
489  sipCpp->setInvalidGeometryCallback( [a0]( const QgsFeature &arg )
490  {
491  SIP_BLOCK_THREADS
492  Py_XDECREF( sipCallMethod( NULL, a0, "D", &arg, sipType_QgsFeature, NULL ) );
493  SIP_UNBLOCK_THREADS
494  } );
495 
496  sipRes = sipCpp;
497 
498  Py_END_ALLOW_THREADS
499  % End
500 #endif
501 
509  std::function< void( const QgsFeature & ) > invalidGeometryCallback() const { return mInvalidGeometryCallback; } SIP_SKIP
510 
520  QgsFeatureRequest &setFilterExpression( const QString &expression );
521 
527  QgsExpression *filterExpression() const { return mFilterExpression.get(); }
528 
538  QgsFeatureRequest &combineFilterExpression( const QString &expression );
539 
546  QgsExpressionContext *expressionContext() { return &mExpressionContext; }
547 
554  QgsFeatureRequest &setExpressionContext( const QgsExpressionContext &context );
555 
567  QgsFeatureRequest &disableFilter() { mFilter = FilterNone; mFilterExpression.reset(); return *this; }
568 
580  QgsFeatureRequest &addOrderBy( const QString &expression, bool ascending = true );
581 
591  QgsFeatureRequest &addOrderBy( const QString &expression, bool ascending, bool nullsfirst );
592 
598  OrderBy orderBy() const;
599 
605  QgsFeatureRequest &setOrderBy( const OrderBy &orderBy );
606 
613  QgsFeatureRequest &setLimit( long long limit );
614 
620 #ifndef SIP_RUN
621  long long limit() const { return mLimit; }
622 #else
623  long long limit() const;
624 #endif
625 
631  QgsFeatureRequest &setFlags( QgsFeatureRequest::Flags flags );
632 
638  Flags flags() const { return mFlags; }
639 
656  QgsFeatureRequest &setSubsetOfAttributes( const QgsAttributeList &attrs );
657 
673  QgsFeatureRequest &setNoAttributes();
674 
688  QgsAttributeList subsetOfAttributes() const { return mAttrs; }
689 
701  QgsFeatureRequest &setSubsetOfAttributes( const QStringList &attrNames, const QgsFields &fields );
702 
714  QgsFeatureRequest &setSubsetOfAttributes( const QSet<QString> &attrNames, const QgsFields &fields );
715 
722  QgsFeatureRequest &setSimplifyMethod( const QgsSimplifyMethod &simplifyMethod );
723 
730  const QgsSimplifyMethod &simplifyMethod() const { return mSimplifyMethod; }
731 
740  QgsCoordinateReferenceSystem destinationCrs() const;
741 
749  QgsCoordinateTransformContext transformContext() const;
750 
774  QgsFeatureRequest &setDestinationCrs( const QgsCoordinateReferenceSystem &crs, const QgsCoordinateTransformContext &context );
775 
784 #ifndef SIP_RUN
785  QgsFeatureRequest &setTransformErrorCallback( const std::function< void( const QgsFeature & )> &callback );
786 #else
787  QgsFeatureRequest &setTransformErrorCallback( SIP_PYCALLABLE / AllowNone / );
788  % MethodCode
789  Py_BEGIN_ALLOW_THREADS
790 
791  sipCpp->setTransformErrorCallback( [a0]( const QgsFeature &arg )
792  {
793  SIP_BLOCK_THREADS
794  Py_XDECREF( sipCallMethod( NULL, a0, "D", &arg, sipType_QgsFeature, NULL ) );
795  SIP_UNBLOCK_THREADS
796  } );
797 
798  sipRes = sipCpp;
799 
800  Py_END_ALLOW_THREADS
801  % End
802 #endif
803 
812  std::function< void( const QgsFeature & ) > transformErrorCallback() const { return mTransformErrorCallback; } SIP_SKIP
813 
814 
824  bool acceptFeature( const QgsFeature &feature );
825 
835  Q_DECL_DEPRECATED int connectionTimeout() const SIP_DEPRECATED;
836 
846  Q_DECL_DEPRECATED QgsFeatureRequest &setConnectionTimeout( int connectionTimeout ) SIP_DEPRECATED;
847 
857  int timeout() const;
858 
868  QgsFeatureRequest &setTimeout( int timeout );
869 
883  bool requestMayBeNested() const;
884 
898  QgsFeatureRequest &setRequestMayBeNested( bool requestMayBeNested );
899 
911  void setFeedback( QgsFeedback *feedback );
912 
921  QgsFeedback *feedback() const;
922 
923  protected:
924 
928  FilterType mFilter = FilterNone;
929 
935  Qgis::SpatialFilterType mSpatialFilter = Qgis::SpatialFilterType::NoFilter;
936 
940  QgsRectangle mFilterRect;
941 
945  QgsGeometry mReferenceGeometry;
946 
950  std::unique_ptr< QgsGeometryEngine > mReferenceGeometryEngine;
951 
955  double mDistanceWithin = 0;
956 
957  QgsFeatureId mFilterFid = -1;
958  QgsFeatureIds mFilterFids;
959  std::unique_ptr< QgsExpression > mFilterExpression;
960  QgsExpressionContext mExpressionContext;
961  Flags mFlags = Flags();
963  QgsSimplifyMethod mSimplifyMethod;
964  long long mLimit = -1;
965  OrderBy mOrderBy;
966  InvalidGeometryCheck mInvalidGeometryFilter = GeometryNoCheck;
967  std::function< void( const QgsFeature & ) > mInvalidGeometryCallback;
968  std::function< void( const QgsFeature & ) > mTransformErrorCallback;
970  QgsCoordinateTransformContext mTransformContext;
971  int mTimeout = -1;
972  int mRequestMayBeNested = false;
973  QgsFeedback *mFeedback = nullptr;
974 };
975 
977 
978 
979 class QgsFeatureIterator;
981 
987 class CORE_EXPORT QgsAbstractFeatureSource
988 {
989  public:
990  virtual ~QgsAbstractFeatureSource();
991 
992 
993  // IMPORTANT -- do NOT remove the /TransferBack/ annotation here -- while it looks completely wrong, it's
994  // required for Python data providers to work correctly! Argh!
995 
1002 
1003  // IMPORTANT -- do NOT remove the /TransferBack/ annotation here -- while it looks completely wrong, it's
1004  // required for Python data providers to work correctly! Argh!
1005 
1006  protected:
1007  void iteratorOpened( QgsAbstractFeatureIterator *it );
1008  void iteratorClosed( QgsAbstractFeatureIterator *it );
1009 
1010  QSet< QgsAbstractFeatureIterator * > mActiveIterators;
1011 
1012  template<typename> friend class QgsAbstractFeatureIteratorFromSource;
1013 };
1014 
1015 #endif // QGSFEATUREREQUEST_H
The Qgis class provides global constants for use throughout the application.
Definition: qgis.h:63
SpatialFilterType
Feature request spatial filter types.
Definition: qgis.h:725
Helper template that cares of two things: 1.
Internal feature iterator to be implemented within data providers.
Base class that can be used for any class that is capable of returning features.
QSet< QgsAbstractFeatureIterator * > mActiveIterators
virtual QgsFeatureIterator getFeatures(const QgsFeatureRequest &request=QgsFeatureRequest())=0
Gets an iterator for features matching the specified request.
This class represents a coordinate reference system (CRS).
Contains information about the context in which a coordinate transform is executed.
Expression contexts are used to encapsulate the parameters around which a QgsExpression should be eva...
Class for parsing and evaluation of expressions (formerly called "search strings").
Wrapper for iterator of features from vector data provider or vector layer.
The OrderByClause class represents an order by clause for a QgsFeatureRequest.
Represents a list of OrderByClauses, with the most important first and the least important last.
CORE_EXPORT OrderBy()
Create a new empty order by.
This class wraps a request for features to a vector layer (or directly its vector data provider).
std::function< void(const QgsFeature &) > invalidGeometryCallback() const
Returns the callback function to use when encountering an invalid geometry and invalidGeometryCheck()...
const QgsSimplifyMethod & simplifyMethod() const
Returns the simplification method for geometries that will be fetched.
InvalidGeometryCheck
Handling of features with invalid geometries.
InvalidGeometryCheck invalidGeometryCheck() const
Returns the invalid geometry checking behavior.
QgsExpression * filterExpression() const
Returns the filter expression (if set).
long long limit() const
Returns the maximum number of features to request, or -1 if no limit set.
QgsGeometry referenceGeometry() const
Returns the reference geometry used for spatial filtering of features.
static const QString ALL_ATTRIBUTES
A special attribute that if set matches all attributes.
Flags flags() const
Returns the flags which affect how features are fetched.
QgsExpressionContext * expressionContext()
Returns the expression context used to evaluate filter expressions.
Qgis::SpatialFilterType spatialFilterType() const
Returns the spatial filter type which is currently set on this request.
double distanceWithin() const
Returns the maximum distance from the referenceGeometry() of fetched features, if spatialFilterType()...
QgsAttributeList subsetOfAttributes() const
Returns the subset of attributes which at least need to be fetched.
QgsFeatureRequest & disableFilter()
Disables any attribute/ID filtering.
FilterType filterType() const
Returns the attribute/ID filter type which is currently set on this request.
const QgsFeatureIds & filterFids() const
Returns the feature IDs that should be fetched.
FilterType
Types of filters.
@ FilterFid
Filter using feature ID.
@ FilterNone
No filter is applied.
@ FilterExpression
Filter using expression.
std::function< void(const QgsFeature &) > transformErrorCallback() const
Returns the callback function to use when encountering a transform error when iterating features and ...
QgsFeatureId filterFid() const
Returns the feature ID that should be fetched.
The feature class encapsulates a single feature including its unique ID, geometry and a list of field...
Definition: qgsfeature.h:56
Base class for feedback objects to be used for cancellation of something running in a worker thread.
Definition: qgsfeedback.h:45
Container of fields for a vector layer.
Definition: qgsfields.h:45
A geometry engine is a low-level representation of a QgsAbstractGeometry object, optimised for use wi...
A geometry is the spatial representation of a feature.
Definition: qgsgeometry.h:124
A rectangle specified with double values.
Definition: qgsrectangle.h:42
This class contains information about how to simplify geometries fetched from a QgsFeatureIterator.
std::unique_ptr< GEOSGeometry, GeosDeleter > unique_ptr
Scoped GEOS pointer.
Definition: qgsgeos.h:79
#define SIP_DEPRECATED
Definition: qgis_sip.h:106
#define SIP_SKIP
Definition: qgis_sip.h:126
#define SIP_TRANSFERBACK
Definition: qgis_sip.h:48
QSet< QgsFeatureId > QgsFeatureIds
Definition: qgsfeatureid.h:37
qint64 QgsFeatureId
64 bit feature ids negative numbers are used for uncommitted/newly added features
Definition: qgsfeatureid.h:28
QList< int > QgsAttributeList
Definition: qgsfield.h:26
Q_DECLARE_OPERATORS_FOR_FLAGS(QgsField::ConfigurationFlags) CORE_EXPORT QDataStream &operator<<(QDataStream &out
Writes the field to stream out. QGIS version compatibility is not guaranteed.
const QgsCoordinateReferenceSystem & crs