/
qgsfeaturerequest.sip
406 lines (351 loc) · 13.3 KB
/
qgsfeaturerequest.sip
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
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;
/**
* Types of filters.
*/
enum FilterType
{
FilterNone, //!< No filter is applied
FilterFid, //!< Filter using feature ID
FilterExpression, //!< Filter using expression
FilterFids //!< Filter using feature IDs
};
//! Handling of features with invalid geometries
enum InvalidGeometryCheck
{
GeometryNoCheck,
GeometrySkipInvalid,
GeometryAbortOnInvalid,
};
/**
* 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.
*
* @note added in QGIS 2.14
*/
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 the order is ascending, by default nulls are last
* If the 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 );
/**
* Dumps the content to an SQL equivalent
*/
QString dump() const;
};
/**
* Represents a list of OrderByClauses, with the most important first and the least
* important last.
*
* @note added in QGIS 2.14
*/
class OrderBy
{
public:
/**
* Create a new empty order by
*/
OrderBy();
/**
* Create a new order by from a list of clauses
*/
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 ALL_ATTRIBUTES;
//! 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() );
//! copy constructor
QgsFeatureRequest( const QgsFeatureRequest& rh );
~QgsFeatureRequest();
/**
* Return the filter type which is currently set on this request
*
* @return Filter type
*/
FilterType filterType() const;
/**
* Set rectangle from which features will be taken. Empty rectangle removes the filter.
*/
QgsFeatureRequest& setFilterRect( const QgsRectangle& rect );
/**
* Get the rectangle from which features will be taken.
*/
const QgsRectangle& filterRect() const;
//! Set feature ID that should be fetched.
QgsFeatureRequest& setFilterFid( qint64 fid );
//! Get the feature ID that should be fetched.
qint64 filterFid() const;
//! Set feature IDs that should be fetched.
QgsFeatureRequest& setFilterFids( const QgsFeatureIds& fids );
//! Get feature IDs that should be fetched.
const QgsFeatureIds& filterFids() const;
/**
* Sets invalid geometry checking behavior.
* \note Invalid geometry checking is not performed when retrieving features
* directly from a QgsVectorDataProvider.
* \see invalidGeometryCheck()
* \since QGIS 3.0
*/
QgsFeatureRequest &setInvalidGeometryCheck( InvalidGeometryCheck check );
/**
* Returns the invalid geometry checking behavior.
* \see setInvalidGeometryCheck()
* \since QGIS 3.0
*/
InvalidGeometryCheck invalidGeometryCheck() const;
/**
* Sets a callback function to use when encountering an invalid geometry and
* invalidGeometryCheck() is set to GeometryAbortOnInvalid. This function will be
* called using the feature with invalid geometry as a parameter.
* \since QGIS 3.0
* \see invalidGeometryCallback()
*/
QgsFeatureRequest &setInvalidGeometryCallback( SIP_PYCALLABLE /AllowNone/ );
%MethodCode
Py_BEGIN_ALLOW_THREADS
sipCpp->setInvalidGeometryCallback([a0](const QgsFeature &arg) {
SIP_BLOCK_THREADS
Py_XDECREF( sipCallMethod(NULL, a0, "N", new QgsFeature( arg ), sipType_QgsFeature, NULL) );
SIP_UNBLOCK_THREADS
});
sipRes = sipCpp;
Py_END_ALLOW_THREADS
%End
/**
* Returns the callback function to use when encountering an invalid geometry and
* invalidGeometryCheck() is set to GeometryAbortOnInvalid.
* \since QGIS 3.0
* \note not available in Python bindings
* \see setInvalidGeometryCallback()
*/
// std::function< void( const QgsFeature & ) > invalidGeometryCallback() 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
* @see filterExpression
*/
QgsExpressionContext* expressionContext();
/** Sets the expression context used to evaluate filter expressions.
* @note added in QGIS 2.12
* @see expressionContext
* @see setFilterExpression
*/
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, 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
*
* @note 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
*
* @note 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.
*
* @note added in 2.14
*/
QgsFeatureRequest::OrderBy orderBy() const;
/**
* Set a list of order by clauses.
*
* @note added in 2.14
*/
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 );
/**
* Return the subset of attributes which at least need to be fetched
* @return A list of attributes to be fetched
*/
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();
/**
* Get an iterator for features matching the specified request
* @param request The request
* @return A feature iterator
*/
virtual QgsFeatureIterator getFeatures( const QgsFeatureRequest& request = QgsFeatureRequest() ) = 0;
protected:
void iteratorOpened( QgsAbstractFeatureIterator* it );
void iteratorClosed( QgsAbstractFeatureIterator* it );
};