QGIS API Documentation  2.0.1-Dufour
 All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Properties Friends Macros Groups Pages
Public Types | Signals | Public Member Functions | Static Public Member Functions | Static Private Member Functions | List of all members
QgsApplication Class Reference

Extends QApplication to provide access to QGIS specific resources such as theme paths, database paths etc. More...

#include <qgsapplication.h>

Public Types

enum  ENDIAN { XDR = 0, NDR = 1 }
 constants for endian-ness More...
typedef enum QgsApplication::ENDIAN endian_t
 constants for endian-ness

Signals

void preNotify (QObject *receiver, QEvent *event, bool *done)

Public Member Functions

 QgsApplication (int &argc, char **argv, bool GUIenabled, QString customConfigPath=QString())
virtual ~QgsApplication ()
virtual bool event (QEvent *event)
 Watch for QFileOpenEvent.
virtual bool notify (QObject *receiver, QEvent *event)
 Catch exceptions when sending event to receiver.

Static Public Member Functions

static void init (QString customConfigPath=QString())
 This method initialises paths etc for QGIS.
static void setFileOpenEventReceiver (QObject *receiver)
 Set the FileOpen event receiver.
static void setThemeName (const QString theThemeName)
 Set the active theme to the specified theme.
static const QString themeName ()
 Set the active theme to the specified theme.
static const QString authorsFilePath ()
 Returns the path to the authors file.
static const QString contributorsFilePath ()
 Returns the path to the contributors file.
static const QString sponsorsFilePath ()
 Returns the path to the sponsors file.
static const QString donorsFilePath ()
 Returns the path to the donors file.
static const QString translatorsFilePath ()
 Returns the path to the sponsors file.
static const QString licenceFilePath ()
static const QString helpAppPath ()
 Returns the path to the help application.
static const QString i18nPath ()
 Returns the path to the translation directory.
static const QString qgisMasterDbFilePath ()
 Returns the path to the master qgis.db file.
static const QString qgisSettingsDirPath ()
 Returns the path to the settings directory in user's home dir.
static const QString qgisUserDbFilePath ()
 Returns the path to the user qgis.db file.
static const QString splashPath ()
 Returns the path to the splash screen image directory.
static const QString iconsPath ()
 Returns the path to the icons image directory.
static const QString srsDbFilePath ()
 Returns the path to the srs.db file.
static const QStringList svgPaths ()
 Returns the pathes to svg directories.
static const QMap< QString,
QString > 
systemEnvVars ()
 Returns the system environment variables passed to application.
static const QString prefixPath ()
 Returns the path to the application prefix directory.
static const QString pluginPath ()
 Returns the path to the application plugin directory.
static const QString pkgDataPath ()
 Returns the common root path of all application data directories.
static const QString activeThemePath ()
 Returns the path to the currently active theme directory.
static const QString defaultThemePath ()
 Returns the path to the default theme directory.
static QString iconPath (QString iconFile)
 Returns path to the desired icon file.
static QIcon getThemeIcon (const QString theName)
 Helper to get a theme icon.
static QPixmap getThemePixmap (const QString theName)
 Helper to get a theme icon as a pixmap.
static const QString userStyleV2Path ()
 Returns the path to user's style. Added in QGIS 1.4.
static const QString defaultStyleV2Path ()
 Returns the path to default style (works as a starting point). Added in QGIS 1.4.
static const QString libraryPath ()
 Returns the path containing qgis_core, qgis_gui, qgispython (and other) libraries.
static const QString libexecPath ()
 Returns the path with utility executables (help viewer, crssync, ...)
static void setPrefixPath (const QString thePrefixPath, bool useDefaultPaths=false)
 Alters prefix path - used by 3rd party apps.
static void setPluginPath (const QString thePluginPath)
 Alters plugin path - used by 3rd party apps.
static void setPkgDataPath (const QString thePkgDataPath)
 Alters pkg data path - used by 3rd party apps.
static void setDefaultSvgPaths (const QStringList &pathList)
 Alters default svg paths - used by 3rd party apps. Added in QGIS 1.5.
static void initQgis ()
 loads providers
