QGIS API Documentation  2.17.0-Master (8784312)
Public Types | Signals | Public Member Functions | Protected Member Functions | Protected Attributes | List of all members
QgsDataProvider Class Referenceabstract

Abstract base class for spatial data provider implementations. More...

#include <qgsdataprovider.h>

Inheritance diagram for QgsDataProvider:
Inheritance graph
[legend]

Public Types

enum  DataCapability {
  NoDataCapabilities = 0, File = 1, Dir = 1 << 1, Database = 1 << 2,
  Net = 1 << 3
}
 
enum  ProviderProperty { EvaluateDefaultValues, CustomData = 3000 }
 Properties are used to pass custom configuration options into data providers. More...
 

Signals

void dataChanged ()
 This is emitted whenever an asynchronous operation has finished and the data should be redrawn. More...
 
void dataChanged (int changed)
 This is emitted whenever data or metadata (e.g. More...
 
void fullExtentCalculated ()
 This is emitted whenever the worker thread has fully calculated the PostGIS extents for this layer, and its event has been received by this provider. More...
 

Public Member Functions

 QgsDataProvider (QString const &uri="")
 
virtual ~QgsDataProvider ()
 We need this so the subclass destructors get called. More...
 
virtual QgsCoordinateReferenceSystem crs ()=0
 Get the QgsCoordinateReferenceSystem for this layer. More...
 
virtual QString dataSourceUri (bool expandAuthConfig=false) const
 Get the data source specification. More...
 
virtual QDateTime dataTimestamp () const
 Current time stamp of data source. More...
 
virtual QString description () const =0
 Return description. More...
 
virtual bool enterUpdateMode ()
 Enter update mode. More...
 
virtual QgsError error () const
 Get current status error. More...
 
virtual QgsRectangle extent ()=0
 Get the extent of the layer. More...
 
virtual QString fileRasterFilters () const
 Return raster file filter string. More...
 
virtual QString fileVectorFilters () const
 Return vector file filter string. More...
 
virtual void invalidateConnections (const QString &connection)
 Invalidate connections corresponding to specified name. More...
 
virtual bool isValid ()=0
 Returns true if this is a valid layer. More...
 
virtual bool leaveUpdateMode ()
 Leave update mode. More...
 
virtual QString name () const =0
 Return a provider name. More...
 
QVariant providerProperty (ProviderProperty property, const QVariant &defaultValue=QVariant()) const
 Get the current value of a certain provider property. More...
 
QVariant providerProperty (int property, const QVariant &defaultValue) const
 Get the current value of a certain provider property. More...
 
virtual void reloadData ()
 Reloads the data from the source. More...
 
virtual void setDataSourceUri (const QString &uri)
 Set the data source specification. More...
 
virtual void setLayerOrder (const QStringList &layers)
 Reorder the list of layer names to be rendered by this provider (in order from bottom to top) More...
 
void setProviderProperty (ProviderProperty property, const QVariant &value)
 Allows setting arbitrary properties on the provider. More...
 
void setProviderProperty (int property, const QVariant &value)
 Allows setting arbitrary properties on the provider. More...
 
virtual void setSubLayerVisibility (const QString &name, bool vis)
 Set the visibility of the given sublayer name. More...
 
virtual bool setSubsetString (const QString &subset, bool updateFeatureCount=true)
 Set the subset string used to create a subset of features in the layer. More...
 
virtual uint subLayerCount () const
 return the number of layers for the current data source More...
 
virtual QStringList subLayers () const
 Sub-layers handled by this provider, in order from bottom to top. More...
 
virtual QStringList subLayerStyles () const
 Sub-layer styles for each sub-layer handled by this provider, in order from bottom to top. More...
 
virtual QString subsetString ()
 Returns the subset definition string (typically sql) currently in use by the layer and used by the provider to limit the feature set. More...
 
virtual bool supportsSubsetString ()
 Provider supports setting of subset strings. More...
 
virtual QDateTime timestamp () const
 Time stamp of data source in the moment when data/metadata were loaded by provider. More...
 
virtual void updateExtents ()
 Update the extents of the layer. More...
 
- Public Member Functions inherited from QObject
 QObject (QObject *parent)
 
 QObject (QObject *parent, const char *name)
 
virtual  ~QObject ()
 
bool blockSignals (bool block)
 
QObjectchild (const char *objName, const char *inheritsClass, bool recursiveSearch) const
 
const QObjectList & children () const
 
const char * className () const
 
bool connect (const QObject *sender, const char *signal, const char *method, Qt::ConnectionType type) const
 
void deleteLater ()
 
void destroyed (QObject *obj)
 
bool disconnect (const QObject *receiver, const char *method)
 
bool disconnect (const char *signal, const QObject *receiver, const char *method)
 
void dumpObjectInfo ()
 
void dumpObjectTree ()
 
QList< QByteArraydynamicPropertyNames () const
 
virtual bool event (QEvent *e)
 
virtual bool eventFilter (QObject *watched, QEvent *event)
 
findChild (const QString &name) const
 
QList< T > findChildren (const QRegExp &regExp) const
 
QList< T > findChildren (const QString &name) const
 
bool inherits (const char *className) const
 
void insertChild (QObject *object)
 
void installEventFilter (QObject *filterObj)
 
bool isA (const char *className) const
 
bool isWidgetType () const
 
void killTimer (int id)
 
virtual const QMetaObjectmetaObject () const
 
void moveToThread (QThread *targetThread)
 
const char * name () const
 
const char * name (const char *defaultName) const
 
QString objectName () const
 
QObjectparent () const
 
QVariant property (const char *name) const
 
void removeChild (QObject *object)
 
void removeEventFilter (QObject *obj)
 
void setName (const char *name)
 
void setObjectName (const QString &name)
 
void setParent (QObject *parent)
 
bool setProperty (const char *name, const QVariant &value)
 
bool signalsBlocked () const
 
int startTimer (int interval)
 
QThreadthread () const
 

Protected Member Functions

void appendError (const QgsErrorMessage &theMessage)
 Add error message. More...
 
void setError (const QgsError &theError)
 Set error message. More...
 
- Protected Member Functions inherited from QObject
bool checkConnectArgs (const char *signal, const QObject *object, const char *method)
 
virtual void childEvent (QChildEvent *event)
 
virtual void connectNotify (const char *signal)
 
virtual void customEvent (QEvent *event)
 
virtual void disconnectNotify (const char *signal)
 
int receivers (const char *signal) const
 
QObjectsender () const
 
int senderSignalIndex () const
 
virtual void timerEvent (QTimerEvent *event)
 

Protected Attributes

QgsError mError
 Error. More...
 
QDateTime mTimestamp
 Timestamp of data in the moment when the data were loaded by provider. More...
 

Additional Inherited Members

- Static Public Member Functions inherited from QObject
bool connect (const QObject *sender, const char *signal, const QObject *receiver, const char *method, Qt::ConnectionType type)
 
bool connect (const QObject *sender, const QMetaMethod &signal, const QObject *receiver, const QMetaMethod &method, Qt::ConnectionType type)
 
bool disconnect (const QObject *sender, const char *signal, const QObject *receiver, const char *method)
 
bool disconnect (const QObject *sender, const QMetaMethod &signal, const QObject *receiver, const QMetaMethod &method)
 
QString tr (const char *sourceText, const char *disambiguation, int n)
 
QString trUtf8 (const char *sourceText, const char *disambiguation, int n)
 
- Static Protected Member Functions inherited from QObject
QByteArray normalizeSignalSlot (const char *signalSlot)
 
- Properties inherited from QObject
 objectName
 

Detailed Description

Abstract base class for spatial data provider implementations.

Author
Gary E.Sherman

This object needs to inherit from QObject to enable event processing in the Postgres/PostGIS provider (QgsPostgresProvider). It is called here so that this vtable and the vtable for QgsPostgresProvider don't get misaligned - the QgsVectorLayer class factory (which refers to generic QgsVectorDataProvider's) depends on it.

