Quantum GIS API Documentation  1.7.4
Classes | Public Types | Public Member Functions | Static Public Member Functions | Static Public Attributes | Protected Member Functions | Protected Attributes | Private Attributes | Static Private Attributes
QgsVectorDataProvider Class Reference

This is the base class for vector data providers. More...

#include <qgsvectordataprovider.h>

Inheritance diagram for QgsVectorDataProvider:
Inheritance graph
[legend]
Collaboration diagram for QgsVectorDataProvider:
Collaboration graph
[legend]

List of all members.

Classes

struct  NativeType

Public Types

enum  Capability {
  NoCapabilities = 0, AddFeatures = 1, DeleteFeatures = 1 << 1, ChangeAttributeValues = 1 << 2,
  AddAttributes = 1 << 3, DeleteAttributes = 1 << 4, SaveAsShapefile = 1 << 5, CreateSpatialIndex = 1 << 6,
  SelectAtId = 1 << 7, ChangeGeometries = 1 << 8, SelectGeometryAtId = 1 << 9, RandomSelectGeometryAtId = 1 << 10,
  SequentialSelectGeometryAtId = 1 << 11, CreateAttributeIndex = 1 << 12, SetEncoding = 1 << 13
}
 enumeration with capabilities that providers might implement More...

Public Member Functions

 QgsVectorDataProvider (QString uri=QString())
 Constructor of the vector provider.
virtual ~QgsVectorDataProvider ()
 Destructor.
virtual QString storageType () const
 Returns the permanent storage type for this layer as a friendly name.
virtual void select (QgsAttributeList fetchAttributes=QgsAttributeList(), QgsRectangle rect=QgsRectangle(), bool fetchGeometry=true, bool useIntersect=false)=0
 Select features based on a bounding rectangle.
virtual long updateFeatureCount ()
 This function does nothing useful, it's kept only for compatibility.
virtual bool featureAtId (int featureId, QgsFeature &feature, bool fetchGeometry=true, QgsAttributeList fetchAttributes=QgsAttributeList())
 Gets the feature at the given feature ID.
virtual bool nextFeature (QgsFeature &feature)=0
 Get the next feature resulting from a select operation.
virtual QGis::WkbType geometryType () const =0
 Get feature type.
virtual long featureCount () const =0
 Number of features in the layer.
virtual uint fieldCount () const =0
 Number of attribute fields for a feature in the layer.
virtual const QgsFieldMapfields () const =0
 Return a map of indexes with field names for this layer.