static bool createDB (QString *errorMessage=0)
 initialise qgis.db
static void exitQgis ()
 deletes provider registry and map layer registry
static endian_t endian ()
 Returns whether this machine uses big or little endian.
static QString reportStyleSheet ()
 get a standard css style sheet for reports.
static QString showSettings ()
 Convenience function to get a summary of the paths used in this application instance useful for debugging mainly.
static void registerOgrDrivers ()
 Register OGR drivers ensuring this only happens once.
static QString absolutePathToRelativePath (QString apath, QString targetPath)
 Converts absolute path to path relative to target.
static QString relativePathToAbsolutePath (QString rpath, QString targetPath)
 Converts path relative to target to an absolute path.
static bool isRunningFromBuildDir ()
 Indicates whether running from build directory (not installed)
static QString buildSourcePath ()
 Returns path to the source directory.
static QString buildOutputPath ()
 Returns path to the build output directory.
static void skipGdalDriver (QString theDriver)
 Sets the GDAL_SKIP environment variable to include the specified driver and then calls GDALDriverManager::AutoSkipDrivers() to unregister it.
static void restoreGdalDriver (QString theDriver)
 Sets the GDAL_SKIP environment variable to exclude the specified driver and then calls GDALDriverManager::AutoSkipDrivers() to unregister it.
static QStringList skippedGdalDrivers ()
 Returns the list of gdal drivers that should be skipped (based on GDAL_SKIP environment variable)
static void applyGdalSkippedDrivers ()
 Apply the skipped drivers list to gdal.

Static Private Member Functions

static QObject * ABISYM (mFileOpenEventReceiver)
static QStringList ABISYM (mFileOpenEventList)
static QString ABISYM (mPrefixPath)
static QString ABISYM (mPluginPath)
static QString ABISYM (mPkgDataPath)
static QString ABISYM (mLibraryPath)
static QString ABISYM (mLibexecPath)
static QString ABISYM (mThemeName)
static QStringList ABISYM (mDefaultSvgPaths)
static QMap< QString, QString > ABISYM (mSystemEnvVars)
static QString ABISYM (mConfigPath)
static bool ABISYM (mRunningFromBuildDir)
 true when running from build directory, i.e.
static QString ABISYM (mBuildSourcePath)
 path to the source directory.
static QString ABISYM (mBuildOutputPath)
 path to the output directory of the build.
static QStringList ABISYM (mGdalSkipList)
 List of gdal drivers to be skipped.

Detailed Description

Extends QApplication to provide access to QGIS specific resources such as theme paths, database paths etc.

The QgsApplication class manages application-wide information.

This is a subclass of QApplication and should be instantiated in place of QApplication. Most methods are static in keeping witn the design of QApplication.

This class hides platform-specific path information and provides a portable way of referencing specific files and directories. Ideally, hard-coded paths should appear only here and not in other modules so that platform-conditional code is minimized and paths are easier to change due to centralization.

Definition at line 29 of file qgsapplication.h.

Member Typedef Documentation

constants for endian-ness

Member Enumeration Documentation

constants for endian-ness

Enumerator:
XDR 
NDR 

Definition at line 198 of file qgsapplication.h.

Constructor & Destructor Documentation

QgsApplication::QgsApplication ( int &  argc,
char **  argv,
bool  GUIenabled,
QString  customConfigPath = QString() 
)
Note
customConfigDir parameter added in v1.6

Definition at line 78 of file qgsapplication.cpp.

References init().

QgsApplication::~QgsApplication ( )
virtual

Definition at line 177 of file qgsapplication.cpp.

Member Function Documentation

