QGIS API Documentation  3.23.0-Master (7c4a6de034)
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 
418  std::shared_ptr< QgsGeometryEngine > referenceGeometryEngine() const SIP_SKIP { return mReferenceGeometryEngine; }
419 
431  double distanceWithin() const { return mDistanceWithin; }
432 
441  QgsFeatureRequest &setFilterFid( QgsFeatureId fid );
442 
449  QgsFeatureId filterFid() const { return mFilterFid; }
450 
459  QgsFeatureRequest &setFilterFids( const QgsFeatureIds &fids );
460 
467  const QgsFeatureIds &filterFids() const { return mFilterFids; }
468 
476  QgsFeatureRequest &setInvalidGeometryCheck( InvalidGeometryCheck check );
477 
483  InvalidGeometryCheck invalidGeometryCheck() const { return mInvalidGeometryFilter; }
484 
492 #ifndef SIP_RUN
493  QgsFeatureRequest &setInvalidGeometryCallback( const std::function< void( const QgsFeature & )> &callback );
494 #else
495  QgsFeatureRequest &setInvalidGeometryCallback( SIP_PYCALLABLE / AllowNone / );
496  % MethodCode
497  Py_BEGIN_ALLOW_THREADS
498 
499  sipCpp->setInvalidGeometryCallback( [a0]( const QgsFeature &arg )
500  {
501  SIP_BLOCK_THREADS
502  Py_XDECREF( sipCallMethod( NULL, a0, "D", &arg, sipType_QgsFeature, NULL ) );
503  SIP_UNBLOCK_THREADS
504  } );
505 
506  sipRes = sipCpp;
507 
508  Py_END_ALLOW_THREADS
509  % End
510 #endif
511 
519  std::function< void( const QgsFeature & ) > invalidGeometryCallback() const { return mInvalidGeometryCallback; } SIP_SKIP
520 
530  QgsFeatureRequest &setFilterExpression( const QString &expression );
531 
537  QgsExpression *filterExpression() const { return mFilterExpression.get(); }
538 
548  QgsFeatureRequest &combineFilterExpression( const QString &expression );
549 
556  QgsExpressionContext *expressionContext() { return &mExpressionContext; }
557 
564  QgsFeatureRequest &setExpressionContext( const QgsExpressionContext &context );
565 
577  QgsFeatureRequest &disableFilter() { mFilter = FilterNone; mFilterExpression.reset(); return *this; }
578 
590  QgsFeatureRequest &addOrderBy( const QString &expression, bool ascending = true );
591 
601  QgsFeatureRequest &addOrderBy( const QString &expression, bool ascending, bool nullsfirst );
602 
608  OrderBy orderBy() const;
609 
615  QgsFeatureRequest &setOrderBy( const OrderBy &orderBy );
616 
623  QgsFeatureRequest &setLimit( long long limit );
624 
630 #ifndef SIP_RUN
631  long long limit() const { return mLimit; }
632 #else
633  long long limit() const;
634 #endif
635 
641  QgsFeatureRequest &setFlags( QgsFeatureRequest::Flags flags );
642 
648  Flags flags() const { return mFlags; }
649 
666  QgsFeatureRequest &setSubsetOfAttributes( const QgsAttributeList &attrs );
667 
683  QgsFeatureRequest &setNoAttributes();
684 
698  QgsAttributeList subsetOfAttributes() const { return mAttrs; }
699 
711  QgsFeatureRequest &setSubsetOfAttributes( const QStringList &attrNames, const QgsFields &fields );
712 
724  QgsFeatureRequest &setSubsetOfAttributes( const QSet<QString> &attrNames, const QgsFields &fields );
725 
732  QgsFeatureRequest &setSimplifyMethod( const QgsSimplifyMethod &simplifyMethod );
733 
740  const QgsSimplifyMethod &simplifyMethod() const { return mSimplifyMethod; }
741 
750  QgsCoordinateReferenceSystem destinationCrs() const;
751 
759  QgsCoordinateTransformContext transformContext() const;
760 
784  QgsFeatureRequest &setDestinationCrs( const QgsCoordinateReferenceSystem &crs, const QgsCoordinateTransformContext &context );
785 
794 #ifndef SIP_RUN
795  QgsFeatureRequest &setTransformErrorCallback( const std::function< void( const QgsFeature & )> &callback );
796 #else
797  QgsFeatureRequest &setTransformErrorCallback( SIP_PYCALLABLE / AllowNone / );
798  % MethodCode
799  Py_BEGIN_ALLOW_THREADS
800 
801  sipCpp->setTransformErrorCallback( [a0]( const QgsFeature &arg )
802  {
803  SIP_BLOCK_THREADS
804  Py_XDECREF( sipCallMethod( NULL, a0, "D", &arg, sipType_QgsFeature, NULL ) );
805  SIP_UNBLOCK_THREADS
806  } );
807 
808  sipRes = sipCpp;
809 
810  Py_END_ALLOW_THREADS
811  % End
812 #endif
813 
822  std::function< void( const QgsFeature & ) > transformErrorCallback() const { return mTransformErrorCallback; } SIP_SKIP
823 
824 
834  bool acceptFeature( const QgsFeature &feature );
835 
845  Q_DECL_DEPRECATED int connectionTimeout() const SIP_DEPRECATED;
846 
856  Q_DECL_DEPRECATED QgsFeatureRequest &setConnectionTimeout( int connectionTimeout ) SIP_DEPRECATED;
857 
867  int timeout() const;
868 
878  QgsFeatureRequest &setTimeout( int timeout );
879 
893  bool requestMayBeNested() const;
894 
908  QgsFeatureRequest &setRequestMayBeNested( bool requestMayBeNested );
909 
921  void setFeedback( QgsFeedback *feedback );
922 
931  QgsFeedback *feedback() const;
932 
933  protected:
934 
938  FilterType mFilter = FilterNone;
939 
945  Qgis::SpatialFilterType mSpatialFilter = Qgis::SpatialFilterType::NoFilter;
946 
950  QgsRectangle mFilterRect;
951 
955  QgsGeometry mReferenceGeometry;
956 
960  std::shared_ptr< QgsGeometryEngine > mReferenceGeometryEngine;
961 
965  double mDistanceWithin = 0;
966 
967  QgsFeatureId mFilterFid = -1;
968  QgsFeatureIds mFilterFids;
969  std::unique_ptr< QgsExpression > mFilterExpression;
970  QgsExpressionContext mExpressionContext;
971  Flags mFlags = Flags();
973  QgsSimplifyMethod mSimplifyMethod;
974  long long mLimit = -1;
975  OrderBy mOrderBy;
976  InvalidGeometryCheck mInvalidGeometryFilter = GeometryNoCheck;
977  std::function< void( const QgsFeature & ) > mInvalidGeometryCallback;
978  std::function< void( const QgsFeature & ) > mTransformErrorCallback;
980  QgsCoordinateTransformContext mTransformContext;
981  int mTimeout = -1;
982  int mRequestMayBeNested = false;
983  QgsFeedback *mFeedback = nullptr;
984 };
985 
987 
988 
989 class QgsFeatureIterator;
991 
997 class CORE_EXPORT QgsAbstractFeatureSource
998 {
999  public:
1000  virtual ~QgsAbstractFeatureSource();
1001 
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 
1012 
1013  // IMPORTANT -- do NOT remove the /TransferBack/ annotation here -- while it looks completely wrong, it's
1014  // required for Python data providers to work correctly! Argh!
1015 
1016  protected:
1017  void iteratorOpened( QgsAbstractFeatureIterator *it );
1018  void iteratorClosed( QgsAbstractFeatureIterator *it );
1019 
1020  QSet< QgsAbstractFeatureIterator * > mActiveIterators;
1021 
1022  template<typename> friend class QgsAbstractFeatureIteratorFromSource;
1023 };
1024 
1025 #endif // QGSFEATUREREQUEST_H
The Qgis class provides global constants for use throughout the application.
Definition: qgis.h:64
SpatialFilterType
Feature request spatial filter types.
Definition: qgis.h:751
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.
std::shared_ptr< QgsGeometryEngine > referenceGeometryEngine() const
Returns the reference geometry engine used for spatial filtering of features.
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:125
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