virtual QString dataComment () const
 Return a short comment for the data that this provider is providing access to (e.g.
virtual void rewind ()=0
 Restart reading features from previous select operation.
virtual QVariant minimumValue (int index)
 Returns the minimum value of an attribute.
virtual QVariant maximumValue (int index)
 Returns the maximum value of an attribute.
virtual void uniqueValues (int index, QList< QVariant > &uniqueValues, int limit=-1)
 Return unique values of an attribute.
virtual void enumValues (int index, QStringList &enumList)
 Returns the possible enum values of an attribute.
virtual bool addFeatures (QgsFeatureList &flist)
 Adds a list of features.
virtual bool deleteFeatures (const QgsFeatureIds &id)
 Deletes one or more features.
virtual bool addAttributes (const QList< QgsField > &attributes)
 Adds new attributes.
virtual Q_DECL_DEPRECATED bool addAttributes (const QMap< QString, QString > &attributes)
 Add new attributes.
virtual bool deleteAttributes (const QgsAttributeIds &attributes)
 Deletes existing attributes.
virtual bool changeAttributeValues (const QgsChangedAttributesMap &attr_map)
 Changes attribute values of existing features.
virtual QVariant defaultValue (int fieldId)
 Returns the default value for field specified by fieldId.
virtual bool changeGeometryValues (QgsGeometryMap &geometry_map)
 Changes geometries of existing features.
virtual bool createSpatialIndex ()
 Creates a spatial index on the datasource (if supported by the provider type).
virtual bool createAttributeIndex (int field)
 Create an attribute index on the datasource.
virtual int capabilities () const
 Returns a bitmask containing the supported capabilities Note, some capabilities may change depending on whether a spatial filter is active on this provider, so it may be prudent to check this value per intended operation.
QString capabilitiesString () const
 Returns the above in friendly format.
virtual void setEncoding (const QString &e)
 Set encoding used for accessing data from layer.
QString encoding () const
 Get encoding which is used for accessing data.
int fieldNameIndex (const QString &fieldName) const
 Returns the index of a field name or -1 if the field does not exist.
QMap< QString, int > fieldNameMap () const
 Return a map where the key is the name of the field and the value is its index.
virtual QgsAttributeList attributeIndexes ()
 Return list of indexes to fetch all attributes in nextFeature()
void enableGeometrylessFeatures (bool fetch)
 Set whether provider should also return features that don't have associated geometry.
bool supportedType (const QgsField &field) const
 check if provider supports type of field
const QList< NativeType > & nativeTypes () const
 Returns the names of the supported types.
Q_DECL_DEPRECATED const QMap
< QString, QVariant::Type > & 
supportedNativeTypes () const
 Returns the names of the supported types.
virtual bool doesStrictFeatureTypeCheck () const
 Returns true if the provider is strict about the type of inserted features (e.g.
bool hasErrors ()
void clearErrors ()
QStringList errors ()

Static Public Member Functions

static const QStringList & availableEncodings ()

Static Public Attributes

static const int EditingCapabilities
 bitmask of all provider's editing capabilities

Protected Member Functions

QVariant convertValue (QVariant::Type type, QString value)
void clearMinMaxCache ()
void fillMinMaxCache ()
void pushError (QString msg)

Protected Attributes

bool mCacheMinMaxDirty
QMap< int, QVariant > mCacheMinValues
QMap< int, QVariant > mCacheMaxValues
QTextCodec * mEncoding
 Encoding.
bool mFetchFeaturesWithoutGeom
 should provider fetch also features that don't have geometry?
bool mFetchGeom
 True if geometry should be added to the features in nextFeature calls.
QgsAttributeList mAttributesToFetch
 List of attribute indices to fetch with nextFeature calls.
QList< NativeTypemNativeTypes
 The names of the providers native types.

Private Attributes

QMap< QString, QVariant::Type > mOldTypeList
 old notation
QStringList mErrors

Static Private Attributes

static QStringList smEncodings

Detailed Description

This is the base class for vector data providers.

Data providers abstract the retrieval and writing (where supported) of feature and attribute information from a spatial datasource.

Definition at line 44 of file qgsvectordataprovider.h.


Member Enumeration Documentation

enumeration with capabilities that providers might implement

Enumerator:
NoCapabilities 

provider has no capabilities

AddFeatures 

allows adding features

DeleteFeatures 

allows deletion of features

ChangeAttributeValues 

allows modification of attribute values

AddAttributes 

allows addition of new attributes (fields)

DeleteAttributes 

allows deletion of attributes (fields)

SaveAsShapefile 

DEPRECATED - do not use.

CreateSpatialIndex 

allows creation of spatial index

SelectAtId 

fast access to features using their ID

ChangeGeometries 

allows modifications of geometries

SelectGeometryAtId 

DEPRECATED - do not use.

RandomSelectGeometryAtId 

DEPRECATED - do not use.

SequentialSelectGeometryAtId 

DEPRECATED - do not use.

CreateAttributeIndex 
SetEncoding 

Uses mEncoding for conversion of 8-bit strings to unicode.

Definition at line 54 of file qgsvectordataprovider.h.


Constructor & Destructor Documentation

QgsVectorDataProvider::QgsVectorDataProvider ( QString  uri = QString())

Constructor of the vector provider.

Parameters:
uriuniform resource locator (URI) for a dataset

Definition at line 28 of file qgsvectordataprovider.cpp.

References setEncoding().

Destructor.

Definition at line 38 of file qgsvectordataprovider.cpp.


Member Function Documentation

bool QgsVectorDataProvider::addAttributes ( const QList< QgsField > &  attributes) [virtual]

Adds new attributes.

Parameters:
attributeslist of new attributes
Returns:
true in case of success and false in case of failure
Note:
added in 1.2

Definition at line 83 of file qgsvectordataprovider.cpp.

Referenced by addAttributes(), QgsZonalStatistics::calculateStatistics(), and QgsVectorLayer::commitChanges().

bool QgsVectorDataProvider::addAttributes ( const QMap< QString, QString > &  attributes) [virtual]

Add new attributes.

Parameters:
attributesmap of attributes name as key and type as value
Returns:
true in case of success and false in case of failure
Deprecated:

Definition at line 88 of file qgsvectordataprovider.cpp.

References addAttributes(), and nativeTypes().

Adds a list of features.

Returns:
true in case of success and false in case of failure

Definition at line 73 of file qgsvectordataprovider.cpp.

Referenced by QgsVectorLayer::commitChanges().

Return list of indexes to fetch all attributes in nextFeature()

Definition at line 255 of file qgsvectordataprovider.cpp.

References fieldCount().

Referenced by QgsVectorLayer::featureAtId(), QgsMapTip::fetchFeature(), and QgsVectorLayer::selectedFeatures().

const QStringList & QgsVectorDataProvider::availableEncodings ( ) [static]

Definition at line 449 of file qgsvectordataprovider.cpp.

References smEncodings.

Referenced by QgsEncodingFileDialog::QgsEncodingFileDialog().

int QgsVectorDataProvider::capabilities ( ) const [virtual]

Returns a bitmask containing the supported capabilities Note, some capabilities may change depending on whether a spatial filter is active on this provider, so it may be prudent to check this value per intended operation.

Definition at line 138 of file qgsvectordataprovider.cpp.

References NoCapabilities.

Referenced by QgsVectorLayer::addFeature(), QgsVectorLayer::addFeatures(), capabilitiesString(), QgsVectorLayer::commitChanges(), QgsVectorLayer::deleteSelectedFeatures(), and QgsVectorLayer::startEditing().

Changes attribute values of existing features.

Parameters:
attr_mapa map containing changed attributes
Returns:
true in case of success and false in case of failure

Definition at line 113 of file qgsvectordataprovider.cpp.

Referenced by QgsZonalStatistics::calculateStatistics(), and QgsVectorLayer::commitChanges().

bool QgsVectorDataProvider::changeGeometryValues ( QgsGeometryMap geometry_map) [virtual]

Changes geometries of existing features.

Parameters:
geometry_mapA QgsGeometryMap whose index contains the feature IDs that will have their geometries changed. The second map parameter being the new geometries themselves
Returns:
True in case of success and false in case of failure

Definition at line 123 of file qgsvectordataprovider.cpp.

Referenced by QgsVectorLayer::commitChanges().

Definition at line 503 of file qgsvectordataprovider.cpp.

References mErrors.

Definition at line 364 of file qgsvectordataprovider.cpp.

References mCacheMinMaxDirty.

QVariant QgsVectorDataProvider::convertValue ( QVariant::Type  type,
QString  value 
) [protected]

Definition at line 439 of file qgsvectordataprovider.cpp.

bool QgsVectorDataProvider::createAttributeIndex ( int  field) [virtual]

Create an attribute index on the datasource.

Definition at line 133 of file qgsvectordataprovider.cpp.

Creates a spatial index on the datasource (if supported by the provider type).

Returns:
true in case of success

Definition at line 128 of file qgsvectordataprovider.cpp.

QString QgsVectorDataProvider::dataComment ( ) const [virtual]

Return a short comment for the data that this provider is providing access to (e.g.

the comment for postgres table).

Definition at line 68 of file qgsvectordataprovider.cpp.

Referenced by QgsVectorLayer::dataComment().

QVariant QgsVectorDataProvider::defaultValue ( int  fieldId) [virtual]

Returns the default value for field specified by fieldId.

Definition at line 118 of file qgsvectordataprovider.cpp.

bool QgsVectorDataProvider::deleteAttributes ( const QgsAttributeIds attributes) [virtual]

Deletes existing attributes.

Parameters:
attributesa set containing names of attributes
Returns:
true in case of success and false in case of failure

Definition at line 108 of file qgsvectordataprovider.cpp.

Referenced by QgsVectorLayer::commitChanges().

bool QgsVectorDataProvider::deleteFeatures ( const QgsFeatureIds id) [virtual]

Deletes one or more features.

Parameters:
idlist containing feature ids to delete
Returns:
true in case of success and false in case of failure

Definition at line 78 of file qgsvectordataprovider.cpp.

Referenced by QgsVectorLayer::commitChanges().

virtual bool QgsVectorDataProvider::doesStrictFeatureTypeCheck ( ) const [inline, virtual]

Returns true if the provider is strict about the type of inserted features (e.g.

no multipolygon in a polygon layer)

Note:
: added in version 1.4

Definition at line 362 of file qgsvectordataprovider.h.

Set whether provider should also return features that don't have associated geometry.

false by default

Definition at line 266 of file qgsvectordataprovider.cpp.

References mFetchFeaturesWithoutGeom.

virtual void QgsVectorDataProvider::enumValues ( int  index,
QStringList &  enumList 
) [inline, virtual]

Returns the possible enum values of an attribute.

Returns an empty stringlist if a provider does not support enum types or if the given attribute is not an enum type.

Parameters:
indexthe index of the attribute
enumListreference to the list to fill
Note:
: added in version 1.2

Definition at line 218 of file qgsvectordataprovider.h.

Referenced by QgsAttributeEditor::createAttributeEditor().

Definition at line 513 of file qgsvectordataprovider.cpp.

References mErrors.

bool QgsVectorDataProvider::featureAtId ( int  featureId,
QgsFeature feature,
bool  fetchGeometry = true,
QgsAttributeList  fetchAttributes = QgsAttributeList() 
) [virtual]

Gets the feature at the given feature ID.

Parameters:
featureIdof the feature to be returned
featurewhich will receive the data
fetchGeometryflag which if true, will cause the geometry to be fetched from the provider
fetchAttributesa list containing the indexes of the attribute fields to copy
Returns:
True when feature was found, otherwise false

Default implementation traverses all features until it finds the one with correct ID. In case the provider supports reading the feature directly, override this function.

Definition at line 52 of file qgsvectordataprovider.cpp.

References QgsFeature::id(), nextFeature(), and select().

Referenced by QgsVectorLayer::featureAtId(), QgsVectorLayer::nextFeature(), QgsVectorLayer::selectedFeatures(), QgsVectorLayer::translateFeature(), and QgsVectorLayer::undoEditCommand().

virtual long QgsVectorDataProvider::featureCount ( ) const [pure virtual]

Number of features in the layer.

Returns:
long containing number of features

Referenced by QgsZonalStatistics::calculateStatistics(), QgsVectorLayer::featureCount(), QgsVectorLayer::pendingFeatureCount(), and QgsVectorLayer::updateExtents().

virtual uint QgsVectorDataProvider::fieldCount ( ) const [pure virtual]

Number of attribute fields for a feature in the layer.

Referenced by attributeIndexes().

int QgsVectorDataProvider::fieldNameIndex ( const QString &  fieldName) const

Returns the index of a field name or -1 if the field does not exist.

Definition at line 227 of file qgsvectordataprovider.cpp.

References fields().

Referenced by QgsZonalStatistics::calculateStatistics(), QgsUniqueValueRenderer::readXML(), and QgsContinuousColorRenderer::readXML().

QMap< QString, int > QgsVectorDataProvider::fieldNameMap ( ) const

Return a map where the key is the name of the field and the value is its index.

Definition at line 241 of file qgsvectordataprovider.cpp.

References fields().

virtual const QgsFieldMap& QgsVectorDataProvider::fields ( ) const [pure virtual]
virtual QGis::WkbType QgsVectorDataProvider::geometryType ( ) const [pure virtual]

Definition at line 508 of file qgsvectordataprovider.cpp.

References mErrors.

QVariant QgsVectorDataProvider::maximumValue ( int  index) [virtual]

Returns the maximum value of an attribute.

Parameters:
indexthe index of the attribute

Default implementation walks all numeric attributes and caches minimal and maximal values. If provider has facilities to retrieve maximal value directly, override this function.

Definition at line 325 of file qgsvectordataprovider.cpp.

References fields(), fillMinMaxCache(), mCacheMaxValues, and QgsDebugMsg.

Referenced by QgsVectorLayer::maximumValue().

QVariant QgsVectorDataProvider::minimumValue ( int  index) [virtual]

Returns the minimum value of an attribute.

Parameters:
indexthe index of the attribute

Default implementation walks all numeric attributes and caches minimal and maximal values. If provider has facilities to retrieve minimal value directly, override this function.

Definition at line 309 of file qgsvectordataprovider.cpp.

References fields(), fillMinMaxCache(), mCacheMinValues, and QgsDebugMsg.

Referenced by QgsVectorLayer::minimumValue().

Returns the names of the supported types.

Note:
added in 1.2

Definition at line 271 of file qgsvectordataprovider.cpp.

References mNativeTypes.

Referenced by QgsVectorLayer::addAttribute(), addAttributes(), and supportedNativeTypes().

virtual bool QgsVectorDataProvider::nextFeature ( QgsFeature feature) [pure virtual]

Get the next feature resulting from a select operation.

Parameters:
featurefeature which will receive data from the provider
Returns:
true when there was a feature to fetch, false when end was hit

Referenced by QgsInterpolator::cacheBaseData(), QgsZonalStatistics::calculateStatistics(), featureAtId(), QgsMapTip::fetchFeature(), fillMinMaxCache(), and uniqueValues().

void QgsVectorDataProvider::pushError ( QString  msg) [protected]

Definition at line 518 of file qgsvectordataprovider.cpp.

References mErrors.

virtual void QgsVectorDataProvider::rewind ( ) [pure virtual]

Restart reading features from previous select operation.

virtual void QgsVectorDataProvider::select ( QgsAttributeList  fetchAttributes = QgsAttributeList(),
QgsRectangle  rect = QgsRectangle(),
bool  fetchGeometry = true,
bool  useIntersect = false 
) [pure virtual]

Select features based on a bounding rectangle.

Features can be retrieved with calls to nextFeature.

Parameters:
fetchAttributeslist of attributes which should be fetched
rectspatial filter
fetchGeometrytrue if the feature geometry should be fetched
useIntersecttrue if an accurate intersection test should be used, false if a test based on bounding box is sufficient

Referenced by QgsInterpolator::cacheBaseData(), QgsZonalStatistics::calculateStatistics(), featureAtId(), QgsMapTip::fetchFeature(), fillMinMaxCache(), QgsVectorLayer::select(), and uniqueValues().

void QgsVectorDataProvider::setEncoding ( const QString &  e) [virtual]

Set encoding used for accessing data from layer.

Definition at line 144 of file qgsvectordataprovider.cpp.

References mEncoding, and QgsDebugMsg.

Referenced by QgsVectorDataProvider(), QgsVectorLayer::readXml(), and QgsVectorLayer::setProviderEncoding().

QString QgsVectorDataProvider::storageType ( ) const [virtual]

Returns the permanent storage type for this layer as a friendly name.

Definition at line 42 of file qgsvectordataprovider.cpp.

Referenced by QgsVectorLayer::storageType().

const QMap< QString, QVariant::Type > & QgsVectorDataProvider::supportedNativeTypes ( ) const

Returns the names of the supported types.

Deprecated:
use nativeTypes()

Definition at line 276 of file qgsvectordataprovider.cpp.

References mOldTypeList, and nativeTypes().

bool QgsVectorDataProvider::supportedType ( const QgsField field) const

check if provider supports type of field

Note:
added in 1.2

Definition at line 293 of file qgsvectordataprovider.cpp.

References QgsField::length(), mNativeTypes, QgsField::precision(), and QgsField::type().

Referenced by QgsVectorLayer::addAttribute().

void QgsVectorDataProvider::uniqueValues ( int  index,
QList< QVariant > &  uniqueValues,
int  limit = -1 
) [virtual]

Return unique values of an attribute.

Parameters:
indexthe index of the attribute
uniqueValuesvalues reference to the list to fill
limitmaxmum number of the values to return (added in 1.4)

Default implementation simply iterates the features

Definition at line 341 of file qgsvectordataprovider.cpp.

References QgsFeature::attributeMap(), nextFeature(), and select().

Referenced by QgsAttributeEditor::createAttributeEditor(), and QgsVectorLayer::uniqueValues().

This function does nothing useful, it's kept only for compatibility.

Todo:
to be removed

Definition at line 47 of file qgsvectordataprovider.cpp.


Member Data Documentation

Initial value:

bitmask of all provider's editing capabilities

Definition at line 88 of file qgsvectordataprovider.h.

Referenced by QgsVectorLayer::startEditing().

List of attribute indices to fetch with nextFeature calls.

Definition at line 402 of file qgsvectordataprovider.h.

QMap<int, QVariant> QgsVectorDataProvider::mCacheMaxValues [protected]

Definition at line 390 of file qgsvectordataprovider.h.

Referenced by fillMinMaxCache(), and maximumValue().

Definition at line 389 of file qgsvectordataprovider.h.

Referenced by clearMinMaxCache(), and fillMinMaxCache().

QMap<int, QVariant> QgsVectorDataProvider::mCacheMinValues [protected]

Definition at line 390 of file qgsvectordataprovider.h.

Referenced by fillMinMaxCache(), and minimumValue().

QTextCodec* QgsVectorDataProvider::mEncoding [protected]

Encoding.

Definition at line 393 of file qgsvectordataprovider.h.

Referenced by encoding(), and setEncoding().

QStringList QgsVectorDataProvider::mErrors [private]

Definition at line 414 of file qgsvectordataprovider.h.

Referenced by clearErrors(), errors(), hasErrors(), and pushError().

should provider fetch also features that don't have geometry?

Definition at line 396 of file qgsvectordataprovider.h.

Referenced by enableGeometrylessFeatures().

True if geometry should be added to the features in nextFeature calls.

Definition at line 399 of file qgsvectordataprovider.h.

The names of the providers native types.

Definition at line 405 of file qgsvectordataprovider.h.

Referenced by nativeTypes(), and supportedType().

QMap<QString, QVariant::Type> QgsVectorDataProvider::mOldTypeList [private]

old notation

Definition at line 411 of file qgsvectordataprovider.h.

Referenced by supportedNativeTypes().

QStringList QgsVectorDataProvider::smEncodings [static, private]

Definition at line 417 of file qgsvectordataprovider.h.

Referenced by availableEncodings().


The documentation for this class was generated from the following files:
 All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Defines