static QObject* QgsApplication::ABISYM ( mFileOpenEventReceiver  )
staticprivate
static QStringList QgsApplication::ABISYM ( mFileOpenEventList  )
staticprivate
static QString QgsApplication::ABISYM ( mPrefixPath  )
staticprivate
static QString QgsApplication::ABISYM ( mPluginPath  )
staticprivate
static QString QgsApplication::ABISYM ( mPkgDataPath  )
staticprivate
static QString QgsApplication::ABISYM ( mLibraryPath  )
staticprivate
static QString QgsApplication::ABISYM ( mLibexecPath  )
staticprivate
static QString QgsApplication::ABISYM ( mThemeName  )
staticprivate
static QStringList QgsApplication::ABISYM ( mDefaultSvgPaths  )
staticprivate
static QMap<QString, QString> QgsApplication::ABISYM ( mSystemEnvVars  )
staticprivate
static QString QgsApplication::ABISYM ( mConfigPath  )
staticprivate
static bool QgsApplication::ABISYM ( mRunningFromBuildDir  )
staticprivate

true when running from build directory, i.e.

without 'make install'

static QString QgsApplication::ABISYM ( mBuildSourcePath  )
staticprivate

path to the source directory.

valid only when running from build directory.

static QString QgsApplication::ABISYM ( mBuildOutputPath  )
staticprivate

path to the output directory of the build.

valid only when running from build directory

static QStringList QgsApplication::ABISYM ( mGdalSkipList  )
staticprivate

List of gdal drivers to be skipped.

Uses GDAL_SKIP to exclude them.

See Also
skipGdalDriver, restoreGdalDriver
Note
added in 2.0
QString QgsApplication::absolutePathToRelativePath ( QString  apath,
QString  targetPath 
)
static

Converts absolute path to path relative to target.

Note
: this method was added in version 1.6

Definition at line 734 of file qgsapplication.cpp.

const QString QgsApplication::activeThemePath ( )
static
void QgsApplication::applyGdalSkippedDrivers ( )
static

Apply the skipped drivers list to gdal.

See Also
skipGdalDriver
restoreGdalDriver
skippedGdalDrivers
Note
added in 2.0

Definition at line 868 of file qgsapplication.cpp.

References ABISYM(), and QgsDebugMsg.

Referenced by restoreGdalDriver(), and skipGdalDriver().

const QString QgsApplication::authorsFilePath ( )
static

Returns the path to the authors file.

Definition at line 396 of file qgsapplication.cpp.

References ABISYM().

static QString QgsApplication::buildOutputPath ( )
inlinestatic

Returns path to the build output directory.

Valid only when running from build directory

Note
added in 2.0

Definition at line 248 of file qgsapplication.h.

References ABISYM().

static QString QgsApplication::buildSourcePath ( )
inlinestatic

Returns path to the source directory.

Valid only when running from build directory

Note
added in 2.0

Definition at line 245 of file qgsapplication.h.

References ABISYM().

const QString QgsApplication::contributorsFilePath ( )
static

Returns the path to the contributors file.

Contributors are people who have submitted patches but don't have svn write access.

Note
this function was added in version 1.3

Definition at line 403 of file qgsapplication.cpp.

References ABISYM().

bool QgsApplication::createDB ( QString *  errorMessage = 0)
static

initialise qgis.db

Definition at line 878 of file qgsapplication.cpp.

References qgisMasterDbFilePath(), qgisSettingsDirPath(), qgisUserDbFilePath(), QgsDebugMsg, and tr.

const QString QgsApplication::defaultStyleV2Path ( )
static

Returns the path to default style (works as a starting point). Added in QGIS 1.4.

Definition at line 557 of file qgsapplication.cpp.

References ABISYM().

Referenced by QgsStyleV2::defaultStyle().

const QString QgsApplication::defaultThemePath ( )
static

Returns the path to the default theme directory.

Definition at line 312 of file qgsapplication.cpp.

Referenced by QgsComposerItem::drawSelectionBoxes(), getThemeIcon(), getThemePixmap(), icon(), iconPath(), and showSettings().

const QString QgsApplication::donorsFilePath ( )
static

Returns the path to the donors file.

Note
this function was added in version 1.2

Definition at line 418 of file qgsapplication.cpp.

References ABISYM().

QgsApplication::endian_t QgsApplication::endian ( )
static

Returns whether this machine uses big or little endian.

Definition at line 572 of file qgsapplication.cpp.

References NDR, and XDR.

Referenced by QgsGeometry::convertToMultiType(), QgsGeometry::exportGeosToWkb(), and QgsGml::QgsGml().