Definition at line 47 of file qgsdataprovider.h.

Member Enumeration Documentation

Enumerator
NoDataCapabilities 
File 
Dir 
Database 
Net 

Definition at line 55 of file qgsdataprovider.h.

Properties are used to pass custom configuration options into data providers.

This enum defines a list of custom properties which can be used on different providers. It depends on the provider, which properties are supported. In addition to these default properties, providers can add their custom properties starting from CustomData.

Enumerator
EvaluateDefaultValues 

Evaluate default values on provider side when calling QgsVectorDataProvider::defaultValue( int index ) rather than on commit.

CustomData 

Custom properties for 3rd party providers or very provider-specific properties which are not expected to be of interest for other providers can be added starting from this value up.

Definition at line 71 of file qgsdataprovider.h.

Constructor & Destructor Documentation

QgsDataProvider::QgsDataProvider ( QString const &  uri = "")
inline

Definition at line 77 of file qgsdataprovider.h.

virtual QgsDataProvider::~QgsDataProvider ( )
inlinevirtual

We need this so the subclass destructors get called.

Definition at line 84 of file qgsdataprovider.h.

Member Function Documentation

void QgsDataProvider::appendError ( const QgsErrorMessage theMessage)
inlineprotected

Add error message.

Definition at line 434 of file qgsdataprovider.h.

