QGIS API Documentation  3.27.0-Master (0e23467727)
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  bool operator==( const OrderByClause &v ) const
226  {
227  return mExpression == v.mExpression &&
228  mAscending == v.mAscending &&
229  mNullsFirst == v.mNullsFirst;
230  }
231 
232  bool operator!=( const OrderByClause &v ) const
233  {
234  return !( v == *this );
235  }
236 
237  private:
238  QgsExpression mExpression;
239  bool mAscending;
240  bool mNullsFirst;
241  };
242 
243 
251  class OrderBy : public QList<QgsFeatureRequest::OrderByClause>
252  {
253  public:
254 
258  CORE_EXPORT OrderBy();
259 
263  CORE_EXPORT OrderBy( const QList<QgsFeatureRequest::OrderByClause> &other );
264 
271  QList<QgsFeatureRequest::OrderByClause> CORE_EXPORT list() const;
272 
276  void CORE_EXPORT save( QDomElement &elem ) const;
277 
281  void CORE_EXPORT load( const QDomElement &elem );
282 
287  QSet<QString> CORE_EXPORT usedAttributes() const;
288 
293  QSet<int> CORE_EXPORT usedAttributeIndices( const QgsFields &fields ) const;
294 
298  QString CORE_EXPORT dump() const;
299  };
300 
304  static const QString ALL_ATTRIBUTES;
305 
309  explicit QgsFeatureRequest( QgsFeatureId fid );
311  explicit QgsFeatureRequest( const QgsFeatureIds &fids );
312 
320  explicit QgsFeatureRequest( const QgsRectangle &rectangle );
321 
323  explicit QgsFeatureRequest( const QgsExpression &expr, const QgsExpressionContext &context = QgsExpressionContext() );
327  QgsFeatureRequest &operator=( const QgsFeatureRequest &rh );
328 
330 
342  FilterType filterType() const { return mFilter; }
343 
356  Qgis::SpatialFilterType spatialFilterType() const { return mSpatialFilter; }
357 
370  QgsFeatureRequest &setFilterRect( const QgsRectangle &rectangle );
371 
387  QgsRectangle filterRect() const;
388 
404  QgsFeatureRequest &setDistanceWithin( const QgsGeometry &geometry, double distance );
405 
420  QgsGeometry referenceGeometry() const { return mReferenceGeometry; }
421 
430  std::shared_ptr< QgsGeometryEngine > referenceGeometryEngine() const SIP_SKIP { return mReferenceGeometryEngine; }
431 
443  double distanceWithin() const { return mDistanceWithin; }
444 
453  QgsFeatureRequest &setFilterFid( QgsFeatureId fid );
454 
461  QgsFeatureId filterFid() const { return mFilterFid; }
462 
471  QgsFeatureRequest &setFilterFids( const QgsFeatureIds &fids );
472 
479  const QgsFeatureIds &filterFids() const { return mFilterFids; }
480 
488  QgsFeatureRequest &setInvalidGeometryCheck( InvalidGeometryCheck check );
489 
495  InvalidGeometryCheck invalidGeometryCheck() const { return mInvalidGeometryFilter; }
496 
504 #ifndef SIP_RUN
505  QgsFeatureRequest &setInvalidGeometryCallback( const std::function< void( const QgsFeature & )> &callback );
506 #else
507  QgsFeatureRequest &setInvalidGeometryCallback( SIP_PYCALLABLE / AllowNone / );
508  % MethodCode
509  Py_BEGIN_ALLOW_THREADS
510 
511  sipCpp->setInvalidGeometryCallback( [a0]( const QgsFeature &arg )
512  {
513  SIP_BLOCK_THREADS
514  Py_XDECREF( sipCallMethod( NULL, a0, "D", &arg, sipType_QgsFeature, NULL ) );
515  SIP_UNBLOCK_THREADS
516  } );
517 
518  sipRes = sipCpp;
519 
520  Py_END_ALLOW_THREADS
521  % End
522 #endif
523 
531  std::function< void( const QgsFeature & ) > invalidGeometryCallback() const { return mInvalidGeometryCallback; } SIP_SKIP
532 
542  QgsFeatureRequest &setFilterExpression( const QString &expression );
543 
549  QgsExpression *filterExpression() const { return mFilterExpression.get(); }
550 
560  QgsFeatureRequest &combineFilterExpression( const QString &expression );
561 
568  QgsExpressionContext *expressionContext() { return &mExpressionContext; }
569 
576  QgsFeatureRequest &setExpressionContext( const QgsExpressionContext &context );
577 
589  QgsFeatureRequest &disableFilter() { mFilter = FilterNone; mFilterExpression.reset(); return *this; }
590 
602  QgsFeatureRequest &addOrderBy( const QString &expression, bool ascending = true );
603 
613  QgsFeatureRequest &addOrderBy( const QString &expression, bool ascending, bool nullsfirst );
614 
620  OrderBy orderBy() const;
621 
627  QgsFeatureRequest &setOrderBy( const OrderBy &orderBy );
628 
635  QgsFeatureRequest &setLimit( long long limit );
636 
642 #ifndef SIP_RUN
643  long long limit() const { return mLimit; }
644 #else
645  long long limit() const;
646 #endif
647 
653  QgsFeatureRequest &setFlags( QgsFeatureRequest::Flags flags );
654 
660  Flags flags() const { return mFlags; }
661 
678  QgsFeatureRequest &setSubsetOfAttributes( const QgsAttributeList &attrs );
679 
695  QgsFeatureRequest &setNoAttributes();
696 
710  QgsAttributeList subsetOfAttributes() const { return mAttrs; }
711 
723  QgsFeatureRequest &setSubsetOfAttributes( const QStringList &attrNames, const QgsFields &fields );
724 
736  QgsFeatureRequest &setSubsetOfAttributes( const QSet<QString> &attrNames, const QgsFields &fields );
737 
744  QgsFeatureRequest &setSimplifyMethod( const QgsSimplifyMethod &simplifyMethod );
745 
752  const QgsSimplifyMethod &simplifyMethod() const { return mSimplifyMethod; }
753 
762  QgsCoordinateReferenceSystem destinationCrs() const;
763 
771  QgsCoordinateTransformContext transformContext() const;
772 
796  QgsFeatureRequest &setDestinationCrs( const QgsCoordinateReferenceSystem &crs, const QgsCoordinateTransformContext &context );
797 
806 #ifndef SIP_RUN
807  QgsFeatureRequest &setTransformErrorCallback( const std::function< void( const QgsFeature & )> &callback );
808 #else
809  QgsFeatureRequest &setTransformErrorCallback( SIP_PYCALLABLE / AllowNone / );
810  % MethodCode
811  Py_BEGIN_ALLOW_THREADS
812 
813  sipCpp->setTransformErrorCallback( [a0]( const QgsFeature &arg )
814  {
815  SIP_BLOCK_THREADS
816  Py_XDECREF( sipCallMethod( NULL, a0, "D", &arg, sipType_QgsFeature, NULL ) );
817  SIP_UNBLOCK_THREADS
818  } );
819 
820  sipRes = sipCpp;
821 
822  Py_END_ALLOW_THREADS
823  % End
824 #endif
825 
834  std::function< void( const QgsFeature & ) > transformErrorCallback() const { return mTransformErrorCallback; } SIP_SKIP
835 
836 
846  bool acceptFeature( const QgsFeature &feature );
847 
857  Q_DECL_DEPRECATED int connectionTimeout() const SIP_DEPRECATED;
858 
868  Q_DECL_DEPRECATED QgsFeatureRequest &setConnectionTimeout( int connectionTimeout ) SIP_DEPRECATED;
869 
879  int timeout() const;
880 
890  QgsFeatureRequest &setTimeout( int timeout );
891 
905  bool requestMayBeNested() const;
906 
920  QgsFeatureRequest &setRequestMayBeNested( bool requestMayBeNested );
921 
933  void setFeedback( QgsFeedback *feedback );
934 
943  QgsFeedback *feedback() const;
944 
945  protected:
946 
950  FilterType mFilter = FilterNone;
951 
957  Qgis::SpatialFilterType mSpatialFilter = Qgis::SpatialFilterType::NoFilter;
958 
962  QgsRectangle mFilterRect;
963 
967  QgsGeometry mReferenceGeometry;
968 
972  std::shared_ptr< QgsGeometryEngine > mReferenceGeometryEngine;
973 
977  double mDistanceWithin = 0;
978 
979  QgsFeatureId mFilterFid = -1;
980  QgsFeatureIds mFilterFids;
981  std::unique_ptr< QgsExpression > mFilterExpression;
982  QgsExpressionContext mExpressionContext;
983  Flags mFlags = Flags();
985  QgsSimplifyMethod mSimplifyMethod;
986  long long mLimit = -1;
987  OrderBy mOrderBy;
988  InvalidGeometryCheck mInvalidGeometryFilter = GeometryNoCheck;
989  std::function< void( const QgsFeature & ) > mInvalidGeometryCallback;
990  std::function< void( const QgsFeature & ) > mTransformErrorCallback;
992  QgsCoordinateTransformContext mTransformContext;
993  int mTimeout = -1;
994  int mRequestMayBeNested = false;
995  QgsFeedback *mFeedback = nullptr;
996 };
997 
999 
1000 
1001 class QgsFeatureIterator;
1003 
1009 class CORE_EXPORT QgsAbstractFeatureSource
1010 {
1011  public:
1012  virtual ~QgsAbstractFeatureSource();
1013 
1014 
1015  // IMPORTANT -- do NOT remove the /TransferBack/ annotation here -- while it looks completely wrong, it's
1016  // required for Python data providers to work correctly! Argh!
1017 
1024 
1025  // IMPORTANT -- do NOT remove the /TransferBack/ annotation here -- while it looks completely wrong, it's
1026  // required for Python data providers to work correctly! Argh!
1027 
1028  protected:
1029  void iteratorOpened( QgsAbstractFeatureIterator *it );
1030  void iteratorClosed( QgsAbstractFeatureIterator *it );
1031 
1032  QSet< QgsAbstractFeatureIterator * > mActiveIterators;
1033 
1034  template<typename> friend class QgsAbstractFeatureIteratorFromSource;
1035 };
1036 
1037 #endif // QGSFEATUREREQUEST_H
The Qgis class provides global constants for use throughout the application.
Definition: qgis.h:72
SpatialFilterType
Feature request spatial filter types.
Definition: qgis.h:993
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.
bool operator==(const OrderByClause &v) const
bool operator!=(const OrderByClause &v) const
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