bool QgsApplication::event ( QEvent *  event)
virtual

Watch for QFileOpenEvent.

Definition at line 181 of file qgsapplication.cpp.

References ABISYM(), file, and notify().

void QgsApplication::exitQgis ( )
static

deletes provider registry and map layer registry

Definition at line 586 of file qgsapplication.cpp.

References QgsMapLayerRegistry::instance(), and QgsProviderRegistry::instance().

QIcon QgsApplication::getThemeIcon ( const QString  theName)
static
QPixmap QgsApplication::getThemePixmap ( const QString  theName)
static

Helper to get a theme icon as a pixmap.

It will fall back to the default theme if the active theme does not have the required icon.

Note
Added in 2.0

Definition at line 354 of file qgsapplication.cpp.

References activeThemePath(), and defaultThemePath().

Referenced by QgsFeatureListViewDelegate::paint(), QgsErrorItem::QgsErrorItem(), QgsRasterHistogramWidget::refreshHistogram(), and QgsColorButton::transpBkgrd().

const QString QgsApplication::helpAppPath ( )
static

Returns the path to the help application.

Definition at line 443 of file qgsapplication.cpp.

References libexecPath().

Referenced by QgsContextHelp::start().

const QString QgsApplication::i18nPath ( )
static

Returns the path to the translation directory.

Definition at line 460 of file qgsapplication.cpp.

References ABISYM().

QString QgsApplication::iconPath ( QString  iconFile)
static

Returns path to the desired icon file.

First it tries to use the active theme path, then default theme path

Note
Added in 1.5

Definition at line 322 of file qgsapplication.cpp.

References activeThemePath(), and defaultThemePath().

const QString QgsApplication::iconsPath ( )
static

Returns the path to the icons image directory.

Definition at line 503 of file qgsapplication.cpp.

References ABISYM().

void QgsApplication::init ( QString  customConfigPath = QString())
static

This method initialises paths etc for QGIS.

Called by the ctor or call it manually when your app does not extend the QApplication class.

Note
you will probably want to call initQgis too to load the providers in the above case.

Definition at line 84 of file qgsapplication.cpp.

References ABISYM(), prefixPath(), qgisSettingsDirPath(), setPkgDataPath(), setPluginPath(), and setPrefixPath().

Referenced by QgsApplication().

void QgsApplication::initQgis ( )
static

loads providers

Definition at line 577 of file qgsapplication.cpp.

References QgsMapLayerRegistry::instance(), QgsProviderRegistry::instance(), and pluginPath().

static bool QgsApplication::isRunningFromBuildDir ( )
inlinestatic

Indicates whether running from build directory (not installed)

Note
added in 2.0

Definition at line 239 of file qgsapplication.h.

References ABISYM().

Referenced by QgsContextHelp::start().

const QString QgsApplication::libexecPath ( )
static

Returns the path with utility executables (help viewer, crssync, ...)

Note
Added in 2.0

Definition at line 567 of file qgsapplication.cpp.

References ABISYM().

Referenced by helpAppPath().

const QString QgsApplication::libraryPath ( )
static

Returns the path containing qgis_core, qgis_gui, qgispython (and other) libraries.

Note
Added in 2.0

Definition at line 562 of file qgsapplication.cpp.

References ABISYM().

const QString QgsApplication::licenceFilePath ( )
static

Returns the path to the licence file.

Definition at line 435 of file qgsapplication.cpp.

References ABISYM().

bool QgsApplication::notify ( QObject *  receiver,
QEvent *  event 
)
virtual

Catch exceptions when sending event to receiver.

Definition at line 209 of file qgsapplication.cpp.

References preNotify(), tr, and QgsException::what().

Referenced by event().

const QString QgsApplication::pkgDataPath ( )
static

Returns the common root path of all application data directories.

Definition at line 308 of file qgsapplication.cpp.

References ABISYM().

Referenced by QgsCptCityArchive::defaultBaseDir(), QgsCptCityArchive::initArchives(), QgsCptCityArchive::initDefaultArchive(), QgsMapLayer::loadNamedStyle(), and showSettings().