virtual QgsCoordinateReferenceSystem QgsDataProvider::crs ( )
pure virtual

Get the QgsCoordinateReferenceSystem for this layer.

Note
Must be reimplemented by each provider. If the provider isn't capable of returning its projection an empty srs will be return, ti will return 0
void QgsDataProvider::dataChanged ( )
signal

This is emitted whenever an asynchronous operation has finished and the data should be redrawn.

When emitted from a QgsVectorDataProvider, any cached information such as feature ids should be invalidated.

void QgsDataProvider::dataChanged ( int  changed)
signal

This is emitted whenever data or metadata (e.g.

color table, extent) has changed

Parameters
changedbinary combination of changes
virtual QString QgsDataProvider::dataSourceUri ( bool  expandAuthConfig = false) const
inlinevirtual

Get the data source specification.

This may be a path or database connection string

Parameters
expandAuthConfigWhether to expand any assigned authentication configuration
Returns
data source specification
Note
The default authentication configuration expansion is FALSE. This keeps credentials out of layer data source URIs and project files. Expansion should be specifically done only when needed within a provider

Definition at line 114 of file qgsdataprovider.h.

virtual QDateTime QgsDataProvider::dataTimestamp ( ) const
inlinevirtual

Current time stamp of data source.

Reimplemented in QgsRasterDataProvider.

Definition at line 314 of file qgsdataprovider.h.

virtual QString QgsDataProvider::description ( ) const
pure virtual

Return description.

Return a terse string describing what the provider is.

Note

Instead of being pure virtual, might be better to generalize this behavior and presume that none of the sub-classes are going to do anything strange with regards to their name or description?

virtual bool QgsDataProvider::enterUpdateMode ( )
inlinevirtual

Enter update mode.

This is aimed at providers that can open differently the connection to the datasource, according it to be in update mode or in read-only mode. A call to this method shall be balanced with a call to leaveUpdateMode(), if this method returns true.

Most providers will have an empty implementation for that method.

For backward compatibility, providers that implement enterUpdateMode() should still make sure to allow editing operations to work even if enterUpdateMode() is not explicitly called.

Several successive calls to enterUpdateMode() can be done. So there is a concept of stack of calls that must be handled by the provider. Only the first call to enterUpdateMode() will really turn update mode on.

