mirror of
https://github.com/qgis/QGIS.git
synced 2025-10-31 00:06:02 -04:00
1113 lines
34 KiB
Plaintext
1113 lines
34 KiB
Plaintext
/************************************************************************
|
|
* This file has been generated automatically from *
|
|
* *
|
|
* src/core/qgsfeaturerequest.h *
|
|
* *
|
|
* Do not edit manually ! Edit header and run scripts/sipify.py again *
|
|
************************************************************************/
|
|
|
|
|
|
|
|
class QgsFeatureRequest
|
|
{
|
|
%Docstring(signature="appended")
|
|
Wraps a request for features to a vector layer (or directly its vector
|
|
data provider).
|
|
|
|
The request may apply an attribute/ID filter to fetch only a particular
|
|
subset of features. Currently supported filters:
|
|
|
|
- no filter - all features are returned
|
|
- feature id - only feature that matches given feature id is returned
|
|
- feature ids - only features that match any of the given feature ids
|
|
are returned
|
|
- filter expression - only features that match the given filter
|
|
expression are returned
|
|
|
|
Additionally a spatial filter can be set in combination with the
|
|
attribute/ID filter. Supported spatial filters are:
|
|
|
|
- :py:class:`Qgis`.SpatialFilterType.BoundingBox: Only features that intersect a given rectangle will 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.
|
|
- :py:class:`Qgis`.SpatialFilterType.DistanceWithin: Only features within a specified distance of a reference geometry will be fetched.
|
|
|
|
For efficiency, it is also possible to tell provider that some data is
|
|
not required:
|
|
|
|
- NoGeometry flag
|
|
- SubsetOfAttributes flag
|
|
- SimplifyMethod for geometries to fetch
|
|
|
|
The options may be chained, e.g.:
|
|
|
|
.. code-block:: python
|
|
|
|
QgsFeatureRequest().setFilterRect(QgsRectangle(0,0,1,1)).setFlags(QgsFeatureRequest.ExactIntersect)
|
|
|
|
Examples:
|
|
|
|
.. code-block:: python
|
|
|
|
# fetch all features:
|
|
QgsFeatureRequest()
|
|
# fetch all features, only one attribute
|
|
QgsFeatureRequest().setSubsetOfAttributes(['myfield'], layer.fields())
|
|
# fetch all features, without geometries
|
|
QgsFeatureRequest().setFlags(QgsFeatureRequest.NoGeometry)
|
|
# fetch only features from particular extent
|
|
QgsFeatureRequest().setFilterRect(QgsRectangle(0,0,1,1))
|
|
# fetch only features from particular extent, where the 'type' attribute is equal to 'road':
|
|
QgsFeatureRequest().setFilterRect(QgsRectangle(0,0,1,1)).setFilterExpression('"type"=\'road\'')
|
|
# fetch only one feature
|
|
QgsFeatureRequest().setFilterFid(45)
|
|
# fetch features within 50 map units of a linestring geometry
|
|
QgsFeatureRequest().setDistanceWithin(QgsGeometry.fromWkt('LineString(0 0, 10 0, 12 1)'), 50)
|
|
%End
|
|
|
|
%TypeHeaderCode
|
|
#include "qgsfeaturerequest.h"
|
|
%End
|
|
public:
|
|
|
|
class OrderByClause
|
|
{
|
|
%Docstring(signature="appended")
|
|
The OrderByClause class represents an order by clause for a
|
|
QgsFeatureRequest.
|
|
|
|
It can be a simple field or an expression. Multiple order by clauses can
|
|
be added to a QgsFeatureRequest to fine tune the behavior if a single
|
|
field or expression is not enough to completely specify the required
|
|
behavior.
|
|
|
|
If expression compilation is activated in the settings and the
|
|
expression can be translated for the provider in question, it will be
|
|
evaluated on provider side. If one of these two premises does not apply,
|
|
the ordering will take place locally which results in increased memory
|
|
and CPU usage.
|
|
|
|
If the ordering is done on strings, the order depends on the system's
|
|
locale if the local fallback implementation is used. The order depends
|
|
on the server system's locale and implementation if ordering is done on
|
|
the server.
|
|
|
|
In case the fallback code needs to be used, a limit set on the request
|
|
will be respected for the features returned by the iterator but
|
|
internally all features will be requested from the provider.
|
|
%End
|
|
|
|
%TypeHeaderCode
|
|
#include "qgsfeaturerequest.h"
|
|
%End
|
|
public:
|
|
|
|
OrderByClause( const QString &expression, bool ascending = true );
|
|
%Docstring
|
|
Creates a new OrderByClause for a :py:class:`QgsFeatureRequest`
|
|
|
|
:param expression: The expression to use for ordering
|
|
:param 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
|
|
%End
|
|
|
|
OrderByClause( const QString &expression, bool ascending, bool nullsfirst );
|
|
%Docstring
|
|
Creates a new OrderByClause for a :py:class:`QgsFeatureRequest`
|
|
|
|
:param expression: The expression to use for ordering
|
|
:param ascending: If the order should be ascending (1,2,3) or descending
|
|
(3,2,1)
|
|
:param nullsfirst: If ``True``, NULLS are at the beginning, if
|
|
``False``, NULLS are at the end
|
|
%End
|
|
|
|
OrderByClause( const QgsExpression &expression, bool ascending = true );
|
|
%Docstring
|
|
Creates a new OrderByClause for a :py:class:`QgsFeatureRequest`
|
|
|
|
:param expression: The expression to use for ordering
|
|
:param 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
|
|
%End
|
|
|
|
OrderByClause( const QgsExpression &expression, bool ascending, bool nullsfirst );
|
|
%Docstring
|
|
Creates a new OrderByClause for a :py:class:`QgsFeatureRequest`
|
|
|
|
:param expression: The expression to use for ordering
|
|
:param ascending: If the order should be ascending (1,2,3) or descending
|
|
(3,2,1)
|
|
:param nullsfirst: If ``True``, NULLS are at the beginning, if
|
|
``False``, NULLS are at the end
|
|
%End
|
|
|
|
QgsExpression expression() const;
|
|
%Docstring
|
|
The expression
|
|
|
|
:return: the expression
|
|
%End
|
|
|
|
bool prepare( QgsExpressionContext *context );
|
|
%Docstring
|
|
Prepare the expression with the given context.
|
|
|
|
.. seealso:: :py:func:`QgsExpression.prepare`
|
|
%End
|
|
|
|
bool ascending() const;
|
|
%Docstring
|
|
Order ascending
|
|
|
|
:return: If ascending order is requested
|
|
%End
|
|
|
|
void setAscending( bool ascending );
|
|
%Docstring
|
|
Set if ascending order is requested
|
|
%End
|
|
|
|
bool nullsFirst() const;
|
|
%Docstring
|
|
Set if NULLS should be returned first
|
|
|
|
:return: if NULLS should be returned first
|
|
%End
|
|
|
|
void setNullsFirst( bool nullsFirst );
|
|
%Docstring
|
|
Set if NULLS should be returned first
|
|
%End
|
|
|
|
QString dump() const;
|
|
%Docstring
|
|
Dumps the content to an SQL equivalent
|
|
%End
|
|
|
|
|
|
bool operator==( const OrderByClause &v ) const;
|
|
|
|
bool operator!=( const OrderByClause &v ) const;
|
|
|
|
};
|
|
|
|
|
|
class OrderBy
|
|
{
|
|
%Docstring(signature="appended")
|
|
Represents a list of OrderByClauses, with the most important first and
|
|
the least important last.
|
|
%End
|
|
|
|
%TypeHeaderCode
|
|
#include "qgsfeaturerequest.h"
|
|
%End
|
|
public:
|
|
|
|
OrderBy();
|
|
%Docstring
|
|
Create a new empty order by
|
|
%End
|
|
|
|
OrderBy( const QList<QgsFeatureRequest::OrderByClause> &other );
|
|
%Docstring
|
|
Create a new order by from a list of clauses
|
|
%End
|
|
|
|
bool operator==( const OrderBy &v ) const;
|
|
|
|
bool operator!=( const OrderBy &v ) const;
|
|
|
|
QList<QgsFeatureRequest::OrderByClause> list() const;
|
|
%Docstring
|
|
Gets a copy as a list of OrderByClauses
|
|
|
|
This is only required in Python where the inheritance is not properly
|
|
propagated and this makes it usable.
|
|
%End
|
|
|
|
void save( QDomElement &elem ) const;
|
|
%Docstring
|
|
Serialize to XML
|
|
%End
|
|
|
|
void load( const QDomElement &elem );
|
|
%Docstring
|
|
Deserialize from XML
|
|
%End
|
|
|
|
QSet<QString> usedAttributes() const;
|
|
%Docstring
|
|
Returns a set of used attributes
|
|
|
|
.. note::
|
|
|
|
The returned attributes names are NOT guaranteed to be valid.
|
|
%End
|
|
|
|
QSet<int> usedAttributeIndices( const QgsFields &fields ) const;
|
|
%Docstring
|
|
Returns a set of used, validated attribute indices
|
|
|
|
.. versionadded:: 3.8
|
|
%End
|
|
|
|
QString dump() const;
|
|
%Docstring
|
|
Dumps the content to an SQL equivalent syntax
|
|
%End
|
|
};
|
|
|
|
static const QString ALL_ATTRIBUTES;
|
|
|
|
QgsFeatureRequest();
|
|
%Docstring
|
|
construct a default request: for all features get attributes and
|
|
geometries
|
|
%End
|
|
explicit QgsFeatureRequest( QgsFeatureId fid );
|
|
%Docstring
|
|
construct a request with feature ID filter
|
|
%End
|
|
explicit QgsFeatureRequest( const QgsFeatureIds &fids );
|
|
%Docstring
|
|
construct a request with feature ID filter
|
|
%End
|
|
|
|
explicit QgsFeatureRequest( const QgsRectangle &rectangle );
|
|
%Docstring
|
|
Construct a request with ``rectangle`` bounding box filter.
|
|
|
|
When a destination CRS is set using
|
|
:py:func:`~QgsFeatureRequest.setDestinationCrs`, ``rectangle`` is
|
|
expected to be in the same CRS as the
|
|
:py:func:`~QgsFeatureRequest.destinationCrs`. Otherwise, ``rectangle``
|
|
should use the same CRS as the source layer/provider.
|
|
%End
|
|
|
|
explicit QgsFeatureRequest( const QgsExpression &expr, const QgsExpressionContext &context = QgsExpressionContext() );
|
|
%Docstring
|
|
construct a request with a filter expression
|
|
%End
|
|
QgsFeatureRequest( const QgsFeatureRequest &rh );
|
|
|
|
bool compare( const QgsFeatureRequest &other ) const;
|
|
%Docstring
|
|
Compare two requests for equality, ignoring Expression Context,
|
|
Transform Error Callback, Feedback and Invalid Geometry Callback
|
|
|
|
:param other: the other request
|
|
|
|
:return: ``True`` if the requests are equal in all respects but without
|
|
checking for Expression Context, Transform Error, Feedback and
|
|
Invalid Geometry Callback
|
|
|
|
.. versionadded:: 3.38
|
|
%End
|
|
|
|
~QgsFeatureRequest();
|
|
|
|
Qgis::FeatureRequestFilterType filterType() const;
|
|
%Docstring
|
|
Returns the attribute/ID filter type which is currently set on this
|
|
request.
|
|
|
|
This type will automatically be set to the appropriate value whenever
|
|
:py:func:`~QgsFeatureRequest.setFilterFid`,
|
|
:py:func:`~QgsFeatureRequest.setFilterFids`,
|
|
:py:func:`~QgsFeatureRequest.setFilterExpression` or
|
|
:py:func:`~QgsFeatureRequest.disableFilter` are called.
|
|
|
|
.. note::
|
|
|
|
A feature request may have both an attribute/ID filter AND a spatial filter
|
|
set. See :py:func:`~QgsFeatureRequest.spatialFilterType` to retrieve the spatial filter.
|
|
|
|
.. seealso:: :py:func:`spatialFilterType`
|
|
%End
|
|
|
|
Qgis::SpatialFilterType spatialFilterType() const;
|
|
%Docstring
|
|
Returns the spatial filter type which is currently set on this request.
|
|
|
|
This type will automatically be set to the appropriate value whenever
|
|
:py:func:`~QgsFeatureRequest.setFilterRect`, or
|
|
:py:func:`~QgsFeatureRequest.setDistanceWithin` are called.
|
|
|
|
.. note::
|
|
|
|
A feature request may have both an attribute/ID filter AND a spatial filter
|
|
set. See :py:func:`~QgsFeatureRequest.filterType` to retrieve the attribute/ID filter.
|
|
|
|
.. seealso:: :py:func:`filterType`
|
|
|
|
.. versionadded:: 3.22
|
|
%End
|
|
|
|
QgsFeatureRequest &setFilterRect( const QgsRectangle &rectangle );
|
|
%Docstring
|
|
Sets the ``rectangle`` from which features will be taken. An empty
|
|
rectangle removes the filter.
|
|
|
|
When a destination CRS is set using
|
|
:py:func:`~QgsFeatureRequest.setDestinationCrs`, ``rectangle`` is
|
|
expected to be in the same CRS as the
|
|
:py:func:`~QgsFeatureRequest.destinationCrs`. Otherwise, ``rectangle``
|
|
should use the same CRS as the source layer/provider.
|
|
|
|
Calling this method will automatically set
|
|
:py:func:`~QgsFeatureRequest.spatialFilterType` to
|
|
:py:class:`Qgis`.SpatialFilterType.BoundingBox. If ``rectangle`` is a
|
|
null rectangle then :py:func:`~QgsFeatureRequest.spatialFilterType` will
|
|
be reset to :py:class:`Qgis`.SpatialFilterType.NoFilter.
|
|
|
|
.. seealso:: :py:func:`filterRect`
|
|
%End
|
|
|
|
QgsRectangle filterRect() const;
|
|
%Docstring
|
|
Returns the rectangle from which features will be taken. If the returned
|
|
rectangle is null, then no filter rectangle is set.
|
|
|
|
If :py:func:`~QgsFeatureRequest.spatialFilterType` is
|
|
:py:class:`Qgis`.SpatialFilterType.BoundingBox then only features from
|
|
within this bounding box will be fetched. If
|
|
:py:func:`~QgsFeatureRequest.spatialFilterType` is
|
|
:py:class:`Qgis`.SpatialFilterType.DistanceWithin then the returned
|
|
rectangle represents the bounding box of the
|
|
:py:func:`~QgsFeatureRequest.referenceGeometry` extended by
|
|
:py:func:`~QgsFeatureRequest.distanceWithin`.
|
|
|
|
When a destination CRS is set using
|
|
:py:func:`~QgsFeatureRequest.setDestinationCrs`, the rectangle will be
|
|
in the same CRS as the :py:func:`~QgsFeatureRequest.destinationCrs`.
|
|
Otherwise, the rectangle will use the same CRS as the source
|
|
layer/provider.
|
|
|
|
.. seealso:: :py:func:`setFilterRect`
|
|
%End
|
|
|
|
QgsFeatureRequest &setDistanceWithin( const QgsGeometry &geometry, double distance );
|
|
%Docstring
|
|
Sets a reference ``geometry`` and a maximum ``distance`` from this
|
|
geometry to retrieve features within.
|
|
|
|
When a destination CRS is set using
|
|
:py:func:`~QgsFeatureRequest.setDestinationCrs`, ``geometry`` is
|
|
expected to be in the same CRS as the
|
|
:py:func:`~QgsFeatureRequest.destinationCrs` and ``distance`` is in the
|
|
spatial units of the :py:func:`~QgsFeatureRequest.destinationCrs`.
|
|
Otherwise, ``geometry`` should use the same CRS as the source
|
|
layer/provider and ``distance`` should use the spatial units as this
|
|
same CRS.
|
|
|
|
Calling this method will automatically set
|
|
:py:func:`~QgsFeatureRequest.spatialFilterType` to
|
|
:py:class:`Qgis`.SpatialFilterType.DistanceWithin.
|
|
|
|
.. seealso:: :py:func:`filterRect`
|
|
|
|
.. versionadded:: 3.22
|
|
%End
|
|
|
|
QgsGeometry referenceGeometry() const;
|
|
%Docstring
|
|
Returns the reference geometry used for spatial filtering of features.
|
|
|
|
When :py:func:`~QgsFeatureRequest.spatialFilterType` is
|
|
:py:class:`Qgis`.SpatialFilterType.DistanceWithin then only features
|
|
within :py:func:`~QgsFeatureRequest.distanceWithin` units of the
|
|
reference geometry will be fetched.
|
|
|
|
When a destination CRS is set using
|
|
:py:func:`~QgsFeatureRequest.setDestinationCrs`, the geometry will be in
|
|
the same CRS as the :py:func:`~QgsFeatureRequest.destinationCrs`.
|
|
Otherwise, the geometry will use the same CRS as the source
|
|
layer/provider.
|
|
|
|
.. seealso:: :py:func:`setDistanceWithin`
|
|
|
|
.. versionadded:: 3.22
|
|
%End
|
|
|
|
|
|
double distanceWithin() const;
|
|
%Docstring
|
|
Returns the maximum distance from the
|
|
:py:func:`~QgsFeatureRequest.referenceGeometry` of fetched features, if
|
|
:py:func:`~QgsFeatureRequest.spatialFilterType` is
|
|
:py:class:`Qgis`.SpatialFilterType.DistanceWithin.
|
|
|
|
When a destination CRS is set using
|
|
:py:func:`~QgsFeatureRequest.setDestinationCrs`, the distance will be in
|
|
the spatial units of :py:func:`~QgsFeatureRequest.destinationCrs`.
|
|
Otherwise, the distance will use the same units as the CRS of the source
|
|
layer/provider.
|
|
|
|
.. seealso:: :py:func:`setDistanceWithin`
|
|
|
|
.. versionadded:: 3.22
|
|
%End
|
|
|
|
QgsFeatureRequest &setFilterFid( QgsFeatureId fid );
|
|
%Docstring
|
|
Sets the feature ID that should be fetched.
|
|
|
|
Calling this method will automatically set
|
|
:py:func:`~QgsFeatureRequest.filterType` to QgsFeatureRequest.FilterFid.
|
|
|
|
.. seealso:: :py:func:`filterFid`
|
|
|
|
.. seealso:: :py:func:`setFilterFids`
|
|
%End
|
|
|
|
QgsFeatureId filterFid() const;
|
|
%Docstring
|
|
Returns the feature ID that should be fetched.
|
|
|
|
.. seealso:: :py:func:`setFilterFid`
|
|
|
|
.. seealso:: :py:func:`filterFids`
|
|
%End
|
|
|
|
QgsFeatureRequest &setFilterFids( const QgsFeatureIds &fids );
|
|
%Docstring
|
|
Sets the feature IDs that should be fetched.
|
|
|
|
Calling this method will automatically set
|
|
:py:func:`~QgsFeatureRequest.filterType` to
|
|
QgsFeatureRequest.FilterFids.
|
|
|
|
.. seealso:: :py:func:`filterFids`
|
|
|
|
.. seealso:: :py:func:`setFilterFid`
|
|
%End
|
|
|
|
const QgsFeatureIds &filterFids() const;
|
|
%Docstring
|
|
Returns the feature IDs that should be fetched.
|
|
|
|
.. seealso:: :py:func:`setFilterFids`
|
|
|
|
.. seealso:: :py:func:`filterFid`
|
|
%End
|
|
|
|
QgsFeatureRequest &setInvalidGeometryCheck( Qgis::InvalidGeometryCheck check );
|
|
%Docstring
|
|
Sets invalid geometry checking behavior.
|
|
|
|
.. note::
|
|
|
|
Invalid geometry checking is not performed when retrieving features
|
|
directly from a :py:class:`QgsVectorDataProvider`.
|
|
|
|
.. seealso:: :py:func:`invalidGeometryCheck`
|
|
%End
|
|
|
|
Qgis::InvalidGeometryCheck invalidGeometryCheck() const;
|
|
%Docstring
|
|
Returns the invalid geometry checking behavior.
|
|
|
|
.. seealso:: :py:func:`setInvalidGeometryCheck`
|
|
%End
|
|
|
|
QgsFeatureRequest &setInvalidGeometryCallback( SIP_PYCALLABLE / AllowNone / );
|
|
%Docstring
|
|
Sets a callback function to use when encountering an invalid geometry
|
|
and :py:func:`~QgsFeatureRequest.invalidGeometryCheck` is set to
|
|
GeometryAbortOnInvalid or GeometrySkipInvalid. This function will be
|
|
called using the feature with invalid geometry as a parameter.
|
|
|
|
.. seealso:: :py:func:`invalidGeometryCallback`
|
|
%End
|
|
%MethodCode
|
|
Py_BEGIN_ALLOW_THREADS
|
|
|
|
sipCpp->setInvalidGeometryCallback( [a0]( const QgsFeature &arg )
|
|
{
|
|
SIP_BLOCK_THREADS
|
|
Py_XDECREF( sipCallMethod( NULL, a0, "D", &arg, sipType_QgsFeature, NULL ) );
|
|
SIP_UNBLOCK_THREADS
|
|
} );
|
|
|
|
sipRes = sipCpp;
|
|
|
|
Py_END_ALLOW_THREADS
|
|
%End
|
|
|
|
|
|
QgsFeatureRequest &setFilterExpression( const QString &expression );
|
|
%Docstring
|
|
Set the filter ``expression``. {:py:class:`QgsExpression`}
|
|
|
|
:param expression: expression string
|
|
|
|
Calling this method will automatically set
|
|
:py:func:`~QgsFeatureRequest.filterType` to
|
|
QgsFeatureRequest.FilterExpression.
|
|
|
|
.. seealso:: :py:func:`filterExpression`
|
|
|
|
.. seealso:: :py:func:`setExpressionContext`
|
|
%End
|
|
|
|
QgsExpression *filterExpression() const;
|
|
%Docstring
|
|
Returns the filter expression (if set).
|
|
|
|
.. seealso:: :py:func:`setFilterExpression`
|
|
|
|
.. seealso:: :py:func:`expressionContext`
|
|
%End
|
|
|
|
QgsFeatureRequest &combineFilterExpression( const QString &expression );
|
|
%Docstring
|
|
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.
|
|
|
|
Calling this method will automatically set
|
|
:py:func:`~QgsFeatureRequest.filterType` to
|
|
QgsFeatureRequest.FilterExpression.
|
|
%End
|
|
|
|
QgsExpressionContext *expressionContext();
|
|
%Docstring
|
|
Returns the expression context used to evaluate filter expressions.
|
|
|
|
.. seealso:: :py:func:`setExpressionContext`
|
|
|
|
.. seealso:: :py:func:`filterExpression`
|
|
%End
|
|
|
|
QgsFeatureRequest &setExpressionContext( const QgsExpressionContext &context );
|
|
%Docstring
|
|
Sets the expression context used to evaluate filter expressions.
|
|
|
|
.. seealso:: :py:func:`expressionContext`
|
|
|
|
.. seealso:: :py:func:`setFilterExpression`
|
|
%End
|
|
|
|
QgsFeatureRequest &disableFilter();
|
|
%Docstring
|
|
Disables any attribute/ID filtering.
|
|
|
|
Calling this method will automatically set
|
|
:py:func:`~QgsFeatureRequest.filterType` to
|
|
QgsFeatureRequest.FilterNone.
|
|
|
|
.. note::
|
|
|
|
Spatial filters will be left in place.
|
|
|
|
:return: The object the method is called on for chaining
|
|
%End
|
|
|
|
|
|
QgsFeatureRequest &addOrderBy( const QString &expression, bool ascending = true );
|
|
%Docstring
|
|
Adds a new OrderByClause, appending it as the least important one.
|
|
|
|
:param expression: The expression to use for ordering
|
|
:param 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
|
|
%End
|
|
|
|
QgsFeatureRequest &addOrderBy( const QString &expression, bool ascending, bool nullsfirst );
|
|
%Docstring
|
|
Adds a new OrderByClause, appending it as the least important one.
|
|
|
|
:param expression: The expression to use for ordering
|
|
:param ascending: If the order should be ascending (1,2,3) or descending
|
|
(3,2,1)
|
|
:param nullsfirst: If ``True``, NULLS are at the beginning, if
|
|
``False``, NULLS are at the end
|
|
%End
|
|
|
|
OrderBy orderBy() const;
|
|
%Docstring
|
|
Returns a list of order by clauses specified for this feature request.
|
|
%End
|
|
|
|
QgsFeatureRequest &setOrderBy( const OrderBy &orderBy );
|
|
%Docstring
|
|
Set a list of order by clauses.
|
|
%End
|
|
|
|
QgsFeatureRequest &setLimit( long long limit );
|
|
%Docstring
|
|
Set the maximum number of features to request.
|
|
|
|
:param limit: maximum number of features, or -1 to request all features.
|
|
|
|
.. seealso:: :py:func:`limit`
|
|
%End
|
|
|
|
long long limit() const;
|
|
%Docstring
|
|
Returns the maximum number of features to request, or -1 if no limit
|
|
set.
|
|
|
|
.. seealso:: :py:func:`setLimit`
|
|
%End
|
|
|
|
QgsFeatureRequest &setFlags( Qgis::FeatureRequestFlags flags );
|
|
%Docstring
|
|
Sets ``flags`` that affect how features will be fetched.
|
|
|
|
.. seealso:: :py:func:`flags`
|
|
%End
|
|
|
|
Qgis::FeatureRequestFlags flags() const;
|
|
%Docstring
|
|
Returns the flags which affect how features are fetched.
|
|
|
|
.. seealso:: :py:func:`setFlags`
|
|
%End
|
|
|
|
QgsFeatureRequest &setSubsetOfAttributes( const QgsAttributeList &attrs );
|
|
%Docstring
|
|
Set a subset of attributes that will be fetched.
|
|
|
|
An empty attributes list indicates that no attributes will be fetched.
|
|
To revert a call to setSubsetOfAttributes and fetch all available
|
|
attributes, the SubsetOfAttributes flag should be removed from the
|
|
request.
|
|
|
|
.. note::
|
|
|
|
This is intended as hint to data providers for optimising feature retrieval. Depending
|
|
on the provider, it may be trivial for the provider to always return all attributes instead of
|
|
the requested subset, or actually result in slower retrieval when the attributes are filtered out.
|
|
In these cases the provider may ignore this hint and return all attributes regardless of the
|
|
requested attributes.
|
|
|
|
.. seealso:: :py:func:`subsetOfAttributes`
|
|
|
|
.. seealso:: :py:func:`setNoAttributes`
|
|
%End
|
|
|
|
QgsFeatureRequest &setNoAttributes();
|
|
%Docstring
|
|
Set that no attributes will be fetched.
|
|
|
|
To revert a call to setNoAttributes and fetch all or some available
|
|
attributes, the SubsetOfAttributes flag should be removed from the
|
|
request.
|
|
|
|
.. note::
|
|
|
|
This is intended as hint to data providers for optimising feature retrieval. Depending
|
|
on the provider, it may be trivial for the provider to always return all attributes instead of
|
|
removing them. In these cases the provider may ignore this hint and return all attributes
|
|
regardless of whether this method has been called.
|
|
|
|
.. seealso:: :py:func:`setSubsetOfAttributes`
|
|
|
|
.. versionadded:: 3.4
|
|
%End
|
|
|
|
QgsAttributeList subsetOfAttributes() const;
|
|
%Docstring
|
|
Returns the subset of attributes which at least need to be fetched.
|
|
|
|
:return: A list of attributes to be fetched
|
|
|
|
.. note::
|
|
|
|
This is intended as hint to data providers for optimising feature retrieval. Depending
|
|
on the provider, it may be trivial for the provider to always return all attributes instead of
|
|
the requested subset, or actually result in slower retrieval when the attributes are filtered out.
|
|
In these cases the provider may ignore this hint and return all attributes regardless of the
|
|
requested attributes.
|
|
|
|
.. seealso:: :py:func:`setSubsetOfAttributes`
|
|
|
|
.. seealso:: :py:func:`setNoAttributes`
|
|
%End
|
|
|
|
QgsFeatureRequest &setSubsetOfAttributes( const QStringList &attrNames, const QgsFields &fields );
|
|
%Docstring
|
|
Sets a subset of attributes by names that will be fetched.
|
|
|
|
.. note::
|
|
|
|
This is intended as hint to data providers for optimising feature retrieval. Depending
|
|
on the provider, it may be trivial for the provider to always return all attributes instead of
|
|
the requested subset, or actually result in slower retrieval when the attributes are filtered out.
|
|
In these cases the provider may ignore this hint and return all attributes regardless of the
|
|
requested attributes.
|
|
|
|
.. seealso:: :py:func:`subsetOfAttributes`
|
|
%End
|
|
|
|
QgsFeatureRequest &setSubsetOfAttributes( const QSet<QString> &attrNames, const QgsFields &fields );
|
|
%Docstring
|
|
Sets a subset of attributes by names that will be fetched.
|
|
|
|
.. note::
|
|
|
|
This is intended as hint to data providers for optimising feature retrieval. Depending
|
|
on the provider, it may be trivial for the provider to always return all attributes instead of
|
|
the requested subset, or actually result in slower retrieval when the attributes are filtered out.
|
|
In these cases the provider may ignore this hint and return all attributes regardless of the
|
|
requested attributes.
|
|
|
|
.. seealso:: :py:func:`subsetOfAttributes`
|
|
%End
|
|
|
|
QgsFeatureRequest &setSimplifyMethod( const QgsSimplifyMethod &simplifyMethod );
|
|
%Docstring
|
|
Set a simplification method for geometries that will be fetched.
|
|
|
|
.. seealso:: :py:func:`simplifyMethod`
|
|
%End
|
|
|
|
const QgsSimplifyMethod &simplifyMethod() const;
|
|
%Docstring
|
|
Returns the simplification method for geometries that will be fetched.
|
|
|
|
.. seealso:: :py:func:`setSimplifyMethod`
|
|
%End
|
|
|
|
QgsCoordinateTransform coordinateTransform() const;
|
|
%Docstring
|
|
Returns the coordinate transform which will be used to transform the
|
|
feature's geometries.
|
|
|
|
If this transform is valid then it will always be used to transform
|
|
features, regardless of the :py:func:`~QgsFeatureRequest.destinationCrs`
|
|
setting or the underlying feature source's actual CRS.
|
|
|
|
.. seealso:: :py:func:`setCoordinateTransform`
|
|
|
|
.. versionadded:: 3.40
|
|
%End
|
|
|
|
QgsCoordinateReferenceSystem destinationCrs() const;
|
|
%Docstring
|
|
Returns the destination coordinate reference system for feature's
|
|
geometries, or an invalid :py:class:`QgsCoordinateReferenceSystem` if no
|
|
reprojection will be done and all features will be left with their
|
|
original geometry.
|
|
|
|
.. warning::
|
|
|
|
if :py:func:`~QgsFeatureRequest.coordinateTransform` returns a valid transform then the
|
|
:py:func:`~QgsFeatureRequest.destinationCrs` will have no effect, and the :py:func:`~QgsFeatureRequest.coordinateTransform` will
|
|
always be used to transform features.
|
|
|
|
.. seealso:: :py:func:`calculateTransform`
|
|
|
|
.. seealso:: :py:func:`setDestinationCrs`
|
|
|
|
.. seealso:: :py:func:`transformContext`
|
|
%End
|
|
|
|
QgsCoordinateTransformContext transformContext() const;
|
|
%Docstring
|
|
Returns the transform context, for use when a
|
|
:py:func:`~QgsFeatureRequest.destinationCrs` has been set and
|
|
reprojection is required
|
|
|
|
.. seealso:: :py:func:`setDestinationCrs`
|
|
|
|
.. seealso:: :py:func:`destinationCrs`
|
|
%End
|
|
|
|
QgsCoordinateTransform calculateTransform( const QgsCoordinateReferenceSystem &sourceCrs ) const;
|
|
%Docstring
|
|
Calculates the coordinate transform to use to transform geometries when
|
|
they are originally in ``sourceCrs``.
|
|
|
|
This method will return
|
|
:py:func:`~QgsFeatureRequest.coordinateTransform` if it is set (ignoring
|
|
``sourceCrs``), otherwise it will calculate an appriopriate transform
|
|
from ``sourceCrs`` to :py:func:`~QgsFeatureRequest.destinationCrs`.
|
|
|
|
.. versionadded:: 3.40
|
|
%End
|
|
|
|
QgsFeatureRequest &setCoordinateTransform( const QgsCoordinateTransform &transform );
|
|
%Docstring
|
|
Sets the coordinate ``transform`` which will be used to transform the
|
|
feature's geometries.
|
|
|
|
If this transform is valid then it will always be used to transform
|
|
features, regardless of the :py:func:`~QgsFeatureRequest.destinationCrs`
|
|
setting or the underlying feature source's actual CRS.
|
|
|
|
When a ``transform`` is set using
|
|
:py:func:`~QgsFeatureRequest.setCoordinateTransform`, then any
|
|
:py:func:`~QgsFeatureRequest.filterRect` or
|
|
:py:func:`~QgsFeatureRequest.referenceGeometry` set on the request is
|
|
expected to be in the same CRS as the destination CRS for the
|
|
``transform``.
|
|
|
|
The feature geometry transformation is performed after all filter
|
|
expressions are tested and any virtual fields are calculated.
|
|
Accordingly, any geometric expressions used in
|
|
:py:func:`~QgsFeatureRequest.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.
|
|
|
|
.. warning::
|
|
|
|
This method should be used with caution, and it is recommended
|
|
to use the high-level :py:func:`~QgsFeatureRequest.setDestinationCrs` method instead. Setting a specific
|
|
transform should only be done when there is a requirement to use a particular
|
|
transform.
|
|
|
|
.. seealso:: :py:func:`coordinateTransform`
|
|
|
|
.. versionadded:: 3.40
|
|
%End
|
|
|
|
QgsFeatureRequest &setDestinationCrs( const QgsCoordinateReferenceSystem &crs, const QgsCoordinateTransformContext &context );
|
|
%Docstring
|
|
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
|
|
:py:class:`QgsCoordinateReferenceSystem` then no reprojection will be
|
|
done and all features will be left with their original geometry.
|
|
|
|
When a ``crs`` is set using
|
|
:py:func:`~QgsFeatureRequest.setDestinationCrs`, then any
|
|
:py:func:`~QgsFeatureRequest.filterRect` or
|
|
:py:func:`~QgsFeatureRequest.referenceGeometry` 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
|
|
:py:func:`~QgsFeatureRequest.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.
|
|
|
|
.. warning::
|
|
|
|
if :py:func:`~QgsFeatureRequest.coordinateTransform` returns a valid transform then the
|
|
:py:func:`~QgsFeatureRequest.destinationCrs` will have no effect, and the :py:func:`~QgsFeatureRequest.coordinateTransform` will
|
|
always be used to transform features.
|
|
|
|
.. seealso:: :py:func:`destinationCrs`
|
|
%End
|
|
|
|
QgsFeatureRequest &setTransformErrorCallback( SIP_PYCALLABLE / AllowNone / );
|
|
%Docstring
|
|
Sets a callback function to use when encountering a transform error when
|
|
iterating features and a :py:func:`~QgsFeatureRequest.destinationCrs` is
|
|
set. This function will be called using the feature which encountered
|
|
the transform error as a parameter.
|
|
|
|
.. seealso:: :py:func:`transformErrorCallback`
|
|
|
|
.. seealso:: :py:func:`setDestinationCrs`
|
|
%End
|
|
%MethodCode
|
|
Py_BEGIN_ALLOW_THREADS
|
|
|
|
sipCpp->setTransformErrorCallback( [a0]( const QgsFeature &arg )
|
|
{
|
|
SIP_BLOCK_THREADS
|
|
Py_XDECREF( sipCallMethod( NULL, a0, "D", &arg, sipType_QgsFeature, NULL ) );
|
|
SIP_UNBLOCK_THREADS
|
|
} );
|
|
|
|
sipRes = sipCpp;
|
|
|
|
Py_END_ALLOW_THREADS
|
|
%End
|
|
|
|
|
|
|
|
bool acceptFeature( const QgsFeature &feature );
|
|
%Docstring
|
|
Check if a feature is accepted by this requests filter
|
|
|
|
:param feature: The feature which will be tested
|
|
|
|
:return: ``True``, if the filter accepts the feature
|
|
%End
|
|
|
|
int connectionTimeout() const /Deprecated="Since 3.40. Use timeout() instead."/;
|
|
%Docstring
|
|
Returns the timeout (in milliseconds) 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.
|
|
|
|
.. note::
|
|
|
|
Only works if the provider supports this option.
|
|
|
|
.. deprecated:: 3.40
|
|
|
|
Use :py:func:`~QgsFeatureRequest.timeout` instead.
|
|
%End
|
|
|
|
QgsFeatureRequest &setConnectionTimeout( int connectionTimeout ) /Deprecated="Since 3.40. Use setTimeout() instead."/;
|
|
%Docstring
|
|
Sets the timeout (in milliseconds) 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.
|
|
|
|
.. note::
|
|
|
|
Only works if the provider supports this option.
|
|
|
|
.. deprecated:: 3.40
|
|
|
|
Use :py:func:`~QgsFeatureRequest.setTimeout` instead.
|
|
%End
|
|
|
|
int timeout() const;
|
|
%Docstring
|
|
Returns the timeout (in milliseconds) for the maximum time we should
|
|
wait during feature requests before a feature is returned. A negative
|
|
value (which is set by default) will wait forever.
|
|
|
|
.. note::
|
|
|
|
Only works if the provider supports this option.
|
|
|
|
.. seealso:: :py:func:`setTimeout`
|
|
|
|
.. versionadded:: 3.4
|
|
%End
|
|
|
|
QgsFeatureRequest &setTimeout( int timeout );
|
|
%Docstring
|
|
Sets the ``timeout`` (in milliseconds) for the maximum time we should
|
|
wait during feature requests before a feature is returned. A negative
|
|
value (which is set by default) will wait forever.
|
|
|
|
.. note::
|
|
|
|
Only works if the provider supports this option.
|
|
|
|
.. seealso:: :py:func:`timeout`
|
|
|
|
.. versionadded:: 3.4
|
|
%End
|
|
|
|
bool requestMayBeNested() const;
|
|
%Docstring
|
|
In case this request may be run nested within another already running
|
|
iteration on the same connection, set this to ``True``.
|
|
|
|
If this flag is ``True``, this request will be able to make use of
|
|
"spare" connections to avoid deadlocks.
|
|
|
|
For example, this should be set on requests that are issued from an
|
|
expression function.
|
|
|
|
.. seealso:: :py:func:`setRequestMayBeNested`
|
|
|
|
.. versionadded:: 3.4
|
|
%End
|
|
|
|
QgsFeatureRequest &setRequestMayBeNested( bool requestMayBeNested );
|
|
%Docstring
|
|
In case this request may be run nested within another already running
|
|
iteration on the same connection, set this to ``True``.
|
|
|
|
If this flag is ``True``, this request will be able to make use of
|
|
"spare" connections to avoid deadlocks.
|
|
|
|
For example, this should be set on requests that are issued from an
|
|
expression function.
|
|
|
|
.. seealso:: :py:func:`requestMayBeNested`
|
|
|
|
.. versionadded:: 3.4
|
|
%End
|
|
|
|
void setFeedback( QgsFeedback *feedback );
|
|
%Docstring
|
|
Attach a ``feedback`` object that can be queried regularly by the
|
|
iterator to check if it should be canceled.
|
|
|
|
Ownership of ``feedback`` is NOT transferred, and the caller must take
|
|
care that it exists for the lifetime of the feature request and feature
|
|
iterators.
|
|
|
|
.. seealso:: :py:func:`feedback`
|
|
|
|
.. versionadded:: 3.20
|
|
%End
|
|
|
|
QgsFeedback *feedback() const;
|
|
%Docstring
|
|
Returns the feedback object that can be queried regularly by the
|
|
iterator to check if it should be canceled, if set.
|
|
|
|
.. seealso:: :py:func:`setFeedback`
|
|
|
|
.. versionadded:: 3.20
|
|
%End
|
|
|
|
protected:
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
};
|
|
|
|
|
|
|
|
class QgsAbstractFeatureSource
|
|
{
|
|
%Docstring(signature="appended")
|
|
Base class that can be used for any class that is capable of returning
|
|
features.
|
|
%End
|
|
|
|
%TypeHeaderCode
|
|
#include "qgsfeaturerequest.h"
|
|
%End
|
|
public:
|
|
virtual ~QgsAbstractFeatureSource();
|
|
|
|
|
|
|
|
virtual QgsFeatureIterator getFeatures( const QgsFeatureRequest &request = QgsFeatureRequest() ) = 0 /TransferBack/;
|
|
%Docstring
|
|
Gets an iterator for features matching the specified request
|
|
|
|
:param request: The request
|
|
|
|
:return: A feature iterator
|
|
%End
|
|
|
|
|
|
protected:
|
|
void iteratorOpened( QgsAbstractFeatureIterator *it );
|
|
void iteratorClosed( QgsAbstractFeatureIterator *it );
|
|
|
|
|
|
};
|
|
|
|
/************************************************************************
|
|
* This file has been generated automatically from *
|
|
* *
|
|
* src/core/qgsfeaturerequest.h *
|
|
* *
|
|
* Do not edit manually ! Edit header and run scripts/sipify.py again *
|
|
************************************************************************/
|