const QString QgsApplication::pluginPath ( )
static

Returns the path to the application plugin directory.

Definition at line 304 of file qgsapplication.cpp.

References ABISYM().

Referenced by initQgis(), and showSettings().

const QString QgsApplication::prefixPath ( )
static

Returns the path to the application prefix directory.

Definition at line 295 of file qgsapplication.cpp.

References ABISYM().

Referenced by init(), and showSettings().

void QgsApplication::preNotify ( QObject *  receiver,
QEvent *  event,
bool *  done 
)
signal
Note
not available in python bindings

Referenced by notify().

const QString QgsApplication::qgisMasterDbFilePath ( )
static

Returns the path to the master qgis.db file.

Definition at line 471 of file qgsapplication.cpp.

References ABISYM().

Referenced by createDB(), and showSettings().

const QString QgsApplication::qgisSettingsDirPath ( )
static

Returns the path to the settings directory in user's home dir.

Returns the path to the settings directory in user's home dir

Definition at line 479 of file qgsapplication.cpp.

References ABISYM().

Referenced by createDB(), init(), QgsMapLayer::loadNamedStyle(), qgisUserDbFilePath(), QgsMapLayer::saveNamedStyle(), and userStyleV2Path().

const QString QgsApplication::qgisUserDbFilePath ( )
static
void QgsApplication::registerOgrDrivers ( )
static

Register OGR drivers ensuring this only happens once.

This is a workaround for an issue with older gdal versions that caused duplicate driver name entries to appear in the list of registered drivers when QgsApplication::registerOgrDrivers was called multiple times.

Definition at line 726 of file qgsapplication.cpp.

Referenced by QgsVectorFileWriter::ogrDriverList(), QgsVectorFileWriter::QgsVectorFileWriter(), and QgsVectorFileWriter::supportedFiltersAndFormats().

QString QgsApplication::relativePathToAbsolutePath ( QString  rpath,
QString  targetPath 
)
static

Converts path relative to target to an absolute path.

Note
: this method was added in version 1.6

Definition at line 797 of file qgsapplication.cpp.

QString QgsApplication::reportStyleSheet ( )
static

get a standard css style sheet for reports.

Typically you will use this method by doing: QString myStyle = QgsApplication::reportStyleSheet(); textBrowserReport->document()->setDefaultStyleSheet(myStyle);

Returns
QString containing the CSS 2.1 compliant stylesheet.
Note
you can use the special Qt extensions too, for example the gradient fills for backgrounds.

Definition at line 617 of file qgsapplication.cpp.

Referenced by QgsExpressionBuilderWidget::loadFunctionHelp(), QgsGenericProjectionSelector::setMessage(), and QgsContextHelp::showContext().

void QgsApplication::restoreGdalDriver ( QString  theDriver)
static

Sets the GDAL_SKIP environment variable to exclude the specified driver and then calls GDALDriverManager::AutoSkipDrivers() to unregister it.

The driver name should be the short format of the Gdal driver name e.g. GTIFF.

Note
added in 2.0

Definition at line 854 of file qgsapplication.cpp.

References ABISYM(), and applyGdalSkippedDrivers().

void QgsApplication::setDefaultSvgPaths ( const QStringList &  pathList)
static

Alters default svg paths - used by 3rd party apps. Added in QGIS 1.5.

Definition at line 290 of file qgsapplication.cpp.

References ABISYM().

void QgsApplication::setFileOpenEventReceiver ( QObject *  receiver)
static

Set the FileOpen event receiver.

Definition at line 241 of file qgsapplication.cpp.

References ABISYM().

void QgsApplication::setPkgDataPath ( const QString  thePkgDataPath)
static

Alters pkg data path - used by 3rd party apps.

Definition at line 281 of file qgsapplication.cpp.

References ABISYM().

Referenced by init(), and setPrefixPath().

void QgsApplication::setPluginPath ( const QString  thePluginPath)
static

Alters plugin path - used by 3rd party apps.

Definition at line 276 of file qgsapplication.cpp.

References ABISYM().

Referenced by init(), and setPrefixPath().

