mirror of
https://github.com/qgis/QGIS.git
synced 2025-02-25 00:58:06 -05:00
1c615c15cc
Use Qt style "returns .." tense instead of "return ..", and lock this in with a documentation compliance unit test
264 lines
10 KiB
Plaintext
264 lines
10 KiB
Plaintext
/************************************************************************
|
|
* This file has been generated automatically from *
|
|
* *
|
|
* src/core/qgssettings.h *
|
|
* *
|
|
* Do not edit manually ! Edit header and run scripts/sipify.pl again *
|
|
************************************************************************/
|
|
|
|
|
|
|
|
|
|
|
|
class QgsSettings : QObject
|
|
{
|
|
%Docstring
|
|
|
|
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
|
|
- Auth
|
|
- App
|
|
- Providers
|
|
- Misc
|
|
|
|
.. versionadded:: 3
|
|
%End
|
|
|
|
%TypeHeaderCode
|
|
#include "qgssettings.h"
|
|
%End
|
|
public:
|
|
|
|
enum Section
|
|
{
|
|
NoSection,
|
|
Core,
|
|
Gui,
|
|
Server,
|
|
Plugins,
|
|
Auth,
|
|
App,
|
|
Providers,
|
|
Misc
|
|
};
|
|
|
|
explicit QgsSettings( const QString &organization,
|
|
const QString &application = QString(), QObject *parent = 0 );
|
|
%Docstring
|
|
Construct a QgsSettings object for accessing settings of the application
|
|
called application from the organization called organization, and with parent parent.
|
|
%End
|
|
|
|
QgsSettings( QSettings::Scope scope, const QString &organization,
|
|
const QString &application = QString(), QObject *parent = 0 );
|
|
%Docstring
|
|
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.
|
|
%End
|
|
|
|
QgsSettings( QSettings::Format format, QSettings::Scope scope, const QString &organization,
|
|
const QString &application = QString(), QObject *parent = 0 );
|
|
%Docstring
|
|
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.
|
|
%End
|
|
|
|
QgsSettings( const QString &fileName, QSettings::Format format, QObject *parent = 0 );
|
|
%Docstring
|
|
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.
|
|
%End
|
|
|
|
explicit QgsSettings( QObject *parent = 0 );
|
|
%Docstring
|
|
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.
|
|
%End
|
|
~QgsSettings();
|
|
|
|
void beginGroup( const QString &prefix, const QgsSettings::Section section = QgsSettings::NoSection );
|
|
%Docstring
|
|
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.
|
|
%End
|
|
void endGroup();
|
|
%Docstring
|
|
Resets the group to what it was before the corresponding beginGroup() call.
|
|
%End
|
|
QStringList allKeys() const;
|
|
%Docstring
|
|
Returns a list of all keys, including subkeys, that can be read using the QSettings object.
|
|
%End
|
|
QStringList childKeys() const;
|
|
%Docstring
|
|
Returns a list of all top-level keys that can be read using the QSettings object.
|
|
%End
|
|
QStringList childGroups() const;
|
|
%Docstring
|
|
Returns a list of all key top-level groups that contain keys that can be read using the QSettings object.
|
|
%End
|
|
QStringList globalChildGroups() const;
|
|
%Docstring
|
|
Returns a list of all key top-level groups (same as childGroups) but only for groups defined in global settings.
|
|
%End
|
|
static QString globalSettingsPath();
|
|
%Docstring
|
|
Returns the path to the Global Settings QSettings storage file
|
|
%End
|
|
static bool setGlobalSettingsPath( const QString &path );
|
|
%Docstring
|
|
Sets the Global Settings QSettings storage file
|
|
%End
|
|
int beginReadArray( const QString &prefix );
|
|
%Docstring
|
|
Adds prefix to the current group and starts reading from an array. Returns the size of the array.
|
|
%End
|
|
|
|
void beginWriteArray( const QString &prefix, int size = -1 );
|
|
%Docstring
|
|
Adds prefix to the current group and starts writing an array of size size.
|
|
If size is -1 (the default), it is automatically determined based on the indexes of the entries written.
|
|
|
|
.. note::
|
|
|
|
This will completely shadow any existing array with the same name in the global settings
|
|
%End
|
|
void endArray();
|
|
%Docstring
|
|
Closes the array that was started using beginReadArray() or beginWriteArray().
|
|
%End
|
|
|
|
void setArrayIndex( int i );
|
|
%Docstring
|
|
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.
|
|
%End
|
|
|
|
void setValue( const QString &key, const QVariant &value, const QgsSettings::Section section = QgsSettings::NoSection );
|
|
%Docstring
|
|
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.
|
|
%End
|
|
|
|
SIP_PYOBJECT value( const QString &key, const QVariant &defaultValue = QVariant(),
|
|
SIP_PYOBJECT type = 0,
|
|
QgsSettings::Section section = QgsSettings::NoSection ) const / ReleaseGIL /;
|
|
%Docstring
|
|
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.
|
|
%End
|
|
%MethodCode
|
|
typedef PyObject *( *pyqt5_from_qvariant_by_type )( QVariant &value, PyObject *type );
|
|
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
|
|
|
|
|
|
bool contains( const QString &key, const QgsSettings::Section section = QgsSettings::NoSection ) const;
|
|
%Docstring
|
|
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.
|
|
%End
|
|
QString fileName() const;
|
|
%Docstring
|
|
Returns the path where settings written using this QSettings object are stored.
|
|
%End
|
|
|
|
void sync();
|
|
%Docstring
|
|
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.
|
|
%End
|
|
void remove( const QString &key, const QgsSettings::Section section = QgsSettings::NoSection );
|
|
%Docstring
|
|
Removes the setting key and any sub-settings of key in a section.
|
|
%End
|
|
QString prefixedKey( const QString &key, const QgsSettings::Section section ) const;
|
|
%Docstring
|
|
Returns the sanitized and prefixed key
|
|
%End
|
|
void clear();
|
|
%Docstring
|
|
Removes all entries in the user settings
|
|
%End
|
|
|
|
};
|
|
|
|
/************************************************************************
|
|
* This file has been generated automatically from *
|
|
* *
|
|
* src/core/qgssettings.h *
|
|
* *
|
|
* Do not edit manually ! Edit header and run scripts/sipify.pl again *
|
|
************************************************************************/
|