Returns
true in case of success (or no-op implementation), false in case of failure.
Note
added in QGIS 2.16

Definition at line 348 of file qgsdataprovider.h.

virtual QgsError QgsDataProvider::error ( ) const
inlinevirtual

Get current status error.

This error describes some principal problem for which provider cannot work and thus is not valid. It is not last error after accessing data by block(), identify() etc.

Definition at line 320 of file qgsdataprovider.h.

virtual QgsRectangle QgsDataProvider::extent ( )
pure virtual

Get the extent of the layer.

Returns
QgsRectangle containing the extent of the layer

Implemented in QgsRasterDataProvider.

virtual QString QgsDataProvider::fileRasterFilters ( ) const
inlinevirtual

Return raster file filter string.

Returns a string suitable for a QFileDialog of raster file formats supported by the data provider. Naturally this will be an empty string for those data providers that do not deal with plain files, such as databases and servers.

Note
It'd be nice to eventually be raster/vector neutral.

Definition at line 300 of file qgsdataprovider.h.

virtual QString QgsDataProvider::fileVectorFilters ( ) const
inlinevirtual

Return vector file filter string.

Returns a string suitable for a QFileDialog of vector file formats supported by the data provider. Naturally this will be an empty string for those data providers that do not deal with plain files, such as databases and servers.

Note
It'd be nice to eventually be raster/vector neutral.

Definition at line 285 of file qgsdataprovider.h.

void QgsDataProvider::fullExtentCalculated ( )
signal

This is emitted whenever the worker thread has fully calculated the PostGIS extents for this layer, and its event has been received by this provider.

virtual void QgsDataProvider::invalidateConnections ( const QString connection)
inlinevirtual

Invalidate connections corresponding to specified name.

Note
added in QGIS 2.16

Definition at line 325 of file qgsdataprovider.h.

virtual bool QgsDataProvider::isValid ( )
pure virtual

Returns true if this is a valid layer.

It is up to individual providers to determine what constitutes a valid layer

virtual bool QgsDataProvider::leaveUpdateMode ( )
inlinevirtual

Leave update mode.

This is aimed at providers that can open differently the connection to the datasource, according it to be in update mode or in read-only mode. This method shall be balanced with a successful call to enterUpdateMode().

Most providers will have an empty implementation for that method.

Several successive calls to enterUpdateMode() can be done. So there is a concept of stack of calls that must be handled by the provider. Only the last call to leaveUpdateMode() will really turn update mode off.

Returns
true in case of success (or no-op implementation), false in case of failure.
Note
added in QGIS 2.16

Definition at line 366 of file qgsdataprovider.h.

virtual QString QgsDataProvider::name ( ) const
pure virtual

Return a provider name.

Essentially just returns the provider key. Should be used to build file dialogs so that providers can be shown with their supported types. Thus if more than one provider supports a given format, the user is able to select a specific provider to open that file.

Note

Instead of being pure virtual, might be better to generalize this behavior and presume that none of the sub-classes are going to do anything strange with regards to their name or description?

QVariant QgsDataProvider::providerProperty ( QgsDataProvider::ProviderProperty  property,
const QVariant defaultValue = QVariant() 
) const

Get the current value of a certain provider property.

It depends on the provider which properties are supported.

Note
added in 2.16

Definition at line 29 of file qgsdataprovider.cpp.

QVariant QgsDataProvider::providerProperty ( int  property,
const QVariant defaultValue = QVariant() 
) const

Get the current value of a certain provider property.

It depends on the provider which properties are supported.

Note
added in 2.16

Definition at line 34 of file qgsdataprovider.cpp.

virtual void QgsDataProvider::reloadData ( )
inlinevirtual

Reloads the data from the source.

Needs to be implemented by providers with data caches to synchronize with changes in the data source

Definition at line 308 of file qgsdataprovider.h.

