/************************************************************************
 * This file has been generated automatically from                      *
 *                                                                      *
 * src/core/settings/qgssettings.h                                      *
 *                                                                      *
 * Do not edit manually ! Edit header and run scripts/sipify.py again   *
 ************************************************************************/






class QgsSettings : QObject
{
%Docstring(signature="appended")
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 :py:class:`QgsSettings` objects, with a static call to: static bool
setGlobalSettingsPath( QString path );

:py:class:`QgsSettings` provides some shortcuts to get/set namespaced
settings from/to a specific section:

- Core
- Gui
- Server
- Plugins
- Auth
- App
- Providers
- Misc
%End

%TypeHeaderCode
#include "qgssettings.h"
%End
  public:

    enum Section /BaseType=IntEnum/
    {
      NoSection,
      Core,
      Gui,
      Server,
      Plugins,
      Auth,
      App,
      Providers,
      Expressions,
      Misc,
      Gps,
    };

    explicit QgsSettings( const QString &organization,
                          const QString &application = QString(), QObject *parent = 0 );
%Docstring
Constructs 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
Constructs 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
:py:func:`~QgsSettings.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
Constructs 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
Constructs 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
:py:func:`~QgsSettings.defaultFormat` (QSettings.NativeFormat by
default). Use :py:func:`~QgsSettings.setDefaultFormat` before calling
this constructor to change the default format used by this constructor.
%End
    ~QgsSettings();

    void beginGroup( const QString &prefix, 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 :py:func:`~QgsSettings.childGroups`,
:py:func:`~QgsSettings.childKeys`, and :py:func:`~QgsSettings.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
:py:func:`~QgsSettings.beginGroup` call.
%End

    QString group() const;
%Docstring
Returns the current group.

.. seealso:: :py:func:`beginGroup`

.. seealso:: :py:func:`endGroup`

.. versionadded:: 3.6
%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( Qgis::SettingsOrigin origin = Qgis::SettingsOrigin::Any ) 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
:py:func:`~QgsSettings.beginReadArray` or
:py:func:`~QgsSettings.beginWriteArray`.
%End

    void setArrayIndex( int i );
%Docstring
Sets the current array index to i. Calls to functions such as
:py:func:`~QgsSettings.setValue`, :py:func:`~QgsSettings.value`,
:py:func:`~QgsSettings.remove`, and :py:func:`~QgsSettings.contains`
will operate on the array entry at that index.
%End

    Qgis::SettingsOrigin origin( const QString &key ) const;
%Docstring
Returns the origin of the setting if it exists at the given ``key``

.. note::

   it will return :py:class:`Qgis`.SettingsOrigin.Any if the key doesn't exist

.. versionadded:: 3.30
%End

    void setValue( const QString &key, const QVariant &value, 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 *( *pyqt_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

    pyqt_from_qvariant_by_type f = ( pyqt_from_qvariant_by_type ) sipImportSymbol( SIP_PYQT_FROM_QVARIANT_BY_TYPE );
    sipRes = f( value, a2 );

    sipIsErr = !sipRes;
%End



    bool contains( const QString &key, 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 :py:func:`~QgsSettings.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, 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, 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/settings/qgssettings.h                                      *
 *                                                                      *
 * Do not edit manually ! Edit header and run scripts/sipify.py again   *
 ************************************************************************/