class QgsFeatureRequest
{
%TypeHeaderCode
#include <qgsfeaturerequest.h>
%End
public:
enum Flag
{
NoFlags,
NoGeometry, //!< Geometry is not required. It may still be returned if e.g. required for a filter condition.
SubsetOfAttributes, //!< Fetch only a subset of attributes (setSubsetOfAttributes sets this flag)
ExactIntersect //!< Use exact geometry intersection (slower) instead of bounding boxes
};
typedef QFlags<QgsFeatureRequest::Flag> Flags;
enum FilterType
{
FilterNone, //!< No filter is applied
FilterRect, //!< Filter using a rectangle, no need to set NoGeometry
FilterFid, //!< Filter using feature ID
FilterExpression, //!< Filter using expression
FilterFids //!< Filter using feature IDs
};
/**
* @brief The OrderByClause class represents an order by clause for a QgsFeatureRequest
*/
class OrderByClause
{
public:
/**
* Creates a new OrderByClause for a 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 thr order is ascending, by default nulls are last
* If thr order is descending, by default nulls are first
*/
OrderByClause( const QString &expression, bool ascending = true );
/**
* Creates a new OrderByClause for a 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
*/
OrderByClause( const QString &expression, bool ascending, bool nullsfirst );
/**
* The expression
* @return the expression
*/
QgsExpression expression() const;
/**
* Order ascending
* @return If ascending order is requested
*/
bool ascending() const;
/**
* Set if ascending order is requested
*/
void setAscending( bool ascending );
/**
* Set if NULLS should be returned first
* @return if NULLS should be returned first
*/
bool nullsFirst() const;
/**
* Set if NULLS should be returned first
*/
void setNullsFirst( bool nullsFirst );
};
class OrderBy
{
public:
OrderBy();
OrderBy( const QList<QgsFeatureRequest::OrderByClause>& other );
/**
* Get 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.
*/
QList<QgsFeatureRequest::OrderByClause> list() const;
/**
* Serialize to XML
*/
void save( QDomElement& elem ) const;
/**
* Deserialize from XML
*/
void load( const QDomElement& elem );
/**
* Returns a set of used attributes
*/
QSet<QString> usedAttributes() const;
/**
* Dumps the content to an SQL equivalent syntax
*/
QString dump() const;
};
/**
* A special attribute that if set matches all attributes
*/
static const QString AllAttributes;
//! construct a default request: for all features get attributes and geometries
QgsFeatureRequest();
//! construct a request with feature ID filter
explicit QgsFeatureRequest( QgsFeatureId fid );
//! construct a request with rectangle filter
explicit QgsFeatureRequest( const QgsRectangle& rect );
//! construct a request with a filter expression
explicit QgsFeatureRequest( const QgsExpression& expr, const QgsExpressionContext& context = QgsExpressionContext() );
FilterType filterType() const;
//! Set rectangle from which features will be taken. Empty rectangle removes the filter.
//!
QgsFeatureRequest& setFilterRect( const QgsRectangle& rect );
const QgsRectangle& filterRect() const;
//! Set feature ID that should be fetched.
QgsFeatureRequest& setFilterFid( qint64 fid );
qint64 filterFid() const;
//! Set feature ID that should be fetched.
QgsFeatureRequest& setFilterFids( const QgsFeatureIds& fids );
const QgsFeatureIds& filterFids() const;
/** Set the filter expression. {@see QgsExpression}
* @param expression expression string
* @see filterExpression
* @see setExpressionContext
*/
QgsFeatureRequest& setFilterExpression( const QString& expression );
/** Returns the filter expression if set.
* @see setFilterExpression
* @see expressionContext
*/
QgsExpression* filterExpression() const;
/** 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.
* @note added in QGIS 2.14
*/
QgsFeatureRequest& combineFilterExpression( const QString& expression );
/** Returns the expression context used to evaluate filter expressions.
* @note added in QGIS 2.12
* @see setExpressionContext
*/
QgsExpressionContext* expressionContext();
/** Sets the expression context used to evaluate filter expressions.
* @note added in QGIS 2.12
* @see expressionContext
*/
QgsFeatureRequest& setExpressionContext( const QgsExpressionContext& context );
/**
* Disables filter conditions.
* The spatial filter (filterRect) will be kept in place.
*
* @return The object the method is called on for chaining
*
* @note Added in 2.12
*/
QgsFeatureRequest& disableFilter();
/**
* Adds a new OrderByClause
*
* @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
*
* @added in QGIS 2.14
*/
QgsFeatureRequest& addOrderBy( const QString &expression, bool ascending = true );
/**
* 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
*
* @added in QGIS 2.14
*/
QgsFeatureRequest& addOrderBy( const QString &expression, bool ascending, bool nullsfirst );
/**
* Return a list of order by clauses specified for this feature request.
*/
QgsFeatureRequest::OrderBy orderBy() const;
/**
* Set a list of order by clauses.
*/
QgsFeatureRequest& setOrderBy(const QgsFeatureRequest::OrderBy& orderBy );
/** Set the maximum number of features to request.
* @param limit maximum number of features, or -1 to request all features.
* @see limit()
* @note added in QGIS 2.14
*/
QgsFeatureRequest& setLimit( long limit );
/** Returns the maximum number of features to request, or -1 if no limit set.
* @see setLimit
* @note added in QGIS 2.14
*/
long limit() const;
//! Set flags that affect how features will be fetched
QgsFeatureRequest& setFlags( const Flags& flags );
const Flags& flags() const;
//! 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)
QgsFeatureRequest& setSubsetOfAttributes( const QgsAttributeList& attrs );
const QgsAttributeList& subsetOfAttributes() const;
//! Set a subset of attributes by names that will be fetched
QgsFeatureRequest& setSubsetOfAttributes( const QStringList& attrNames, const QgsFields& fields );
//! Set a simplification method for geometries that will be fetched
//! @note added in 2.2
QgsFeatureRequest& setSimplifyMethod( const QgsSimplifyMethod& simplifyMethod );
//! Get simplification method for geometries that will be fetched
//! @note added in 2.2
const QgsSimplifyMethod& simplifyMethod() const;
/**
* 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
*
* @note added in 2.1
*/
bool acceptFeature( const QgsFeature& feature );
};
/** Base class that can be used for any class that is capable of returning features
* @note added in 2.4
*/
class QgsAbstractFeatureSource
{
%TypeHeaderCode
#include <qgsfeaturerequest.h>
%End
public:
virtual ~QgsAbstractFeatureSource();
virtual QgsFeatureIterator getFeatures( const QgsFeatureRequest& request ) = 0;
protected:
void iteratorOpened( QgsAbstractFeatureIterator* it );
void iteratorClosed( QgsAbstractFeatureIterator* it );
};