1/************************************************************************ 2 * This file has been generated automatically from * 3 * * 4 * src/core/vector/qgsvectorlayerutils.h * 5 * * 6 * Do not edit manually ! Edit header and run scripts/sipify.pl again * 7 ************************************************************************/ 8 9 10 11 12 13class QgsVectorLayerUtils 14{ 15%Docstring(signature="appended") 16Contains utility methods for working with :py:class:`QgsVectorLayers`. 17 18.. versionadded:: 3.0 19%End 20 21%TypeHeaderCode 22#include "qgsvectorlayerutils.h" 23%End 24 public: 25 26 class QgsDuplicateFeatureContext 27{ 28%Docstring(signature="appended") 29Contains mainly the QMap with :py:class:`QgsVectorLayer` and :py:class:`QgsFeatureIds` do list all the duplicated features 30 31.. versionadded:: 3.0 32%End 33 34%TypeHeaderCode 35#include "qgsvectorlayerutils.h" 36%End 37 public: 38 39 QgsDuplicateFeatureContext(); 40%Docstring 41Constructor for QgsDuplicateFeatureContext 42%End 43 44 QList<QgsVectorLayer *> layers() const; 45%Docstring 46Returns all the layers on which features have been duplicated 47 48.. versionadded:: 3.0 49%End 50 51 QgsFeatureIds duplicatedFeatures( QgsVectorLayer *layer ) const; 52%Docstring 53Returns the duplicated features in the given layer 54 55.. versionadded:: 3.0 56%End 57 58 59 }; 60 61 class QgsFeatureData 62{ 63%Docstring(signature="appended") 64Encapsulate geometry and attributes for new features, to be passed to createFeatures 65 66.. seealso:: :py:func:`createFeatures` 67 68.. versionadded:: 3.6 69%End 70 71%TypeHeaderCode 72#include "qgsvectorlayerutils.h" 73%End 74 public: 75 76 QgsFeatureData( const QgsGeometry &geometry = QgsGeometry(), const QgsAttributeMap &attributes = QgsAttributeMap() ); 77%Docstring 78Constructs a new QgsFeatureData with given ``geometry`` and ``attributes`` 79%End 80 81 QgsGeometry geometry() const; 82%Docstring 83Returns geometry 84%End 85 86 QgsAttributeMap attributes() const; 87%Docstring 88Returns attributes 89%End 90 91 }; 92 93 typedef QList<QgsVectorLayerUtils::QgsFeatureData> QgsFeaturesDataList; 94 95 static QgsFeatureIterator getValuesIterator( const QgsVectorLayer *layer, const QString &fieldOrExpression, bool &ok, bool selectedOnly ); 96%Docstring 97Create a feature iterator for a specified field name or expression. 98 99:param layer: vector layer to retrieve values from 100:param fieldOrExpression: field name or an expression string 101:param ok: will be set to ``False`` if field or expression is invalid, otherwise ``True`` 102:param selectedOnly: set to ``True`` to get values from selected features only 103 104:return: feature iterator 105 106.. versionadded:: 3.0 107%End 108 109 static QList< QVariant > getValues( const QgsVectorLayer *layer, const QString &fieldOrExpression, bool &ok, bool selectedOnly = false, QgsFeedback *feedback = 0 ); 110%Docstring 111Fetches all values from a specified field name or expression. 112 113:param layer: vector layer to retrieve values from 114:param fieldOrExpression: field name or an expression string 115:param ok: will be set to ``False`` if field or expression is invalid, otherwise ``True`` 116:param selectedOnly: set to ``True`` to get values from selected features only 117:param feedback: optional feedback object to allow cancellation 118 119:return: list of fetched values 120 121.. seealso:: :py:func:`getDoubleValues` 122 123.. versionadded:: 3.0 124%End 125 126 static QList< double > getDoubleValues( const QgsVectorLayer *layer, const QString &fieldOrExpression, bool &ok, bool selectedOnly = false, int *nullCount = 0, QgsFeedback *feedback = 0 ); 127%Docstring 128Fetches all double values from a specified field name or expression. Null values or 129invalid expression results are skipped. 130 131:param layer: vector layer to retrieve values from 132:param fieldOrExpression: field name or an expression string evaluating to a double value 133:param ok: will be set to ``False`` if field or expression is invalid, otherwise ``True`` 134:param selectedOnly: set to ``True`` to get values from selected features only 135:param nullCount: optional pointer to integer to store number of null values encountered in 136:param feedback: optional feedback object to allow cancellation 137 138:return: list of fetched values 139 140.. seealso:: :py:func:`getValues` 141 142.. versionadded:: 3.0 143%End 144 145 static bool valueExists( const QgsVectorLayer *layer, int fieldIndex, const QVariant &value, const QgsFeatureIds &ignoreIds = QgsFeatureIds() ); 146%Docstring 147Returns ``True`` if the specified value already exists within a field. This method can be used to test for uniqueness 148of values inside a layer's attributes. An optional list of ignored feature IDs can be provided, if so, any features 149with IDs within this list are ignored when testing for existence of the value. 150 151.. seealso:: :py:func:`createUniqueValue` 152%End 153 154 static QVariant createUniqueValue( const QgsVectorLayer *layer, int fieldIndex, const QVariant &seed = QVariant() ); 155%Docstring 156Returns a new attribute value for the specified field index which is guaranteed to be unique. The optional seed 157value can be used as a basis for generated values. 158 159.. seealso:: :py:func:`valueExists` 160%End 161 162 static QVariant createUniqueValueFromCache( const QgsVectorLayer *layer, int fieldIndex, const QSet<QVariant> &existingValues, const QVariant &seed = QVariant() ); 163%Docstring 164Returns a new attribute value for the specified field index which is guaranteed to 165be unique within regard to ``existingValues``. 166The optional seed value can be used as a basis for generated values. 167 168.. versionadded:: 3.6 169%End 170 171 static bool validateAttribute( const QgsVectorLayer *layer, const QgsFeature &feature, int attributeIndex, QStringList &errors /Out/, 172 QgsFieldConstraints::ConstraintStrength strength = QgsFieldConstraints::ConstraintStrengthNotSet, 173 QgsFieldConstraints::ConstraintOrigin origin = QgsFieldConstraints::ConstraintOriginNotSet ); 174%Docstring 175Tests a feature attribute value to check whether it passes all constraints which are present on the corresponding field. 176Returns ``True`` if the attribute value is valid for the field. Any constraint failures will be reported in the errors argument. 177If the strength or origin parameter is set then only constraints with a matching strength/origin will be checked. 178%End 179 180 static QgsFeature createFeature( const QgsVectorLayer *layer, 181 const QgsGeometry &geometry = QgsGeometry(), 182 const QgsAttributeMap &attributes = QgsAttributeMap(), 183 QgsExpressionContext *context = 0 ); 184%Docstring 185Creates a new feature ready for insertion into a layer. Default values and constraints 186(e.g., unique constraints) will automatically be handled. An optional attribute map can be 187passed for the new feature to copy as many attribute values as possible from the map, 188assuming that they respect the layer's constraints. Note that the created feature is not 189automatically inserted into the layer. 190 191.. seealso:: :py:func:`createFeatures` 192%End 193 194 static QgsFeatureList createFeatures( const QgsVectorLayer *layer, 195 const QgsFeaturesDataList &featuresData, 196 QgsExpressionContext *context = 0 ); 197%Docstring 198Creates a set of new features ready for insertion into a layer. Default values and constraints 199(e.g., unique constraints) will automatically be handled. Note that the created features are not 200automatically inserted into the layer. 201 202.. seealso:: :py:func:`createFeature` 203 204.. versionadded:: 3.6 205%End 206 207 static QgsFeature duplicateFeature( QgsVectorLayer *layer, const QgsFeature &feature, QgsProject *project, QgsDuplicateFeatureContext &duplicateFeatureContext /Out/, const int maxDepth = 0 ); 208%Docstring 209Duplicates a feature and it's children (one level deep). It calls CreateFeature, so 210default values and constraints (e.g., unique constraints) will automatically be handled. 211The duplicated feature will be automatically inserted into the layer. 212``duplicateFeatureContext`` stores all the layers and the featureids of the duplicated features (incl. children) 213``maxDepth`` the maximum depth to duplicate children in relations, 0 is unlimited depth (in any case, limited to 100) 214``depth`` the current depth, not exposed in Python 215``referencedLayersBranch`` the current branch of layers across the relations, not exposed in Python, taken by copy not reference, used to avoid infinite loop 216 217.. versionadded:: 3.0 218%End 219 220 221 222 static void matchAttributesToFields( QgsFeature &feature, const QgsFields &fields ); 223%Docstring 224Matches the attributes in ``feature`` to the specified ``fields``. 225 226This causes the attributes contained within the given ``feature`` to be rearranged (or in 227some cases dropped) in order to match the fields and order indicated by ``fields``. 228 229The exact behavior depends on whether or not ``feature`` has a valid fields container 230set (see :py:func:`QgsFeature.fields()`). If a fields container is set, then the names of the 231feature's fields are matched to ``fields``. In this case attributes from ``feature`` 232will be rearranged or dropped in order to match the field names from ``fields``. 233 234If the ``feature`` does not have a valid fields container set, then the feature's attributes 235are simply truncated to match the number of fields present in ``fields`` (or if 236less attributes are present in ``feature`` than in ``fields``, the feature's attributes 237are padded with NULL values to match the required length). 238Finally, the feature's fields are set to ``fields``. 239 240.. versionadded:: 3.4 241%End 242 243 static QgsFeatureList makeFeatureCompatible( const QgsFeature &feature, const QgsVectorLayer *layer, QgsFeatureSink::SinkFlags sinkFlags = QgsFeatureSink::SinkFlags() ); 244%Docstring 245Converts input ``feature`` to be compatible with the given ``layer``. 246 247This function returns a new list of transformed features compatible with the input 248layer, note that the number of features returned might be greater than one when 249converting a multi part geometry to single part 250 251The following operations will be performed to convert the input features: 252 253- convert single geometries to multi part 254- drop additional attributes 255- drop geometry if layer is geometry-less 256- add missing attribute fields 257- add back M/Z values (initialized to 0) 258- drop Z/M 259- convert multi part geometries to single part 260 261Optionally, ``sinkFlags`` can be specified to further refine the compatibility logic. 262 263.. versionadded:: 3.4 264%End 265 266 static QgsFeatureList makeFeaturesCompatible( const QgsFeatureList &features, const QgsVectorLayer *layer, QgsFeatureSink::SinkFlags sinkFlags = QgsFeatureSink::SinkFlags() ); 267%Docstring 268Converts input ``features`` to be compatible with the given ``layer``. 269 270This function returns a new list of transformed features compatible with the input 271layer, note that the number of features returned might be greater than the number 272of input features. 273 274The following operations will be performed to convert the input features: 275 276- convert single geometries to multi part 277- drop additional attributes 278- drop geometry if layer is geometry-less 279- add missing attribute fields 280- add back M/Z values (initialized to 0) 281- drop Z/M 282- convert multi part geometries to single part 283 284Optionally, ``sinkFlags`` can be specified to further refine the compatibility logic. 285 286.. versionadded:: 3.4 287%End 288 289 static bool fieldIsEditable( const QgsVectorLayer *layer, int fieldIndex, const QgsFeature &feature ); 290%Docstring 291Tests whether a field is editable for a particular ``feature``. 292 293:return: ``True`` if the field at index ``fieldIndex`` from ``layer`` 294 is editable, ``False`` if the field is read only. 295 296.. versionadded:: 3.10 297%End 298 299 static bool fieldIsReadOnly( const QgsVectorLayer *layer, int fieldIndex ); 300%Docstring 301 302:return: ``True`` if the field at index ``fieldIndex`` from ``layer`` 303 is editable, ``False`` if the field is read only. 304 305If this function returns ``True`` then the editability of the field may still vary feature by 306feature. See :py:func:`~QgsVectorLayerUtils.fieldIsEditable` to determine this on a feature by feature basis. 307 308.. versionadded:: 3.18 309%End 310 311 static bool fieldEditabilityDependsOnFeature( const QgsVectorLayer *layer, int fieldIndex ); 312%Docstring 313Returns ``True`` if the editability of the field at index ``fieldIndex`` from ``layer`` may vary 314feature by feature. 315 316I.e. if the field is taken from a joined layer, the value may or may not be editable for any individual 317feature depending on the join's "upsert on edit" capabilities. 318 319.. versionadded:: 3.18 320%End 321 322 323 324 static QString getFeatureDisplayString( const QgsVectorLayer *layer, const QgsFeature &feature ); 325%Docstring 326 327:return: a descriptive string for a ``feature``, suitable for displaying to the user. 328 The definition is taken from the ``displayExpression`` property of ``layer``. 329 330.. versionadded:: 3.12 331%End 332 333 enum CascadedFeatureFlag 334 { 335 IgnoreAuxiliaryLayers, 336 }; 337 typedef QFlags<QgsVectorLayerUtils::CascadedFeatureFlag> CascadedFeatureFlags; 338 339 340 static bool impactsCascadeFeatures( const QgsVectorLayer *layer, const QgsFeatureIds &fids, const QgsProject *project, QgsDuplicateFeatureContext &context /Out/, QgsVectorLayerUtils::CascadedFeatureFlags flags = QgsVectorLayerUtils::CascadedFeatureFlags() ); 341%Docstring 342 343:return: ``True`` if at least one feature of the ``fids`` on ``layer`` is connected as parent in at 344 least one composition relation of the ``project`` or contains joins, where cascade delete is set. 345 Details about cascading effects will be written to ``context``. 346 347.. versionadded:: 3.14 348%End 349 350 351 static QString guessFriendlyIdentifierField( const QgsFields &fields, bool *foundFriendly /Out/ = 0 ) /PyName=guessFriendlyIdentifierFieldV2/; 352%Docstring 353Given a set of fields, attempts to pick the "most useful" field 354for user-friendly identification of features. 355 356For instance, if a field called "name" is present, this will be returned. 357 358Assumes that the user has organized the data with the more "interesting" field 359names first. As such, "name" would be selected before "oldname", "othername", etc. 360 361If no friendly identifier is found, the function will fallback to the 362first available. 363 364:param fields: list of fields to pick a friendly identifier from 365 366:return: - field name 367 - foundFriendly: set to ``True`` if the returned field name is a friendly identifier 368 369.. versionadded:: 3.22 370%End 371 372 373 static QString guessFriendlyIdentifierField( const QgsFields &fields ); 374%Docstring 375Given a set of fields, attempts to pick the "most useful" field 376for user-friendly identification of features. 377 378For instance, if a field called "name" is present, this will be returned. 379 380Assumes that the user has organized the data with the more "interesting" field 381names first. As such, "name" would be selected before "oldname", "othername", etc. 382 383If no friendly identifier is found, the function will fallback to the 384first available. 385 386:param fields: list of fields to pick a friendly identifier from 387 388:return: field name 389 390.. versionadded:: 3.18 391%End 392 393}; 394 395 396/************************************************************************ 397 * This file has been generated automatically from * 398 * * 399 * src/core/vector/qgsvectorlayerutils.h * 400 * * 401 * Do not edit manually ! Edit header and run scripts/sipify.pl again * 402 ************************************************************************/ 403