QGIS API Documentation
3.0.2-Girona (307d082)
|
This class wraps a request for features to a vector layer (or directly its vector data provider). More...
#include <qgsfeaturerequest.h>
Classes | |
class | OrderBy |
Represents a list of OrderByClauses, with the most important first and the least important last. More... | |
class | OrderByClause |
The OrderByClause class represents an order by clause for a QgsFeatureRequest. More... | |
Public Types | |
enum | FilterType { FilterNone, FilterFid, FilterExpression, FilterFids } |
Types of filters. More... | |
enum | Flag { NoFlags = 0, NoGeometry = 1, SubsetOfAttributes = 2, ExactIntersect = 4 } |
enum | InvalidGeometryCheck { GeometryNoCheck = 0, GeometrySkipInvalid = 1, GeometryAbortOnInvalid = 2 } |
Handling of features with invalid geometries. More... | |
Public Member Functions | |
QgsFeatureRequest () | |
construct a default request: for all features get attributes and geometries More... | |
QgsFeatureRequest (QgsFeatureId fid) | |
construct a request with feature ID filter More... | |
QgsFeatureRequest (const QgsFeatureIds &fids) | |
construct a request with feature ID filter More... | |
QgsFeatureRequest (const QgsRectangle &rectangle) | |
Construct a request with rectangle bounding box filter. More... | |
QgsFeatureRequest (const QgsExpression &expr, const QgsExpressionContext &context=QgsExpressionContext()) | |
construct a request with a filter expression More... | |
QgsFeatureRequest (const QgsFeatureRequest &rh) | |
copy constructor More... | |
bool | acceptFeature (const QgsFeature &feature) |
Check if a feature is accepted by this requests filter. More... | |
QgsFeatureRequest & | addOrderBy (const QString &expression, bool ascending=true) |
Adds a new OrderByClause, appending it as the least important one. More... | |
QgsFeatureRequest & | addOrderBy (const QString &expression, bool ascending, bool nullsfirst) |
Adds a new OrderByClause, appending it as the least important one. More... | |
QgsFeatureRequest & | combineFilterExpression (const QString &expression) |
Modifies the existing filter expression to add an additional expression filter. More... | |
int | connectionTimeout () const |
The timeout for how long we should wait for a connection if none is available from the pool at this moment. More... | |
QgsCoordinateReferenceSystem | destinationCrs () const |
Returns the destination coordinate reference system for feature's geometries, or an invalid QgsCoordinateReferenceSystem if no reprojection will be done and all features will be left with their original geometry. More... | |
QgsFeatureRequest & | disableFilter () |
Disables filter conditions. More... | |
QgsExpressionContext * | expressionContext () |
Returns the expression context used to evaluate filter expressions. More... | |
QgsExpression * | filterExpression () const |
Returns the filter expression if set. More... | |
QgsFeatureId | filterFid () const |
Get the feature ID that should be fetched. More... | |
const QgsFeatureIds & | filterFids () const |
Get feature IDs that should be fetched. More... | |
const QgsRectangle & | filterRect () const |
Returns the rectangle from which features will be taken. More... | |
FilterType | filterType () const |
Return the filter type which is currently set on this request. More... | |
const Flags & | flags () const |
std::function< void(const QgsFeature &) > | invalidGeometryCallback () const |
Returns the callback function to use when encountering an invalid geometry and invalidGeometryCheck() is set to GeometryAbortOnInvalid or GeometrySkipInvalid. More... | |
InvalidGeometryCheck | invalidGeometryCheck () const |
Returns the invalid geometry checking behavior. More... | |
long | limit () const |
Returns the maximum number of features to request, or -1 if no limit set. More... | |
QgsFeatureRequest & | operator= (const QgsFeatureRequest &rh) |
Assignment operator. More... | |
OrderBy | orderBy () const |
Return a list of order by clauses specified for this feature request. More... | |
void | setConnectionTimeout (int connectionTimeout) |
The timeout for how long we should wait for a connection if none is available from the pool at this moment. More... | |
QgsFeatureRequest & | setDestinationCrs (const QgsCoordinateReferenceSystem &crs, const QgsCoordinateTransformContext &context) |
Sets the destination crs for feature's geometries. More... | |
QgsFeatureRequest & | setExpressionContext (const QgsExpressionContext &context) |
Sets the expression context used to evaluate filter expressions. More... | |
QgsFeatureRequest & | setFilterExpression (const QString &expression) |
Set the filter expression. More... | |
QgsFeatureRequest & | setFilterFid (QgsFeatureId fid) |
Set feature ID that should be fetched. More... | |
QgsFeatureRequest & | setFilterFids (const QgsFeatureIds &fids) |
Set feature IDs that should be fetched. More... | |
QgsFeatureRequest & | setFilterRect (const QgsRectangle &rectangle) |
Sets the rectangle from which features will be taken. More... | |
QgsFeatureRequest & | setFlags (QgsFeatureRequest::Flags flags) |
Set flags that affect how features will be fetched. More... | |
QgsFeatureRequest & | setInvalidGeometryCallback (const std::function< void(const QgsFeature &)> &callback) |
Sets a callback function to use when encountering an invalid geometry and invalidGeometryCheck() is set to GeometryAbortOnInvalid or GeometrySkipInvalid. More... | |
QgsFeatureRequest & | setInvalidGeometryCheck (InvalidGeometryCheck check) |
Sets invalid geometry checking behavior. More... | |
QgsFeatureRequest & | setLimit (long limit) |
Set the maximum number of features to request. More... | |
QgsFeatureRequest & | setOrderBy (const OrderBy &orderBy) |
Set a list of order by clauses. More... | |
QgsFeatureRequest & | setSimplifyMethod (const QgsSimplifyMethod &simplifyMethod) |
Set a simplification method for geometries that will be fetched. More... | |
QgsFeatureRequest & | setSubsetOfAttributes (const QgsAttributeList &attrs) |
Set a subset of attributes that will be fetched. More... | |
QgsFeatureRequest & | setSubsetOfAttributes (const QStringList &attrNames, const QgsFields &fields) |
Set a subset of attributes by names that will be fetched. More... | |
QgsFeatureRequest & | setSubsetOfAttributes (const QSet< QString > &attrNames, const QgsFields &fields) |
Set a subset of attributes by names that will be fetched. More... | |
QgsFeatureRequest & | setTransformErrorCallback (const std::function< void(const QgsFeature &)> &callback) |
Sets a callback function to use when encountering a transform error when iterating features and a destinationCrs() is set. More... | |
const QgsSimplifyMethod & | simplifyMethod () const |
Get simplification method for geometries that will be fetched. More... | |
QgsAttributeList | subsetOfAttributes () const |
Return the subset of attributes which at least need to be fetched. More... | |
QgsCoordinateTransformContext | transformContext () const |
Returns the transform context, for use when a destinationCrs() has been set and reprojection is required. More... | |
std::function< void(const QgsFeature &) > | transformErrorCallback () const |
Returns the callback function to use when encountering a transform error when iterating features and a destinationCrs() is set. More... | |
Static Public Attributes | |
static const QString | ALL_ATTRIBUTES = QStringLiteral( "#!allattributes!#" ) |
A special attribute that if set matches all attributes. More... | |
Protected Attributes | |
QgsAttributeList | mAttrs |
int | mConnectionTimeout = -1 |
QgsCoordinateReferenceSystem | mCrs |
QgsExpressionContext | mExpressionContext |
FilterType | mFilter = FilterNone |
std::unique_ptr< QgsExpression > | mFilterExpression |
QgsFeatureId | mFilterFid = -1 |
QgsFeatureIds | mFilterFids |
QgsRectangle | mFilterRect |
Flags | mFlags |
std::function< void(const QgsFeature &) > | mInvalidGeometryCallback |
InvalidGeometryCheck | mInvalidGeometryFilter = GeometryNoCheck |
long | mLimit = -1 |
OrderBy | mOrderBy |
QgsSimplifyMethod | mSimplifyMethod |
QgsCoordinateTransformContext | mTransformContext |
std::function< void(const QgsFeature &) > | mTransformErrorCallback |
This class wraps a request for features to a vector layer (or directly its vector data provider).
The request may apply a filter to fetch only a particular subset of features. Currently supported filters:
Additionally a spatial rectangle can be set in combination: Only features that intersect given rectangle should be fetched. For the sake of speed, the intersection is often done only using feature's bounding box. There is a flag ExactIntersect that makes sure that only intersecting features will be returned.
For efficiency, it is also possible to tell provider that some data is not required:
The options may be chained, e.g.: QgsFeatureRequest().setFilterRect(QgsRectangle(0,0,1,1)).setFlags(QgsFeatureRequest::ExactIntersect)
Examples:
Definition at line 67 of file qgsfeaturerequest.h.
Types of filters.
Enumerator | |
---|---|
FilterNone | No filter is applied. |
FilterFid | Filter using feature ID. |
FilterExpression | Filter using expression. |
FilterFids | Filter using feature IDs. |
Definition at line 82 of file qgsfeaturerequest.h.
Definition at line 70 of file qgsfeaturerequest.h.
Handling of features with invalid geometries.
Definition at line 91 of file qgsfeaturerequest.h.
QgsFeatureRequest::QgsFeatureRequest | ( | ) |
construct a default request: for all features get attributes and geometries
Definition at line 25 of file qgsfeaturerequest.cpp.
|
explicit |
construct a request with feature ID filter
Definition at line 30 of file qgsfeaturerequest.cpp.
|
explicit |
construct a request with feature ID filter
Definition at line 37 of file qgsfeaturerequest.cpp.
|
explicit |
Construct a request with rectangle bounding box filter.
When a destination CRS is set using setDestinationCrs(), rectangle is expected to be in the same CRS as the destinationCrs(). Otherwise, rectangle should use the same CRS as the source layer/provider.
Definition at line 45 of file qgsfeaturerequest.cpp.
|
explicit |
construct a request with a filter expression
Definition at line 51 of file qgsfeaturerequest.cpp.
QgsFeatureRequest::QgsFeatureRequest | ( | const QgsFeatureRequest & | rh | ) |
copy constructor
Definition at line 59 of file qgsfeaturerequest.cpp.
bool QgsFeatureRequest::acceptFeature | ( | const QgsFeature & | feature | ) |
Check if a feature is accepted by this requests filter.
feature | The feature which will be tested |
Definition at line 264 of file qgsfeaturerequest.cpp.
QgsFeatureRequest & QgsFeatureRequest::addOrderBy | ( | const QString & | expression, |
bool | ascending = true |
||
) |
Adds a new OrderByClause, appending it as the least important one.
expression | The expression to use for ordering |
ascending | If the order should be ascending (1,2,3) or descending (3,2,1) If the order is ascending, by default nulls are last If the order is descending, by default nulls are first |
Definition at line 150 of file qgsfeaturerequest.cpp.
QgsFeatureRequest & QgsFeatureRequest::addOrderBy | ( | const QString & | expression, |
bool | ascending, | ||
bool | nullsfirst | ||
) |
Adds a new OrderByClause, appending it as the least important one.
expression | The expression to use for ordering |
ascending | If the order should be ascending (1,2,3) or descending (3,2,1) |
nullsfirst | If true, NULLS are at the beginning, if false, NULLS are at the end |
Definition at line 156 of file qgsfeaturerequest.cpp.
QgsFeatureRequest & QgsFeatureRequest::combineFilterExpression | ( | const QString & | expression | ) |
Modifies the existing filter expression to add an additional expression filter.
The filter expressions are combined using AND, so only features matching both the existing expression and the additional expression will be returned.
Definition at line 131 of file qgsfeaturerequest.cpp.
int QgsFeatureRequest::connectionTimeout | ( | ) | const |
The timeout for how long we should wait for a connection if none is available from the pool at this moment.
A negative value (which is set by default) will wait forever.
Definition at line 291 of file qgsfeaturerequest.cpp.
QgsCoordinateReferenceSystem QgsFeatureRequest::destinationCrs | ( | ) | const |
Returns the destination coordinate reference system for feature's geometries, or an invalid QgsCoordinateReferenceSystem if no reprojection will be done and all features will be left with their original geometry.
Definition at line 241 of file qgsfeaturerequest.cpp.
|
inline |
Disables filter conditions.
The spatial filter (filterRect) will be kept in place.
Definition at line 431 of file qgsfeaturerequest.h.
|
inline |
Returns the expression context used to evaluate filter expressions.
Definition at line 413 of file qgsfeaturerequest.h.
|
inline |
Returns the filter expression if set.
Definition at line 397 of file qgsfeaturerequest.h.
|
inline |
Get the feature ID that should be fetched.
Definition at line 325 of file qgsfeaturerequest.h.
|
inline |
Get feature IDs that should be fetched.
Definition at line 330 of file qgsfeaturerequest.h.
|
inline |
Returns the rectangle from which features will be taken.
If the returned rectangle is null, then no filter rectangle is set.
When a destination CRS is set using setDestinationCrs(), the rectangle will be in the same CRS as the destinationCrs(). Otherwise, the rectangle will use the same CRS as the source layer/provider.
Definition at line 320 of file qgsfeaturerequest.h.
|
inline |
Return the filter type which is currently set on this request.
Definition at line 297 of file qgsfeaturerequest.h.
|
inline |
Definition at line 488 of file qgsfeaturerequest.h.
|
inline |
Returns the callback function to use when encountering an invalid geometry and invalidGeometryCheck() is set to GeometryAbortOnInvalid or GeometrySkipInvalid.
Definition at line 382 of file qgsfeaturerequest.h.
|
inline |
Returns the invalid geometry checking behavior.
Definition at line 346 of file qgsfeaturerequest.h.
|
inline |
Returns the maximum number of features to request, or -1 if no limit set.
Definition at line 484 of file qgsfeaturerequest.h.
QgsFeatureRequest & QgsFeatureRequest::operator= | ( | const QgsFeatureRequest & | rh | ) |
Assignment operator.
Definition at line 64 of file qgsfeaturerequest.cpp.
QgsFeatureRequest::OrderBy QgsFeatureRequest::orderBy | ( | ) | const |
Return a list of order by clauses specified for this feature request.
Definition at line 162 of file qgsfeaturerequest.cpp.
void QgsFeatureRequest::setConnectionTimeout | ( | int | connectionTimeout | ) |
The timeout for how long we should wait for a connection if none is available from the pool at this moment.
A negative value (which is set by default) will wait forever.
Definition at line 296 of file qgsfeaturerequest.cpp.
QgsFeatureRequest & QgsFeatureRequest::setDestinationCrs | ( | const QgsCoordinateReferenceSystem & | crs, |
const QgsCoordinateTransformContext & | context | ||
) |
Sets the destination crs for feature's geometries.
If set, all geometries will be reprojected from their original coordinate reference system to this desired reference system. If crs is an invalid QgsCoordinateReferenceSystem then no reprojection will be done and all features will be left with their original geometry.
When a crs is set using setDestinationCrs(), then any filterRect() set on the request is expected to be in the same CRS as the destination CRS.
The feature geometry transformation to the destination CRS is performed after all filter expressions are tested and any virtual fields are calculated. Accordingly, any geometric expressions used in filterExpression() will be performed in the original source CRS. This ensures consistent results are returned regardless of the destination CRS. Similarly, virtual field values will be calculated using the original geometry in the source CRS, so these values are not affected by any destination CRS transform present in the feature request.
Definition at line 251 of file qgsfeaturerequest.cpp.
QgsFeatureRequest & QgsFeatureRequest::setExpressionContext | ( | const QgsExpressionContext & | context | ) |
Sets the expression context used to evaluate filter expressions.
Definition at line 144 of file qgsfeaturerequest.cpp.
QgsFeatureRequest & QgsFeatureRequest::setFilterExpression | ( | const QString & | expression | ) |
Set the filter expression.
{
expression | expression string |
Definition at line 124 of file qgsfeaturerequest.cpp.
QgsFeatureRequest & QgsFeatureRequest::setFilterFid | ( | QgsFeatureId | fid | ) |
Set feature ID that should be fetched.
Definition at line 98 of file qgsfeaturerequest.cpp.
QgsFeatureRequest & QgsFeatureRequest::setFilterFids | ( | const QgsFeatureIds & | fids | ) |
Set feature IDs that should be fetched.
Definition at line 105 of file qgsfeaturerequest.cpp.
QgsFeatureRequest & QgsFeatureRequest::setFilterRect | ( | const QgsRectangle & | rectangle | ) |
Sets the rectangle from which features will be taken.
An empty rectangle removes the filter.
When a destination CRS is set using setDestinationCrs(), rectangle is expected to be in the same CRS as the destinationCrs(). Otherwise, rectangle should use the same CRS as the source layer/provider.
Definition at line 92 of file qgsfeaturerequest.cpp.
QgsFeatureRequest & QgsFeatureRequest::setFlags | ( | QgsFeatureRequest::Flags | flags | ) |
Set flags that affect how features will be fetched.
Definition at line 179 of file qgsfeaturerequest.cpp.
QgsFeatureRequest & QgsFeatureRequest::setInvalidGeometryCallback | ( | const std::function< void(const QgsFeature &)> & | callback | ) |
Sets a callback function to use when encountering an invalid geometry and invalidGeometryCheck() is set to GeometryAbortOnInvalid or GeometrySkipInvalid.
This function will be called using the feature with invalid geometry as a parameter.
Definition at line 118 of file qgsfeaturerequest.cpp.
QgsFeatureRequest & QgsFeatureRequest::setInvalidGeometryCheck | ( | QgsFeatureRequest::InvalidGeometryCheck | check | ) |
Sets invalid geometry checking behavior.
Definition at line 112 of file qgsfeaturerequest.cpp.
QgsFeatureRequest & QgsFeatureRequest::setLimit | ( | long | limit | ) |
Set the maximum number of features to request.
limit | maximum number of features, or -1 to request all features. |
Definition at line 173 of file qgsfeaturerequest.cpp.
QgsFeatureRequest & QgsFeatureRequest::setOrderBy | ( | const OrderBy & | orderBy | ) |
Set a list of order by clauses.
Definition at line 167 of file qgsfeaturerequest.cpp.
QgsFeatureRequest & QgsFeatureRequest::setSimplifyMethod | ( | const QgsSimplifyMethod & | simplifyMethod | ) |
Set a simplification method for geometries that will be fetched.
Definition at line 234 of file qgsfeaturerequest.cpp.
QgsFeatureRequest & QgsFeatureRequest::setSubsetOfAttributes | ( | const QgsAttributeList & | attrs | ) |
Set a subset of attributes that will be fetched.
Empty list means that all attributes are used. To disable fetching attributes, reset the FetchAttributes flag (which is set by default)
Definition at line 185 of file qgsfeaturerequest.cpp.
QgsFeatureRequest & QgsFeatureRequest::setSubsetOfAttributes | ( | const QStringList & | attrNames, |
const QgsFields & | fields | ||
) |
Set a subset of attributes by names that will be fetched.
Definition at line 192 of file qgsfeaturerequest.cpp.
QgsFeatureRequest & QgsFeatureRequest::setSubsetOfAttributes | ( | const QSet< QString > & | attrNames, |
const QgsFields & | fields | ||
) |
Set a subset of attributes by names that will be fetched.
Definition at line 213 of file qgsfeaturerequest.cpp.
QgsFeatureRequest & QgsFeatureRequest::setTransformErrorCallback | ( | const std::function< void(const QgsFeature &)> & | callback | ) |
Sets a callback function to use when encountering a transform error when iterating features and a destinationCrs() is set.
This function will be called using the feature which encountered the transform error as a parameter.
Definition at line 258 of file qgsfeaturerequest.cpp.
|
inline |
Get simplification method for geometries that will be fetched.
Definition at line 518 of file qgsfeaturerequest.h.
|
inline |
Return the subset of attributes which at least need to be fetched.
Definition at line 500 of file qgsfeaturerequest.h.
QgsCoordinateTransformContext QgsFeatureRequest::transformContext | ( | ) | const |
Returns the transform context, for use when a destinationCrs() has been set and reprojection is required.
Definition at line 246 of file qgsfeaturerequest.cpp.
|
inline |
Returns the callback function to use when encountering a transform error when iterating features and a destinationCrs() is set.
Definition at line 600 of file qgsfeaturerequest.h.
|
static |
A special attribute that if set matches all attributes.
Definition at line 267 of file qgsfeaturerequest.h.
|
protected |
Definition at line 642 of file qgsfeaturerequest.h.
|
protected |
Definition at line 651 of file qgsfeaturerequest.h.
|
protected |
Definition at line 649 of file qgsfeaturerequest.h.
|
protected |
Definition at line 640 of file qgsfeaturerequest.h.
|
protected |
Definition at line 635 of file qgsfeaturerequest.h.
|
protected |
Definition at line 639 of file qgsfeaturerequest.h.
|
protected |
Definition at line 637 of file qgsfeaturerequest.h.
|
protected |
Definition at line 638 of file qgsfeaturerequest.h.
|
protected |
Definition at line 636 of file qgsfeaturerequest.h.
|
protected |
Definition at line 641 of file qgsfeaturerequest.h.
|
protected |
Definition at line 647 of file qgsfeaturerequest.h.
|
protected |
Definition at line 646 of file qgsfeaturerequest.h.
|
protected |
Definition at line 644 of file qgsfeaturerequest.h.
|
protected |
Definition at line 645 of file qgsfeaturerequest.h.
|
protected |
Definition at line 643 of file qgsfeaturerequest.h.
|
protected |
Definition at line 650 of file qgsfeaturerequest.h.
|
protected |
Definition at line 648 of file qgsfeaturerequest.h.