1/************************************************************************ 2 * This file has been generated automatically from * 3 * * 4 * src/core/qgsfeaturerequest.h * 5 * * 6 * Do not edit manually ! Edit header and run scripts/sipify.pl again * 7 ************************************************************************/ 8 9 10 11 12 13class QgsFeatureRequest 14{ 15%Docstring 16This class wraps a request for features to a vector layer (or directly its vector data provider). 17 18The request may apply a filter to fetch only a particular subset of features. Currently supported filters: 19 20- no filter - all features are returned 21- feature id - only feature that matches given feature id is returned 22- feature ids - only features that match any of the given feature ids are returned 23- filter expression - only features that match the given filter expression are returned 24 25Additionally a spatial rectangle can be set in combination: 26Only features that intersect given rectangle should be fetched. For the sake of speed, 27the intersection is often done only using feature's bounding box. There is a flag 28ExactIntersect that makes sure that only intersecting features will be returned. 29 30For efficiency, it is also possible to tell provider that some data is not required: 31 32- NoGeometry flag 33- SubsetOfAttributes flag 34- SimplifyMethod for geometries to fetch 35 36The options may be chained, e.g.: 37 38.. code-block:: python 39 40 QgsFeatureRequest().setFilterRect(QgsRectangle(0,0,1,1)).setFlags(QgsFeatureRequest.ExactIntersect) 41 42Examples: 43 44.. code-block:: python 45 46 # fetch all features: 47 QgsFeatureRequest() 48 # fetch all features, only one attribute 49 QgsFeatureRequest().setSubsetOfAttributes(['myfield'], layer.fields()) 50 # fetch all features, without geometries 51 QgsFeatureRequest().setFlags(QgsFeatureRequest.NoGeometry) 52 # fetch only features from particular extent 53 QgsFeatureRequest().setFilterRect(QgsRectangle(0,0,1,1)) 54 # fetch only one feature 55 QgsFeatureRequest().setFilterFid(45) 56%End 57 58%TypeHeaderCode 59#include "qgsfeaturerequest.h" 60%End 61 public: 62 enum Flag 63 { 64 NoFlags, 65 NoGeometry, 66 SubsetOfAttributes, 67 ExactIntersect 68 }; 69 typedef QFlags<QgsFeatureRequest::Flag> Flags; 70 71 72 enum FilterType 73 { 74 FilterNone, 75 FilterFid, 76 FilterExpression, 77 FilterFids 78 }; 79 80 enum InvalidGeometryCheck 81 { 82 GeometryNoCheck, 83 GeometrySkipInvalid, 84 GeometryAbortOnInvalid, 85 }; 86 87 class OrderByClause 88{ 89%Docstring 90The OrderByClause class represents an order by clause for a QgsFeatureRequest. 91 92It can be a simple field or an expression. Multiple order by clauses can be added to 93a QgsFeatureRequest to fine tune the behavior if a single field or expression is not 94enough to completely specify the required behavior. 95 96If expression compilation is activated in the settings and the expression can be 97translated for the provider in question, it will be evaluated on provider side. 98If one of these two premises does not apply, the ordering will take place locally 99which results in increased memory and CPU usage. 100 101If the ordering is done on strings, the order depends on the system's locale if the 102local fallback implementation is used. The order depends on the server system's locale 103and implementation if ordering is done on the server. 104 105In case the fallback code needs to be used, a limit set on the request will be respected 106for the features returned by the iterator but internally all features will be requested 107from the provider. 108 109.. versionadded:: 2.14 110%End 111 112%TypeHeaderCode 113#include "qgsfeaturerequest.h" 114%End 115 public: 116 117 OrderByClause( const QString &expression, bool ascending = true ); 118%Docstring 119Creates a new OrderByClause for a :py:class:`QgsFeatureRequest` 120 121:param expression: The expression to use for ordering 122:param ascending: If the order should be ascending (1,2,3) or descending (3,2,1) 123 If the order is ascending, by default nulls are last 124 If the order is descending, by default nulls are first 125%End 126 127 OrderByClause( const QString &expression, bool ascending, bool nullsfirst ); 128%Docstring 129Creates a new OrderByClause for a :py:class:`QgsFeatureRequest` 130 131:param expression: The expression to use for ordering 132:param ascending: If the order should be ascending (1,2,3) or descending (3,2,1) 133:param nullsfirst: If ``True``, NULLS are at the beginning, if ``False``, NULLS are at the end 134%End 135 136 OrderByClause( const QgsExpression &expression, bool ascending = true ); 137%Docstring 138Creates a new OrderByClause for a :py:class:`QgsFeatureRequest` 139 140:param expression: The expression to use for ordering 141:param ascending: If the order should be ascending (1,2,3) or descending (3,2,1) 142 If the order is ascending, by default nulls are last 143 If the order is descending, by default nulls are first 144%End 145 146 OrderByClause( const QgsExpression &expression, bool ascending, bool nullsfirst ); 147%Docstring 148Creates a new OrderByClause for a :py:class:`QgsFeatureRequest` 149 150:param expression: The expression to use for ordering 151:param ascending: If the order should be ascending (1,2,3) or descending (3,2,1) 152:param nullsfirst: If ``True``, NULLS are at the beginning, if ``False``, NULLS are at the end 153%End 154 155 QgsExpression expression() const; 156%Docstring 157The expression 158 159:return: the expression 160%End 161 162 bool prepare( QgsExpressionContext *context ); 163%Docstring 164Prepare the expression with the given context. 165 166.. seealso:: :py:func:`QgsExpression.prepare` 167 168.. versionadded:: 3.0 169%End 170 171 bool ascending() const; 172%Docstring 173Order ascending 174 175:return: If ascending order is requested 176%End 177 178 void setAscending( bool ascending ); 179%Docstring 180Set if ascending order is requested 181%End 182 183 bool nullsFirst() const; 184%Docstring 185Set if NULLS should be returned first 186 187:return: if NULLS should be returned first 188%End 189 190 void setNullsFirst( bool nullsFirst ); 191%Docstring 192Set if NULLS should be returned first 193%End 194 195 QString dump() const; 196%Docstring 197Dumps the content to an SQL equivalent 198%End 199 200 201 }; 202 203 204 class OrderBy 205{ 206%Docstring 207Represents a list of OrderByClauses, with the most important first and the least 208important last. 209 210.. versionadded:: 2.14 211%End 212 213%TypeHeaderCode 214#include "qgsfeaturerequest.h" 215%End 216 public: 217 218 OrderBy(); 219%Docstring 220Create a new empty order by 221%End 222 223 OrderBy( const QList<QgsFeatureRequest::OrderByClause> &other ); 224%Docstring 225Create a new order by from a list of clauses 226%End 227 228 QList<QgsFeatureRequest::OrderByClause> list() const; 229%Docstring 230Gets a copy as a list of OrderByClauses 231 232This is only required in Python where the inheritance 233is not properly propagated and this makes it usable. 234%End 235 236 void save( QDomElement &elem ) const; 237%Docstring 238Serialize to XML 239%End 240 241 void load( const QDomElement &elem ); 242%Docstring 243Deserialize from XML 244%End 245 246 QSet<QString> usedAttributes() const; 247%Docstring 248Returns a set of used attributes 249 250.. note:: 251 252 The returned attributes names are NOT guaranteed to be valid. 253%End 254 255 QSet<int> usedAttributeIndices( const QgsFields &fields ) const; 256%Docstring 257Returns a set of used, validated attribute indices 258 259.. versionadded:: 3.8 260%End 261 262 QString dump() const; 263%Docstring 264Dumps the content to an SQL equivalent syntax 265%End 266 }; 267 268 static const QString ALL_ATTRIBUTES; 269 270 QgsFeatureRequest(); 271%Docstring 272construct a default request: for all features get attributes and geometries 273%End 274 explicit QgsFeatureRequest( QgsFeatureId fid ); 275%Docstring 276construct a request with feature ID filter 277%End 278 explicit QgsFeatureRequest( const QgsFeatureIds &fids ); 279%Docstring 280construct a request with feature ID filter 281%End 282 283 explicit QgsFeatureRequest( const QgsRectangle &rectangle ); 284%Docstring 285Construct a request with ``rectangle`` bounding box filter. 286 287When a destination CRS is set using :py:func:`~QgsFeatureRequest.setDestinationCrs`, ``rectangle`` 288is expected to be in the same CRS as the :py:func:`~QgsFeatureRequest.destinationCrs`. Otherwise, ``rectangle`` 289should use the same CRS as the source layer/provider. 290%End 291 292 explicit QgsFeatureRequest( const QgsExpression &expr, const QgsExpressionContext &context = QgsExpressionContext() ); 293%Docstring 294construct a request with a filter expression 295%End 296 QgsFeatureRequest( const QgsFeatureRequest &rh ); 297%Docstring 298copy constructor 299%End 300 301 FilterType filterType() const; 302%Docstring 303Returns the filter type which is currently set on this request 304 305:return: Filter type 306%End 307 308 QgsFeatureRequest &setFilterRect( const QgsRectangle &rectangle ); 309%Docstring 310Sets the ``rectangle`` from which features will be taken. An empty rectangle removes the filter. 311 312When a destination CRS is set using :py:func:`~QgsFeatureRequest.setDestinationCrs`, ``rectangle`` 313is expected to be in the same CRS as the :py:func:`~QgsFeatureRequest.destinationCrs`. Otherwise, ``rectangle`` 314should use the same CRS as the source layer/provider. 315 316.. seealso:: :py:func:`filterRect` 317%End 318 319 const QgsRectangle &filterRect() const; 320%Docstring 321Returns the rectangle from which features will be taken. If the returned 322rectangle is null, then no filter rectangle is set. 323 324When a destination CRS is set using :py:func:`~QgsFeatureRequest.setDestinationCrs`, the rectangle 325will be in the same CRS as the :py:func:`~QgsFeatureRequest.destinationCrs`. Otherwise, the rectangle 326will use the same CRS as the source layer/provider. 327 328.. seealso:: :py:func:`setFilterRect` 329%End 330 331 QgsFeatureRequest &setFilterFid( QgsFeatureId fid ); 332%Docstring 333Sets feature ID that should be fetched. 334%End 335 QgsFeatureId filterFid() const; 336%Docstring 337Gets the feature ID that should be fetched. 338%End 339 340 QgsFeatureRequest &setFilterFids( const QgsFeatureIds &fids ); 341%Docstring 342Sets feature IDs that should be fetched. 343%End 344 const QgsFeatureIds &filterFids() const; 345%Docstring 346Gets feature IDs that should be fetched. 347%End 348 349 QgsFeatureRequest &setInvalidGeometryCheck( InvalidGeometryCheck check ); 350%Docstring 351Sets invalid geometry checking behavior. 352 353.. note:: 354 355 Invalid geometry checking is not performed when retrieving features 356 directly from a :py:class:`QgsVectorDataProvider`. 357 358.. seealso:: :py:func:`invalidGeometryCheck` 359 360.. versionadded:: 3.0 361%End 362 363 InvalidGeometryCheck invalidGeometryCheck() const; 364%Docstring 365Returns the invalid geometry checking behavior. 366 367.. seealso:: :py:func:`setInvalidGeometryCheck` 368 369.. versionadded:: 3.0 370%End 371 372 QgsFeatureRequest &setInvalidGeometryCallback( SIP_PYCALLABLE / AllowNone / ); 373%Docstring 374Sets a callback function to use when encountering an invalid geometry and 375:py:func:`~QgsFeatureRequest.invalidGeometryCheck` is set to GeometryAbortOnInvalid or GeometrySkipInvalid. This function will be 376called using the feature with invalid geometry as a parameter. 377 378.. seealso:: :py:func:`invalidGeometryCallback` 379 380.. versionadded:: 3.0 381%End 382%MethodCode 383 Py_BEGIN_ALLOW_THREADS 384 385 sipCpp->setInvalidGeometryCallback( [a0]( const QgsFeature &arg ) 386 { 387 SIP_BLOCK_THREADS 388 Py_XDECREF( sipCallMethod( NULL, a0, "D", &arg, sipType_QgsFeature, NULL ) ); 389 SIP_UNBLOCK_THREADS 390 } ); 391 392 sipRes = sipCpp; 393 394 Py_END_ALLOW_THREADS 395%End 396 397 398 QgsFeatureRequest &setFilterExpression( const QString &expression ); 399%Docstring 400Set the filter expression. {:py:class:`QgsExpression`} 401 402:param expression: expression string 403 404.. seealso:: :py:func:`filterExpression` 405 406.. seealso:: :py:func:`setExpressionContext` 407%End 408 409 QgsExpression *filterExpression() const; 410%Docstring 411Returns the filter expression if set. 412 413.. seealso:: :py:func:`setFilterExpression` 414 415.. seealso:: :py:func:`expressionContext` 416%End 417 418 QgsFeatureRequest &combineFilterExpression( const QString &expression ); 419%Docstring 420Modifies the existing filter expression to add an additional expression filter. The 421filter expressions are combined using AND, so only features matching both 422the existing expression and the additional expression will be returned. 423 424.. versionadded:: 2.14 425%End 426 427 QgsExpressionContext *expressionContext(); 428%Docstring 429Returns the expression context used to evaluate filter expressions. 430 431.. seealso:: :py:func:`setExpressionContext` 432 433.. seealso:: :py:func:`filterExpression` 434 435.. versionadded:: 2.12 436%End 437 438 QgsFeatureRequest &setExpressionContext( const QgsExpressionContext &context ); 439%Docstring 440Sets the expression context used to evaluate filter expressions. 441 442.. seealso:: :py:func:`expressionContext` 443 444.. seealso:: :py:func:`setFilterExpression` 445 446.. versionadded:: 2.12 447%End 448 449 QgsFeatureRequest &disableFilter(); 450%Docstring 451Disables filter conditions. 452The spatial filter (filterRect) will be kept in place. 453 454:return: The object the method is called on for chaining 455 456.. versionadded:: 2.12 457%End 458 459 460 QgsFeatureRequest &addOrderBy( const QString &expression, bool ascending = true ); 461%Docstring 462Adds a new OrderByClause, appending it as the least important one. 463 464:param expression: The expression to use for ordering 465:param ascending: If the order should be ascending (1,2,3) or descending (3,2,1) 466 If the order is ascending, by default nulls are last 467 If the order is descending, by default nulls are first 468 469.. versionadded:: 2.14 470%End 471 472 QgsFeatureRequest &addOrderBy( const QString &expression, bool ascending, bool nullsfirst ); 473%Docstring 474Adds a new OrderByClause, appending it as the least important one. 475 476:param expression: The expression to use for ordering 477:param ascending: If the order should be ascending (1,2,3) or descending (3,2,1) 478:param nullsfirst: If ``True``, NULLS are at the beginning, if ``False``, NULLS are at the end 479 480.. versionadded:: 2.14 481%End 482 483 OrderBy orderBy() const; 484%Docstring 485Returns a list of order by clauses specified for this feature request. 486 487.. versionadded:: 2.14 488%End 489 490 QgsFeatureRequest &setOrderBy( const OrderBy &orderBy ); 491%Docstring 492Set a list of order by clauses. 493 494.. versionadded:: 2.14 495%End 496 497 QgsFeatureRequest &setLimit( long limit ); 498%Docstring 499Set the maximum number of features to request. 500 501:param limit: maximum number of features, or -1 to request all features. 502 503.. seealso:: :py:func:`limit` 504 505.. versionadded:: 2.14 506%End 507 508 long limit() const; 509%Docstring 510Returns the maximum number of features to request, or -1 if no limit set. 511 512.. seealso:: :py:func:`setLimit` 513 514.. versionadded:: 2.14 515%End 516 517 QgsFeatureRequest &setFlags( QgsFeatureRequest::Flags flags ); 518%Docstring 519Sets flags that affect how features will be fetched 520%End 521 const Flags &flags() const; 522 523 QgsFeatureRequest &setSubsetOfAttributes( const QgsAttributeList &attrs ); 524%Docstring 525Set a subset of attributes that will be fetched. 526 527An empty attributes list indicates that no attributes will be fetched. 528To revert a call to setSubsetOfAttributes and fetch all available attributes, 529the SubsetOfAttributes flag should be removed from the request. 530%End 531 532 QgsFeatureRequest &setNoAttributes(); 533%Docstring 534Set that no attributes will be fetched. 535To revert a call to setNoAttributes and fetch all or some available attributes, 536the SubsetOfAttributes flag should be removed from the request. 537 538.. versionadded:: 3.4 539%End 540 541 QgsAttributeList subsetOfAttributes() const; 542%Docstring 543Returns the subset of attributes which at least need to be fetched 544 545:return: A list of attributes to be fetched 546%End 547 548 QgsFeatureRequest &setSubsetOfAttributes( const QStringList &attrNames, const QgsFields &fields ); 549%Docstring 550Sets a subset of attributes by names that will be fetched 551%End 552 553 QgsFeatureRequest &setSubsetOfAttributes( const QSet<QString> &attrNames, const QgsFields &fields ); 554%Docstring 555Sets a subset of attributes by names that will be fetched 556%End 557 558 QgsFeatureRequest &setSimplifyMethod( const QgsSimplifyMethod &simplifyMethod ); 559%Docstring 560Set a simplification method for geometries that will be fetched 561 562.. versionadded:: 2.2 563%End 564 565 const QgsSimplifyMethod &simplifyMethod() const; 566%Docstring 567Gets simplification method for geometries that will be fetched 568 569.. versionadded:: 2.2 570%End 571 572 QgsCoordinateReferenceSystem destinationCrs() const; 573%Docstring 574Returns the destination coordinate reference system for feature's geometries, 575or an invalid QgsCoordinateReferenceSystem if no reprojection will be done 576and all features will be left with their original geometry. 577 578.. seealso:: :py:func:`setDestinationCrs` 579 580.. seealso:: :py:func:`transformContext` 581 582.. versionadded:: 3.0 583%End 584 585 QgsCoordinateTransformContext transformContext() const; 586%Docstring 587Returns the transform context, for use when a :py:func:`~QgsFeatureRequest.destinationCrs` has been set 588and reprojection is required 589 590.. seealso:: :py:func:`setDestinationCrs` 591 592.. seealso:: :py:func:`destinationCrs` 593 594.. versionadded:: 3.0 595%End 596 597 QgsFeatureRequest &setDestinationCrs( const QgsCoordinateReferenceSystem &crs, const QgsCoordinateTransformContext &context ); 598%Docstring 599Sets the destination ``crs`` for feature's geometries. If set, all 600geometries will be reprojected from their original coordinate reference 601system to this desired reference system. If ``crs`` is an invalid 602QgsCoordinateReferenceSystem then no reprojection will be done 603and all features will be left with their original geometry. 604 605When a ``crs`` is set using :py:func:`~QgsFeatureRequest.setDestinationCrs`, then any :py:func:`~QgsFeatureRequest.filterRect` 606set on the request is expected to be in the same CRS as the destination 607CRS. 608 609The feature geometry transformation to the destination CRS is performed 610after all filter expressions are tested and any virtual fields are 611calculated. Accordingly, any geometric expressions used in 612:py:func:`~QgsFeatureRequest.filterExpression` will be performed in the original 613source CRS. This ensures consistent results are returned regardless of the 614destination CRS. Similarly, virtual field values will be calculated using the 615original geometry in the source CRS, so these values are not affected by 616any destination CRS transform present in the feature request. 617 618.. seealso:: :py:func:`destinationCrs` 619 620.. versionadded:: 3.0 621%End 622 623 QgsFeatureRequest &setTransformErrorCallback( SIP_PYCALLABLE / AllowNone / ); 624%Docstring 625Sets a callback function to use when encountering a transform error when iterating 626features and a :py:func:`~QgsFeatureRequest.destinationCrs` is set. This function will be 627called using the feature which encountered the transform error as a parameter. 628 629.. seealso:: :py:func:`transformErrorCallback` 630 631.. seealso:: :py:func:`setDestinationCrs` 632 633.. versionadded:: 3.0 634%End 635%MethodCode 636 Py_BEGIN_ALLOW_THREADS 637 638 sipCpp->setTransformErrorCallback( [a0]( const QgsFeature &arg ) 639 { 640 SIP_BLOCK_THREADS 641 Py_XDECREF( sipCallMethod( NULL, a0, "D", &arg, sipType_QgsFeature, NULL ) ); 642 SIP_UNBLOCK_THREADS 643 } ); 644 645 sipRes = sipCpp; 646 647 Py_END_ALLOW_THREADS 648%End 649 650 651 652 bool acceptFeature( const QgsFeature &feature ); 653%Docstring 654Check if a feature is accepted by this requests filter 655 656:param feature: The feature which will be tested 657 658:return: ``True``, if the filter accepts the feature 659 660 661.. versionadded:: 2.1 662%End 663 664 int connectionTimeout() const /Deprecated/; 665%Docstring 666Returns the timeout (in milliseconds) for how long we should wait for a connection if none is available from the pool 667at this moment. A negative value (which is set by default) will wait forever. 668 669.. note:: 670 671 Only works if the provider supports this option. 672 673.. deprecated:: 674 Use timeout() instead. 675 676.. versionadded:: 3.0 677%End 678 679 QgsFeatureRequest &setConnectionTimeout( int connectionTimeout ) /Deprecated/; 680%Docstring 681Sets the timeout (in milliseconds) for how long we should wait for a connection if none is available from the pool 682at this moment. A negative value (which is set by default) will wait forever. 683 684.. note:: 685 686 Only works if the provider supports this option. 687 688.. deprecated:: 689 Use setTimeout() instead. 690 691.. versionadded:: 3.0 692%End 693 694 int timeout() const; 695%Docstring 696Returns the timeout (in milliseconds) for the maximum time we should wait during feature requests before a 697feature is returned. A negative value (which is set by default) will wait forever. 698 699.. note:: 700 701 Only works if the provider supports this option. 702 703.. versionadded:: 3.4 704%End 705 706 QgsFeatureRequest &setTimeout( int timeout ); 707%Docstring 708Sets the ``timeout`` (in milliseconds) for the maximum time we should wait during feature requests before a 709feature is returned. A negative value (which is set by default) will wait forever. 710 711.. note:: 712 713 Only works if the provider supports this option. 714 715.. versionadded:: 3.4 716%End 717 718 bool requestMayBeNested() const; 719%Docstring 720In case this request may be run nested within another already running 721iteration on the same connection, set this to ``True``. 722 723If this flag is ``True``, this request will be able to make use of "spare" 724connections to avoid deadlocks. 725 726For example, this should be set on requests that are issued from an 727expression function. 728 729.. versionadded:: 3.4 730%End 731 732 QgsFeatureRequest &setRequestMayBeNested( bool requestMayBeNested ); 733%Docstring 734In case this request may be run nested within another already running 735iteration on the same connection, set this to ``True``. 736 737If this flag is ``True``, this request will be able to make use of "spare" 738connections to avoid deadlocks. 739 740For example, this should be set on requests that are issued from an 741expression function. 742 743.. versionadded:: 3.4 744%End 745 746 protected: 747}; 748 749QFlags<QgsFeatureRequest::Flag> operator|(QgsFeatureRequest::Flag f1, QFlags<QgsFeatureRequest::Flag> f2); 750 751 752 753 754class QgsAbstractFeatureSource 755{ 756%Docstring 757Base class that can be used for any class that is capable of returning features 758 759.. versionadded:: 2.4 760%End 761 762%TypeHeaderCode 763#include "qgsfeaturerequest.h" 764%End 765 public: 766 virtual ~QgsAbstractFeatureSource(); 767 768 769 770 virtual QgsFeatureIterator getFeatures( const QgsFeatureRequest &request = QgsFeatureRequest() ) = 0 /TransferBack/; 771%Docstring 772Gets an iterator for features matching the specified request 773 774:param request: The request 775 776:return: A feature iterator 777%End 778 779 780 protected: 781 void iteratorOpened( QgsAbstractFeatureIterator *it ); 782 void iteratorClosed( QgsAbstractFeatureIterator *it ); 783 784 785}; 786 787/************************************************************************ 788 * This file has been generated automatically from * 789 * * 790 * src/core/qgsfeaturerequest.h * 791 * * 792 * Do not edit manually ! Edit header and run scripts/sipify.pl again * 793 ************************************************************************/ 794