/
qgsfeaturerequest.sip
584 lines (474 loc) · 16.4 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
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
/************************************************************************
* This file has been generated automatically from *
* *
* src/core/qgsfeaturerequest.h *
* *
* Do not edit manually ! Edit header and run scripts/sipify.pl again *
************************************************************************/
class QgsFeatureRequest
{
%Docstring
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:
- 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 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:
- NoGeometry flag
- SubsetOfAttributes flag
- SimplifyMethod for geometries to fetch
The options may be chained, e.g.:
QgsFeatureRequest().setFilterRect(QgsRectangle(0,0,1,1)).setFlags(QgsFeatureRequest.ExactIntersect)
Examples:
- fetch all features:
QgsFeatureRequest()
- fetch all features, only one attribute
QgsFeatureRequest().setSubsetOfAttributes(QStringList("myfield"), provider->fieldMap())
- fetch all features, without geometries
QgsFeatureRequest().setFlags(QgsFeatureRequest.NoGeometry)
- fetch only features from particular extent
QgsFeatureRequest().setFilterRect(QgsRectangle(0,0,1,1))
- fetch only one feature
QgsFeatureRequest().setFilterFid(45)
%End
%TypeHeaderCode
#include "qgsfeaturerequest.h"
%End
public:
enum Flag
{
NoFlags,
NoGeometry,
SubsetOfAttributes,
ExactIntersect
};
typedef QFlags<QgsFeatureRequest::Flag> Flags;
enum FilterType
{
FilterNone,
FilterFid,
FilterExpression,
FilterFids
};
enum InvalidGeometryCheck
{
GeometryNoCheck,
GeometrySkipInvalid,
GeometryAbortOnInvalid,
};
class OrderByClause
{
%Docstring
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.
.. versionadded:: 2.14
%End
%TypeHeaderCode
#include "qgsfeaturerequest.h"
%End
public:
OrderByClause( const QString &expression, bool ascending = true );
%Docstring
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
%End
OrderByClause( const QString &expression, bool ascending, bool nullsfirst );
%Docstring
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
%End
OrderByClause( const QgsExpression &expression, bool ascending = true );
%Docstring
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
%End
OrderByClause( const QgsExpression &expression, bool ascending, bool nullsfirst );
%Docstring
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
%End
QgsExpression expression() const;
%Docstring
The expression
:return: the expression
:rtype: QgsExpression
%End
bool prepare( QgsExpressionContext *context );
%Docstring
Prepare the expression with the given context.
.. seealso:: QgsExpression.prepare
.. versionadded:: 3.0
:rtype: bool
%End
bool ascending() const;
%Docstring
Order ascending
:return: If ascending order is requested
:rtype: bool
%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
:rtype: bool
%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
:rtype: str
%End
};
class OrderBy
{
%Docstring
Represents a list of OrderByClauses, with the most important first and the least
important last.
.. versionadded:: 2.14
%End
%TypeHeaderCode
#include "qgsfeaturerequest.h"
%End
public:
CORE_EXPORT OrderBy();
%Docstring
Create a new empty order by
:rtype: CORE_EXPORT
%End
CORE_EXPORT OrderBy( const QList<QgsFeatureRequest::OrderByClause> &other );
%Docstring
Create a new order by from a list of clauses
:rtype: CORE_EXPORT
%End
QList<QgsFeatureRequest::OrderByClause> CORE_EXPORT list() const;
%Docstring
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.
%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
%End
QString dump() const;
%Docstring
Dumps the content to an SQL equivalent syntax
%End
};
static const QString ALL_ATTRIBUTES;
%Docstring
A special attribute that if set matches all attributes
%End
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 &rect );
%Docstring
construct a request with rectangle filter
%End
explicit QgsFeatureRequest( const QgsExpression &expr, const QgsExpressionContext &context = QgsExpressionContext() );
%Docstring
construct a request with a filter expression
%End
QgsFeatureRequest( const QgsFeatureRequest &rh );
%Docstring
copy constructor
%End
FilterType filterType() const;
%Docstring
Return the filter type which is currently set on this request
:return: Filter type
:rtype: FilterType
%End
QgsFeatureRequest &setFilterRect( const QgsRectangle &rect );
%Docstring
Set rectangle from which features will be taken. Empty rectangle removes the filter.
:rtype: QgsFeatureRequest
%End
const QgsRectangle &filterRect() const;
%Docstring
Get the rectangle from which features will be taken. If the returned
rectangle is null, then no filter rectangle is set.
:rtype: QgsRectangle
%End
QgsFeatureRequest &setFilterFid( QgsFeatureId fid );
%Docstring
Set feature ID that should be fetched.
:rtype: QgsFeatureRequest
%End
QgsFeatureId filterFid() const;
%Docstring
Get the feature ID that should be fetched.
:rtype: QgsFeatureId
%End
QgsFeatureRequest &setFilterFids( const QgsFeatureIds &fids );
%Docstring
Set feature IDs that should be fetched.
:rtype: QgsFeatureRequest
%End
const QgsFeatureIds &filterFids() const;
%Docstring
Get feature IDs that should be fetched.
:rtype: QgsFeatureIds
%End
QgsFeatureRequest &setInvalidGeometryCheck( InvalidGeometryCheck check );
%Docstring
Sets invalid geometry checking behavior.
.. note::
Invalid geometry checking is not performed when retrieving features
directly from a QgsVectorDataProvider.
.. seealso:: invalidGeometryCheck()
.. versionadded:: 3.0
:rtype: QgsFeatureRequest
%End
InvalidGeometryCheck invalidGeometryCheck() const;
%Docstring
Returns the invalid geometry checking behavior.
.. seealso:: setInvalidGeometryCheck()
.. versionadded:: 3.0
:rtype: InvalidGeometryCheck
%End
QgsFeatureRequest &setInvalidGeometryCallback( SIP_PYCALLABLE / AllowNone / );
%Docstring
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.
.. versionadded:: 3.0
.. seealso:: invalidGeometryCallback()
:rtype: QgsFeatureRequest
%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
.. seealso:: QgsExpression}
\param expression expression string
.. seealso:: filterExpression
.. seealso:: setExpressionContext
:rtype: QgsFeatureRequest
%End
QgsExpression *filterExpression() const;
%Docstring
Returns the filter expression if set.
.. seealso:: setFilterExpression
.. seealso:: expressionContext
:rtype: QgsExpression
%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.
.. versionadded:: 2.14
:rtype: QgsFeatureRequest
%End
QgsExpressionContext *expressionContext();
%Docstring
Returns the expression context used to evaluate filter expressions.
.. versionadded:: 2.12
.. seealso:: setExpressionContext
.. seealso:: filterExpression
:rtype: QgsExpressionContext
%End
QgsFeatureRequest &setExpressionContext( const QgsExpressionContext &context );
%Docstring
Sets the expression context used to evaluate filter expressions.
.. versionadded:: 2.12
.. seealso:: expressionContext
.. seealso:: setFilterExpression
:rtype: QgsFeatureRequest
%End
QgsFeatureRequest &disableFilter();
%Docstring
Disables filter conditions.
The spatial filter (filterRect) will be kept in place.
:return: The object the method is called on for chaining
.. versionadded:: 2.12
:rtype: QgsFeatureRequest
%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
.. versionadded:: 2.14
:rtype: QgsFeatureRequest
%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
.. versionadded:: 2.14
:rtype: QgsFeatureRequest
%End
OrderBy orderBy() const;
%Docstring
Return a list of order by clauses specified for this feature request.
.. versionadded:: 2.14
:rtype: OrderBy
%End
QgsFeatureRequest &setOrderBy( const OrderBy &orderBy );
%Docstring
Set a list of order by clauses.
.. versionadded:: 2.14
:rtype: QgsFeatureRequest
%End
QgsFeatureRequest &setLimit( long limit );
%Docstring
Set the maximum number of features to request.
\param limit maximum number of features, or -1 to request all features.
.. seealso:: limit()
.. versionadded:: 2.14
:rtype: QgsFeatureRequest
%End
long limit() const;
%Docstring
Returns the maximum number of features to request, or -1 if no limit set.
.. seealso:: setLimit
.. versionadded:: 2.14
:rtype: long
%End
QgsFeatureRequest &setFlags( QgsFeatureRequest::Flags flags );
%Docstring
Set flags that affect how features will be fetched
:rtype: QgsFeatureRequest
%End
const Flags &flags() const;
%Docstring
:rtype: Flags
%End
QgsFeatureRequest &setSubsetOfAttributes( const QgsAttributeList &attrs );
%Docstring
To disable fetching attributes, reset the FetchAttributes flag (which is set by default)
:rtype: QgsFeatureRequest
%End
QgsAttributeList subsetOfAttributes() const;
%Docstring
Return the subset of attributes which at least need to be fetched
:return: A list of attributes to be fetched
:rtype: QgsAttributeList
%End
QgsFeatureRequest &setSubsetOfAttributes( const QStringList &attrNames, const QgsFields &fields );
%Docstring
Set a subset of attributes by names that will be fetched
:rtype: QgsFeatureRequest
%End
QgsFeatureRequest &setSubsetOfAttributes( const QSet<QString> &attrNames, const QgsFields &fields );
%Docstring
Set a subset of attributes by names that will be fetched
:rtype: QgsFeatureRequest
%End
QgsFeatureRequest &setSimplifyMethod( const QgsSimplifyMethod &simplifyMethod );
%Docstring
.. versionadded:: 2.2
:rtype: QgsFeatureRequest
%End
const QgsSimplifyMethod &simplifyMethod() const;
%Docstring
.. versionadded:: 2.2
:rtype: QgsSimplifyMethod
%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
.. versionadded:: 2.1
:rtype: bool
%End
protected:
};
QFlags<QgsFeatureRequest::Flag> operator|(QgsFeatureRequest::Flag f1, QFlags<QgsFeatureRequest::Flag> f2);
class QgsAbstractFeatureSource
{
%Docstring
Base class that can be used for any class that is capable of returning features
.. versionadded:: 2.4
%End
%TypeHeaderCode
#include "qgsfeaturerequest.h"
%End
public:
virtual ~QgsAbstractFeatureSource();
virtual QgsFeatureIterator getFeatures( const QgsFeatureRequest &request = QgsFeatureRequest() ) = 0;
%Docstring
Get an iterator for features matching the specified request
\param request The request
:return: A feature iterator
:rtype: QgsFeatureIterator
%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.pl again *
************************************************************************/