virtual void QgsDataProvider::setDataSourceUri ( const QString uri)
inlinevirtual

Set the data source specification.

This may be a path or database connection string

Parameters
urisource specification

Definition at line 100 of file qgsdataprovider.h.

void QgsDataProvider::setError ( const QgsError theError)
inlineprotected

Set error message.

Definition at line 437 of file qgsdataprovider.h.

virtual void QgsDataProvider::setLayerOrder ( const QStringList layers)
inlinevirtual

Reorder the list of layer names to be rendered by this provider (in order from bottom to top)

Note
layers must have been previously added.

Definition at line 220 of file qgsdataprovider.h.

void QgsDataProvider::setProviderProperty ( QgsDataProvider::ProviderProperty  property,
const QVariant value 
)

Allows setting arbitrary properties on the provider.

It depends on the provider which properties are supported.

Note
added in 2.16

Definition at line 19 of file qgsdataprovider.cpp.

void QgsDataProvider::setProviderProperty ( int  property,
const QVariant value 
)

Allows setting arbitrary properties on the provider.

It depends on the provider which properties are supported.

Note
added in 2.16

Definition at line 24 of file qgsdataprovider.cpp.

virtual void QgsDataProvider::setSubLayerVisibility ( const QString name,
bool  vis 
)
inlinevirtual

Set the visibility of the given sublayer name.

Definition at line 234 of file qgsdataprovider.h.

virtual bool QgsDataProvider::setSubsetString ( const QString subset,
bool  updateFeatureCount = true 
)
inlinevirtual

Set the subset string used to create a subset of features in the layer.

This may be a sql where clause or any other string that can be used by the data provider to create a subset. Must be implemented in the dataprovider.

Definition at line 157 of file qgsdataprovider.h.

virtual uint QgsDataProvider::subLayerCount ( ) const
inlinevirtual

return the number of layers for the current data source

Definition at line 209 of file qgsdataprovider.h.

virtual QStringList QgsDataProvider::subLayers ( ) const
inlinevirtual

Sub-layers handled by this provider, in order from bottom to top.

Sub-layers are used when the provider's source can combine layers it knows about in some way before it hands them off to the provider.

Reimplemented in QgsRasterDataProvider.

Definition at line 187 of file qgsdataprovider.h.

virtual QStringList QgsDataProvider::subLayerStyles ( ) const
inlinevirtual

Sub-layer styles for each sub-layer handled by this provider, in order from bottom to top.

Sub-layer styles are used to abstract the way the provider's source can symbolise layers in some way at the server, before it serves them to the provider.

Definition at line 200 of file qgsdataprovider.h.

virtual QString QgsDataProvider::subsetString ( )
inlinevirtual

Returns the subset definition string (typically sql) currently in use by the layer and used by the provider to limit the feature set.

Must be overridden in the dataprovider, otherwise returns a null QString.

Definition at line 175 of file qgsdataprovider.h.

virtual bool QgsDataProvider::supportsSubsetString ( )
inlinevirtual

Provider supports setting of subset strings.

Definition at line 167 of file qgsdataprovider.h.

virtual QDateTime QgsDataProvider::timestamp ( ) const
inlinevirtual

Time stamp of data source in the moment when data/metadata were loaded by provider.

Reimplemented in QgsRasterDataProvider.

Definition at line 311 of file qgsdataprovider.h.

virtual void QgsDataProvider::updateExtents ( )
inlinevirtual

Update the extents of the layer.

Not implemented by default

Definition at line 145 of file qgsdataprovider.h.

Member Data Documentation

QgsError QgsDataProvider::mError
protected

Error.

Definition at line 431 of file qgsdataprovider.h.

QDateTime QgsDataProvider::mTimestamp
protected

Timestamp of data in the moment when the data were loaded by provider.

Definition at line 428 of file qgsdataprovider.h.


The documentation for this class was generated from the following files: