QGIS API Documentation  3.37.0-Master (a5b4d9743e8)
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 
109  class CORE_EXPORT OrderByClause
110  {
111  public:
112 
121  OrderByClause( const QString &expression, bool ascending = true );
122 
130  OrderByClause( const QString &expression, bool ascending, bool nullsfirst );
131 
140  OrderByClause( const QgsExpression &expression, bool ascending = true );
141 
149  OrderByClause( const QgsExpression &expression, bool ascending, bool nullsfirst );
150 
155  QgsExpression expression() const;
156 
163  bool prepare( QgsExpressionContext *context );
164 
169  bool ascending() const;
170 
174  void setAscending( bool ascending );
175 
180  bool nullsFirst() const;
181 
185  void setNullsFirst( bool nullsFirst );
186 
190  QString dump() const;
191 
192  // friend inline int qHash(const OrderByClause &a) { return qHash(a.mExpression.expression()) ^ qHash(a.mAscending) ^ qHash( a.mNullsFirst); }
193 
194  bool operator==( const OrderByClause &v ) const
195  {
196  return mExpression == v.mExpression &&
197  mAscending == v.mAscending &&
198  mNullsFirst == v.mNullsFirst;
199  }
200 
201  bool operator!=( const OrderByClause &v ) const
202  {
203  return !( v == *this );
204  }
205 
206  private:
207  QgsExpression mExpression;
208  bool mAscending;
209  bool mNullsFirst;
210  };
211 
212 
219  class OrderBy : public QList<QgsFeatureRequest::OrderByClause>
220  {
221  public:
222 
226  CORE_EXPORT OrderBy();
227 
231  CORE_EXPORT OrderBy( const QList<QgsFeatureRequest::OrderByClause> &other );
232 
239  QList<QgsFeatureRequest::OrderByClause> CORE_EXPORT list() const;
240 
244  void CORE_EXPORT save( QDomElement &elem ) const;
245 
249  void CORE_EXPORT load( const QDomElement &elem );
250 
255  QSet<QString> CORE_EXPORT usedAttributes() const;
256 
261  QSet<int> CORE_EXPORT usedAttributeIndices( const QgsFields &fields ) const;
262 
266  QString CORE_EXPORT dump() const;
267  };
268 
272  static const QString ALL_ATTRIBUTES;
273 
277  explicit QgsFeatureRequest( QgsFeatureId fid );
279  explicit QgsFeatureRequest( const QgsFeatureIds &fids );
280 
288  explicit QgsFeatureRequest( const QgsRectangle &rectangle );
289 
291  explicit QgsFeatureRequest( const QgsExpression &expr, const QgsExpressionContext &context = QgsExpressionContext() );
295  QgsFeatureRequest &operator=( const QgsFeatureRequest &rh );
296 
298 
310  Qgis::FeatureRequestFilterType filterType() const { return mFilter; }
311 
324  Qgis::SpatialFilterType spatialFilterType() const { return mSpatialFilter; }
325 
338  QgsFeatureRequest &setFilterRect( const QgsRectangle &rectangle );
339 
355  QgsRectangle filterRect() const;
356 
372  QgsFeatureRequest &setDistanceWithin( const QgsGeometry &geometry, double distance );
373 
388  QgsGeometry referenceGeometry() const { return mReferenceGeometry; }
389 
398  std::shared_ptr< QgsGeometryEngine > referenceGeometryEngine() const SIP_SKIP { return mReferenceGeometryEngine; }
399 
411  double distanceWithin() const { return mDistanceWithin; }
412 
421  QgsFeatureRequest &setFilterFid( QgsFeatureId fid );
422 
429  QgsFeatureId filterFid() const { return mFilterFid; }
430 
439  QgsFeatureRequest &setFilterFids( const QgsFeatureIds &fids );
440 
447  const QgsFeatureIds &filterFids() const { return mFilterFids; }
448 
455  QgsFeatureRequest &setInvalidGeometryCheck( Qgis::InvalidGeometryCheck check );
456 
461  Qgis::InvalidGeometryCheck invalidGeometryCheck() const { return mInvalidGeometryFilter; }
462 
469 #ifndef SIP_RUN
470  QgsFeatureRequest &setInvalidGeometryCallback( const std::function< void( const QgsFeature & )> &callback );
471 #else
472  QgsFeatureRequest &setInvalidGeometryCallback( SIP_PYCALLABLE / AllowNone / );
473  % MethodCode
474  Py_BEGIN_ALLOW_THREADS
475 
476  sipCpp->setInvalidGeometryCallback( [a0]( const QgsFeature &arg )
477  {
478  SIP_BLOCK_THREADS
479  Py_XDECREF( sipCallMethod( NULL, a0, "D", &arg, sipType_QgsFeature, NULL ) );
480  SIP_UNBLOCK_THREADS
481  } );
482 
483  sipRes = sipCpp;
484 
485  Py_END_ALLOW_THREADS
486  % End
487 #endif
488 
495  std::function< void( const QgsFeature & ) > invalidGeometryCallback() const { return mInvalidGeometryCallback; } SIP_SKIP
496 
506  QgsFeatureRequest &setFilterExpression( const QString &expression );
507 
513  QgsExpression *filterExpression() const { return mFilterExpression.get(); }
514 
523  QgsFeatureRequest &combineFilterExpression( const QString &expression );
524 
530  QgsExpressionContext *expressionContext() { return &mExpressionContext; }
531 
537  QgsFeatureRequest &setExpressionContext( const QgsExpressionContext &context );
538 
549  QgsFeatureRequest &disableFilter() { mFilter = Qgis::FeatureRequestFilterType::NoFilter; mFilterExpression.reset(); return *this; }
550 
561  QgsFeatureRequest &addOrderBy( const QString &expression, bool ascending = true );
562 
571  QgsFeatureRequest &addOrderBy( const QString &expression, bool ascending, bool nullsfirst );
572 
577  OrderBy orderBy() const;
578 
583  QgsFeatureRequest &setOrderBy( const OrderBy &orderBy );
584 
590  QgsFeatureRequest &setLimit( long long limit );
591 
596 #ifndef SIP_RUN
597  long long limit() const { return mLimit; }
598 #else
599  long long limit() const;
600 #endif
601 
607  QgsFeatureRequest &setFlags( Qgis::FeatureRequestFlags flags );
608 
614  Qgis::FeatureRequestFlags flags() const { return mFlags; }
615 
632  QgsFeatureRequest &setSubsetOfAttributes( const QgsAttributeList &attrs );
633 
649  QgsFeatureRequest &setNoAttributes();
650 
664  QgsAttributeList subsetOfAttributes() const { return mAttrs; }
665 
677  QgsFeatureRequest &setSubsetOfAttributes( const QStringList &attrNames, const QgsFields &fields );
678 
690  QgsFeatureRequest &setSubsetOfAttributes( const QSet<QString> &attrNames, const QgsFields &fields );
691 
697  QgsFeatureRequest &setSimplifyMethod( const QgsSimplifyMethod &simplifyMethod );
698 
704  const QgsSimplifyMethod &simplifyMethod() const { return mSimplifyMethod; }
705 
713  QgsCoordinateReferenceSystem destinationCrs() const;
714 
721  QgsCoordinateTransformContext transformContext() const;
722 
745  QgsFeatureRequest &setDestinationCrs( const QgsCoordinateReferenceSystem &crs, const QgsCoordinateTransformContext &context );
746 
754 #ifndef SIP_RUN
755  QgsFeatureRequest &setTransformErrorCallback( const std::function< void( const QgsFeature & )> &callback );
756 #else
757  QgsFeatureRequest &setTransformErrorCallback( SIP_PYCALLABLE / AllowNone / );
758  % MethodCode
759  Py_BEGIN_ALLOW_THREADS
760 
761  sipCpp->setTransformErrorCallback( [a0]( const QgsFeature &arg )
762  {
763  SIP_BLOCK_THREADS
764  Py_XDECREF( sipCallMethod( NULL, a0, "D", &arg, sipType_QgsFeature, NULL ) );
765  SIP_UNBLOCK_THREADS
766  } );
767 
768  sipRes = sipCpp;
769 
770  Py_END_ALLOW_THREADS
771  % End
772 #endif
773 
781  std::function< void( const QgsFeature & ) > transformErrorCallback() const { return mTransformErrorCallback; } SIP_SKIP
782 
783 
792  bool acceptFeature( const QgsFeature &feature );
793 
802  Q_DECL_DEPRECATED int connectionTimeout() const SIP_DEPRECATED;
803 
812  Q_DECL_DEPRECATED QgsFeatureRequest &setConnectionTimeout( int connectionTimeout ) SIP_DEPRECATED;
813 
823  int timeout() const;
824 
834  QgsFeatureRequest &setTimeout( int timeout );
835 
849  bool requestMayBeNested() const;
850 
864  QgsFeatureRequest &setRequestMayBeNested( bool requestMayBeNested );
865 
877  void setFeedback( QgsFeedback *feedback );
878 
887  QgsFeedback *feedback() const;
888 
889  protected:
890 
894  Qgis::FeatureRequestFilterType mFilter = Qgis::FeatureRequestFilterType::NoFilter;
895 
901  Qgis::SpatialFilterType mSpatialFilter = Qgis::SpatialFilterType::NoFilter;
902 
906  QgsRectangle mFilterRect;
907 
911  QgsGeometry mReferenceGeometry;
912 
916  std::shared_ptr< QgsGeometryEngine > mReferenceGeometryEngine;
917 
921  double mDistanceWithin = 0;
922 
923  QgsFeatureId mFilterFid = -1;
924  QgsFeatureIds mFilterFids;
925  std::unique_ptr< QgsExpression > mFilterExpression;
926  QgsExpressionContext mExpressionContext;
927  Qgis::FeatureRequestFlags mFlags;
929  QgsSimplifyMethod mSimplifyMethod;
930  long long mLimit = -1;
931  OrderBy mOrderBy;
932  Qgis::InvalidGeometryCheck mInvalidGeometryFilter = Qgis::InvalidGeometryCheck::NoCheck;
933  std::function< void( const QgsFeature & ) > mInvalidGeometryCallback;
934  std::function< void( const QgsFeature & ) > mTransformErrorCallback;
936  QgsCoordinateTransformContext mTransformContext;
937  int mTimeout = -1;
938  int mRequestMayBeNested = false;
939  QgsFeedback *mFeedback = nullptr;
940 };
941 
942 
943 class QgsFeatureIterator;
945 
950 class CORE_EXPORT QgsAbstractFeatureSource
951 {
952  public:
953  virtual ~QgsAbstractFeatureSource();
954 
955 
956  // IMPORTANT -- do NOT remove the /TransferBack/ annotation here -- while it looks completely wrong, it's
957  // required for Python data providers to work correctly! Argh!
958 
965 
966  // IMPORTANT -- do NOT remove the /TransferBack/ annotation here -- while it looks completely wrong, it's
967  // required for Python data providers to work correctly! Argh!
968 
969  protected:
970  void iteratorOpened( QgsAbstractFeatureIterator *it );
971  void iteratorClosed( QgsAbstractFeatureIterator *it );
972 
973  QSet< QgsAbstractFeatureIterator * > mActiveIterators;
974 
975  template<typename> friend class QgsAbstractFeatureIteratorFromSource;
976 };
977 
978 #endif // QGSFEATUREREQUEST_H
The Qgis class provides global constants for use throughout the application.
Definition: qgis.h:54
FeatureRequestFilterType
Types of feature request filters.
Definition: qgis.h:1743
@ NoFilter
No filter is applied.
SpatialFilterType
Feature request spatial filter types.
Definition: qgis.h:1772
QFlags< FeatureRequestFlag > FeatureRequestFlags
Flags for controlling feature requests.
Definition: qgis.h:1732
InvalidGeometryCheck
Methods for handling of features with invalid geometries.
Definition: qgis.h:1759
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.
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.
Qgis::FeatureRequestFilterType filterType() const
Returns the attribute/ID filter type which is currently set on this request.
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.
Qgis::FeatureRequestFlags 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.
Qgis::InvalidGeometryCheck invalidGeometryCheck() const
Returns the invalid geometry checking behavior.
const QgsFeatureIds & filterFids() const
Returns the feature IDs that should be fetched.
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:44
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:162
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:73
#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:27
const QgsCoordinateReferenceSystem & crs