void QgsApplication::setPrefixPath ( const QString  thePrefixPath,
bool  useDefaultPaths = false 
)
static

Alters prefix path - used by 3rd party apps.

Definition at line 258 of file qgsapplication.cpp.

References ABISYM(), setPkgDataPath(), and setPluginPath().

Referenced by init().

void QgsApplication::setThemeName ( const QString  theThemeName)
static

Set the active theme to the specified theme.

The theme name should be a single word e.g. 'default','classic'. The theme search path usually will be pkgDataPath + "/themes/" + themName + "/" but plugin writers etc can use themeName() as a basis for searching for resources in their own datastores e.g. a Qt4 resource bundle.

Note
A basic test will be carried out to ensure the theme search path based on the supplied theme name exists. If it does not the theme name will be reverted to 'default'.

Set the theme path to the specified theme.

Definition at line 373 of file qgsapplication.cpp.

References ABISYM().

QString QgsApplication::showSettings ( )
static

Convenience function to get a summary of the paths used in this application instance useful for debugging mainly.

Definition at line 592 of file qgsapplication.cpp.

References activeThemePath(), defaultThemePath(), pkgDataPath(), pluginPath(), prefixPath(), qgisMasterDbFilePath(), svgPaths(), themeName(), and tr.

void QgsApplication::skipGdalDriver ( QString  theDriver)
static

Sets the GDAL_SKIP environment variable to include the specified driver and then calls GDALDriverManager::AutoSkipDrivers() to unregister it.

The driver name should be the short format of the Gdal driver name e.g. GTIFF.

Note
added in 2.0

Definition at line 844 of file qgsapplication.cpp.

References ABISYM(), and applyGdalSkippedDrivers().

static QStringList QgsApplication::skippedGdalDrivers ( )
inlinestatic

Returns the list of gdal drivers that should be skipped (based on GDAL_SKIP environment variable)

Note
added in 2.0

Definition at line 268 of file qgsapplication.h.

References ABISYM().

const QString QgsApplication::splashPath ( )
static

Returns the path to the splash screen image directory.

Definition at line 495 of file qgsapplication.cpp.

const QString QgsApplication::sponsorsFilePath ( )
static

Returns the path to the sponsors file.

Note
this function was added in version 1.2

Definition at line 410 of file qgsapplication.cpp.

References ABISYM().

const QString QgsApplication::srsDbFilePath ( )
static
const QStringList QgsApplication::svgPaths ( )
static

Returns the pathes to svg directories.

Note
added in 1.4

Returns the paths to the svg directories.

Definition at line 536 of file qgsapplication.cpp.

References ABISYM().

Referenced by QgsSymbolLayerV2Utils::listSvgFiles(), showSettings(), QgsSymbolLayerV2Utils::symbolNameToPath(), and QgsSymbolLayerV2Utils::symbolPathToName().

static const QMap<QString, QString> QgsApplication::systemEnvVars ( )
inlinestatic

Returns the system environment variables passed to application.

Note
added in 1.9

Definition at line 130 of file qgsapplication.h.

References ABISYM().

const QString QgsApplication::themeName ( )
static

Set the active theme to the specified theme.

The theme name should be a single word e.g. 'default','classic'. The theme search path usually will be pkgDataPath + "/themes/" + themName + "/" but plugin writers etc can use this method as a basis for searching for resources in their own datastores e.g. a Qt4 resource bundle.

Get the active theme name

Definition at line 389 of file qgsapplication.cpp.

References ABISYM().

Referenced by activeThemePath(), and showSettings().

const QString QgsApplication::translatorsFilePath ( )
static

Returns the path to the sponsors file.

Note
This was added in QGIS 1.1

Returns the path to the sponsors file.

Note
Added in QGIS 1.1

Definition at line 427 of file qgsapplication.cpp.

References ABISYM().

const QString QgsApplication::userStyleV2Path ( )
static

Returns the path to user's style. Added in QGIS 1.4.

Definition at line 552 of file qgsapplication.cpp.

References qgisSettingsDirPath().

Referenced by QgsStyleV2::defaultStyle().


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