mirror of
https://github.com/qgis/QGIS.git
synced 2025-02-25 00:58:06 -05:00
200 lines
9.7 KiB
Plaintext
200 lines
9.7 KiB
Plaintext
/***************************************************************************
|
|
qgssettings.sip
|
|
--------------------------------------
|
|
Date : January 2017
|
|
Copyright : (C) 2017 by Alessandro Pasotti
|
|
Email : apasotti at boundlessgeo dot com
|
|
***************************************************************************
|
|
* *
|
|
* This program is free software; you can redistribute it and/or modify *
|
|
* it under the terms of the GNU General Public License as published by *
|
|
* the Free Software Foundation; either version 2 of the License, or *
|
|
* (at your option) any later version. *
|
|
* *
|
|
***************************************************************************/
|
|
|
|
/** \ingroup core
|
|
* \class QgsSettings
|
|
*
|
|
* This class is a composition of two QSettings instances:
|
|
* - the main QSettings instance is the standard User Settings and
|
|
* - the second one (Global Settings) is meant to provide read-only
|
|
* pre-configuration and defaults to the first one.
|
|
*
|
|
* For a given settings key, the function call to value(key, default) will return
|
|
* the first existing setting in the order specified below:
|
|
* - User Settings
|
|
* - Global Settings
|
|
* - Default Value
|
|
*
|
|
* The path to the Global Settings storage can be set before constructing the QgsSettings
|
|
* objects, with a static call to:
|
|
* static bool setGlobalSettingsPath( QString path );
|
|
*
|
|
* QgsSettings provides some shortcuts to get/set namespaced settings from/to a specific section:
|
|
* - Core
|
|
* - Gui
|
|
* - Server
|
|
* - Plugins
|
|
* - Misc
|
|
*
|
|
* @note added in QGIS 3
|
|
*/
|
|
class QgsSettings : public QObject
|
|
{
|
|
%TypeHeaderCode
|
|
#include <qgssettings.h>
|
|
|
|
typedef PyObject *(*pyqt5_from_qvariant_by_type)(QVariant &value, PyObject *type);
|
|
%End
|
|
|
|
public:
|
|
|
|
//! Sections for namespaced settings
|
|
enum Section
|
|
{
|
|
NoSection,
|
|
Core,
|
|
Gui,
|
|
Server,
|
|
Plugins,
|
|
Auth,
|
|
App,
|
|
Providers,
|
|
Misc
|
|
};
|
|
|
|
/** Construct a QgsSettings object for accessing settings of the application
|
|
* called application from the organization called organization, and with parent parent.
|
|
*/
|
|
explicit QgsSettings( const QString &organization,
|
|
const QString &application = QString(), QObject *parent = 0 );
|
|
|
|
/** Construct a QgsSettings object for accessing settings of the application called application
|
|
* from the organization called organization, and with parent parent.
|
|
* If scope is QSettings::UserScope, the QSettings object searches user-specific settings first,
|
|
* before it searches system-wide settings as a fallback. If scope is QSettings::SystemScope,
|
|
* the QSettings object ignores user-specific settings and provides access to system-wide settings.
|
|
*
|
|
* The storage format is set to QSettings::NativeFormat (i.e. calling setDefaultFormat() before
|
|
* calling this constructor has no effect).
|
|
*
|
|
* If no application name is given, the QSettings object will only access the organization-wide
|
|
* locations.
|
|
*/
|
|
QgsSettings( QSettings::Scope scope, const QString &organization,
|
|
const QString &application = QString(), QObject *parent = 0 );
|
|
|
|
/** Construct a QgsSettings object for accessing settings of the application called application
|
|
* from the organization called organization, and with parent parent.
|
|
* If scope is QSettings::UserScope, the QSettings object searches user-specific settings first,
|
|
* before it searches system-wide settings as a fallback. If scope is QSettings::SystemScope,
|
|
* the QSettings object ignores user-specific settings and provides access to system-wide settings.
|
|
* If format is QSettings::NativeFormat, the native API is used for storing settings. If format
|
|
* is QSettings::IniFormat, the INI format is used.
|
|
*
|
|
* If no application name is given, the QSettings object will only access the organization-wide
|
|
* locations.
|
|
*/
|
|
QgsSettings( QSettings::Format format, QSettings::Scope scope, const QString &organization,
|
|
const QString &application = QString(), QObject *parent = 0 );
|
|
|
|
/** Construct a QgsSettings object for accessing the settings stored in the file called fileName,
|
|
* with parent parent. If the file doesn't already exist, it is created.
|
|
*
|
|
* If format is QSettings::NativeFormat, the meaning of fileName depends on the platform. On Unix,
|
|
* fileName is the name of an INI file. On macOS and iOS, fileName is the name of a .plist file.
|
|
* On Windows, fileName is a path in the system registry.
|
|
*
|
|
* If format is QSettings::IniFormat, fileName is the name of an INI file.
|
|
*
|
|
* Warning: This function is provided for convenience. It works well for accessing INI or .plist
|
|
* files generated by Qt, but might fail on some syntaxes found in such files originated by
|
|
* other programs. In particular, be aware of the following limitations:
|
|
* - QgsSettings provides no way of reading INI "path" entries, i.e., entries with unescaped slash characters.
|
|
* (This is because these entries are ambiguous and cannot be resolved automatically.)
|
|
* - In INI files, QSettings uses the @ character as a metacharacter in some contexts, to encode
|
|
* Qt-specific data types (e.g., \@Rect), and might therefore misinterpret it when it occurs
|
|
* in pure INI files.
|
|
*/
|
|
QgsSettings( const QString &fileName, QSettings::Format format, QObject *parent = 0 );
|
|
|
|
/** Constructs a QgsSettings object for accessing settings of the application and organization
|
|
* set previously with a call to QCoreApplication::setOrganizationName(),
|
|
* QCoreApplication::setOrganizationDomain(), and QCoreApplication::setApplicationName().
|
|
*
|
|
* The scope is QSettings::UserScope and the format is defaultFormat() (QSettings::NativeFormat
|
|
* by default). Use setDefaultFormat() before calling this constructor to change the default
|
|
* format used by this constructor.
|
|
*/
|
|
explicit QgsSettings( QObject *parent = 0 );
|
|
~QgsSettings();
|
|
|
|
/** Appends prefix to the current group.
|
|
* The current group is automatically prepended to all keys specified to QSettings.
|
|
* In addition, query functions such as childGroups(), childKeys(), and allKeys()
|
|
* are based on the group. By default, no group is set.
|
|
*/
|
|
void beginGroup( const QString &prefix );
|
|
//! Resets the group to what it was before the corresponding beginGroup() call.
|
|
void endGroup();
|
|
//! Returns a list of all keys, including subkeys, that can be read using the QSettings object.
|
|
QStringList allKeys() const;
|
|
//! Returns a list of all top-level keys that can be read using the QSettings object.
|
|
QStringList childKeys() const;
|
|
//! Returns a list of all key top-level groups that contain keys that can be read using the QSettings object.
|
|
QStringList childGroups() const;
|
|
//! Return the path to the Global Settings QSettings storage file
|
|
static QString globalSettingsPath();
|
|
//! Set the Global Settings QSettings storage file
|
|
static bool setGlobalSettingsPath( QString path );
|
|
//! Adds prefix to the current group and starts reading from an array. Returns the size of the array.
|
|
int beginReadArray( const QString &prefix );
|
|
//! Closes the array that was started using beginReadArray() or beginWriteArray().
|
|
void endArray();
|
|
//! Sets the current array index to i. Calls to functions such as setValue(), value(), remove(), and contains() will operate on the array entry at that index.
|
|
void setArrayIndex( int i );
|
|
//! Sets the value of setting key to value. If the key already exists, the previous value is overwritten.
|
|
//! An optional Section argument can be used to set a value to a specific Section.
|
|
void setValue(const QString &key, const QVariant &value, const QgsSettings::Section section = QgsSettings::Section::NoSection );
|
|
/** Returns the value for setting key. If the setting doesn't exist, it will be
|
|
* searched in the Global Settings and if not found, returns defaultValue.
|
|
* If no default value is specified, a default QVariant is returned.
|
|
* An optional Section argument can be used to get a value from a specific Section.
|
|
*/
|
|
SIP_PYOBJECT value( const QString &key, const QVariant &defaultValue = QVariant(),
|
|
SIP_PYOBJECT type = 0,
|
|
QgsSettings::Section section = QgsSettings::Section::NoSection ) const /ReleaseGIL/;
|
|
%MethodCode
|
|
QVariant value;
|
|
|
|
// QSettings has an internal mutex so release the GIL to avoid the possibility of deadlocks.
|
|
Py_BEGIN_ALLOW_THREADS
|
|
value = sipCpp->value(*a0, *a1, a3);
|
|
Py_END_ALLOW_THREADS
|
|
|
|
pyqt5_from_qvariant_by_type f = (pyqt5_from_qvariant_by_type) sipImportSymbol("pyqt5_from_qvariant_by_type");
|
|
sipRes = f(value, a2);
|
|
|
|
sipIsErr = !sipRes;
|
|
%End
|
|
|
|
//! Removes the setting key and any sub-settings of key.
|
|
void remove(const QString &key);
|
|
//! Return the sanitized and prefixed key
|
|
QString prefixedKey( const QString &key, const Section section ) const;
|
|
//! Returns the path where settings written using this QSettings object are stored.
|
|
QString fileName() const;
|
|
//! Writes any unsaved changes to permanent storage, and reloads any settings that have been
|
|
//! changed in the meantime by another application.
|
|
//! This function is called automatically from QSettings's destructor and by the event
|
|
//! loop at regular intervals, so you normally don't need to call it yourself.
|
|
void sync();
|
|
//! Returns true if there exists a setting called key; returns false otherwise.
|
|
//! If a group is set using beginGroup(), key is taken to be relative to that group.
|
|
bool contains(const QString &key, QgsSettings::Section section = QgsSettings::Section::NoSection ) const;
|
|
//! Removes all entries in the primary location associated to this QgsSettings object.
|
|
void clear();
|
|
|
|
};
|