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









class QgsSettingsEntryBase
{
%Docstring(signature="appended")
Represent settings entry and provides methods for reading and writing
settings values. Different subclasses are provided for different
settings types with metainformations to validate set values and provide
more accurate settings description for the gui.

.. versionadded:: 3.20
%End

%TypeHeaderCode
#include "qgssettingsentry.h"
%End
%ConvertToSubClassCode
    if ( dynamic_cast< QgsSettingsEntryVariant * >( sipCpp ) )
      sipType = sipType_QgsSettingsEntryVariant;
    else if ( dynamic_cast< QgsSettingsEntryString * >( sipCpp ) )
      sipType = sipType_QgsSettingsEntryString;
    else if ( dynamic_cast< QgsSettingsEntryStringList * >( sipCpp ) )
      sipType = sipType_QgsSettingsEntryStringList;
    else if ( dynamic_cast< QgsSettingsEntryVariantMap * >( sipCpp ) )
      sipType = sipType_QgsSettingsEntryVariantMap;
    else if ( dynamic_cast< QgsSettingsEntryBool * >( sipCpp ) )
      sipType = sipType_QgsSettingsEntryBool;
    else if ( dynamic_cast< QgsSettingsEntryInteger * >( sipCpp ) )
      sipType = sipType_QgsSettingsEntryInteger;
    else if ( dynamic_cast< QgsSettingsEntryDouble * >( sipCpp ) )
      sipType = sipType_QgsSettingsEntryDouble;
    else if ( dynamic_cast< QgsSettingsEntryColor * >( sipCpp ) )
      sipType = sipType_QgsSettingsEntryColor;
    else if ( dynamic_cast< QgsSettingsEntryBase * >( sipCpp ) )
      sipType = sipType_QgsSettingsEntryBase;
    else
      sipType = NULL;
%End
  public:

    static QStringList dynamicKeyPartToList( const QString &dynamicKeyPart );
%Docstring
Transforms a dynamic key part string to list

.. versionadded:: 3.26
%End

    QgsSettingsEntryBase( const QString &key,
                          const QString &section,
                          const QVariant &defaultValue = QVariant(),
                          const QString &description = QString(),
                          Qgis::SettingsOptions options = Qgis::SettingsOptions() );
%Docstring
Constructor for QgsSettingsEntryBase.

:param key: specifies the key of the settings.
:param section: specifies the section.
:param defaultValue: specifies the default value for the settings entry.
:param description: specifies a description for the settings entry.
:param options: specifies the options for the settings entry.
%End

    QgsSettingsEntryBase( const QString &name,
                          QgsSettingsTreeNode *parent,
                          const QVariant &defaultValue = QVariant(),
                          const QString &description = QString(),
                          Qgis::SettingsOptions options = Qgis::SettingsOptions() ) throw( QgsSettingsException );
%Docstring
Constructor for QgsSettingsEntryBase.

:param name: specifies the name of the setting.
:param parent: specifies the parent in the tree of settings.
:param defaultValue: specifies the default value for the settings entry.
:param description: specifies a description for the settings entry.
:param options: specifies the options for the settings entry.

:raises QgsSettingsException: if the number of given parent named items
                              doesn't match the complete key definition

.. versionadded:: 3.30
%End

    virtual ~QgsSettingsEntryBase();

    virtual QString typeId() const;
%Docstring
Returns the id of the type of settings This can be re-implemented in a
custom implementation of a setting

.. versionadded:: 3.32
%End

    QString name() const;
%Docstring
Returns the name of the settings

.. versionadded:: 3.30
%End

    QString key( const QString &dynamicKeyPart = QString() ) const;
%Docstring
Returns settings entry key.

:param dynamicKeyPart: specifies the dynamic part of the settings key.
%End

    QString key( const QStringList &dynamicKeyPartList ) const;
%Docstring
Returns settings entry key.

:param dynamicKeyPartList: specifies the list of dynamic parts of the
                           settings key.
%End

    bool keyIsValid( const QString &key ) const;
%Docstring
Returns ``True`` if the provided key match the settings entry.

This is useful for settings with dynamic keys. For example this permits
one to check that the settings key
"NewsFeed/httpsfeedqgisorg/27/content" is valid for the settings entry
defined with the key "NewsFeed/%1/%2/content"

:param key: to check
%End

    QString definitionKey() const;
%Docstring
Returns settings entry defining key. For dynamic settings it return the
key with the placeholder for dynamic part included. For non-dynamic
settings returns the same as :py:func:`~QgsSettingsEntryBase.key`.
%End

    bool hasDynamicKey() const;
%Docstring
Returns ``True`` if a part of the settings key is built dynamically.
%End

    Qgis::SettingsOptions options() const;
%Docstring
Returns the settings options

.. versionadded:: 3.26
%End

    bool exists( const QString &dynamicKeyPart = QString() ) const;
%Docstring
Returns ``True`` if the settings is contained in the underlying
QSettings.

:param dynamicKeyPart: specifies the dynamic part of the settings key.
%End

    bool exists( const QStringList &dynamicKeyPartList ) const;
%Docstring
Returns ``True`` if the settings is contained in the underlying
QSettings.

:param dynamicKeyPartList: specifies the list of dynamic parts of the
                           settings key.
%End

    Qgis::SettingsOrigin origin( const QStringList &dynamicKeyPartList ) const;
%Docstring
Returns the origin of the setting if it exists

.. note::

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

.. versionadded:: 3.30
%End

    void remove( const QString &dynamicKeyPart = QString() ) const;
%Docstring
Removes the settings from the underlying QSettings.

:param dynamicKeyPart: specifies the dynamic part of the settings key.
%End

    void remove( const QStringList &dynamicKeyPartList ) const;
%Docstring
Removes the settings from the underlying QSettings.

:param dynamicKeyPartList: specifies the list of dynamic parts of the
                           settings key.
%End

 int section() const;
%Docstring
Returns settings section. The settings section of the parent group is
returned if available.

.. deprecated:: 3.26

   The key is entirely self-defined.
%End

    bool setVariantValue( const QVariant &value, const QString &dynamicKeyPart = QString() ) const;
%Docstring
Set settings value.

:param value: specifies the value to set.
:param dynamicKeyPart: specifies the dynamic part of the settings key.
%End

    bool setVariantValue( const QVariant &value, const QStringList &dynamicKeyPartList ) const;
%Docstring
Set settings value. This should be called from any implementation as it
takes care of actually calling QSettings

:param value: specifies the value to set.
:param dynamicKeyPartList: specifies the list of dynamic parts of the
                           settings key.
%End

    QVariant valueAsVariant( const QString &dynamicKeyPart = QString() ) const;
%Docstring
Returns settings value with:param dynamicKeyPart: specifying the dynamic
part of the settings key.
%End

    QVariant valueAsVariant( const QStringList &dynamicKeyPartList ) const;
%Docstring
Returns settings value with:param dynamicKeyPartList: specifying the
dynamic part of the settings key.
%End

    QVariant valueAsVariantWithDefaultOverride( const QVariant &defaultValueOverride, const QString &dynamicKeyPart = QString() ) const;
%Docstring
Returns settings value with a ``defaultValueOverride``

.. versionadded:: 3.26
%End

    QVariant valueAsVariantWithDefaultOverride( const QVariant &defaultValueOverride, const QStringList &dynamicKeyPartList ) const;
%Docstring
Returns settings value.

:param dynamicKeyPartList: specifies the list of dynamic parts of the
                           settings key.
:param defaultValueOverride: if valid is used instead of the normal
                             default value.

.. versionadded:: 3.26
%End

 QVariant valueAsVariant( const QString &dynamicKeyPart, bool useDefaultValueOverride, const QVariant &defaultValueOverride ) const /Deprecated/;
%Docstring
Returns settings value with an optional default value override

.. deprecated:: 3.26

   Use valueAsVariantWithDefaultOverride instead.
%End

 QVariant valueAsVariant( const QStringList &dynamicKeyPartList, bool useDefaultValueOverride, const QVariant &defaultValueOverride ) const /Deprecated/;
%Docstring
Returns settings value with an optional default value override

.. deprecated:: 3.26

   Use valueAsVariantWithDefaultOverride instead.
%End


    QVariant defaultValueAsVariant() const;
%Docstring
Returns settings default value.
%End

    virtual Qgis::SettingsType settingsType() const;
%Docstring
Returns the settings entry type.
%End

    QString description() const;
%Docstring
Returns the settings entry description.
%End

    QVariant formerValueAsVariant( const QString &dynamicKeyPart ) const;
%Docstring
Returns the former value of the settings if it has been enabled in the
options. Returns the current value (or default) if there is no former
value.

.. versionadded:: 3.26
%End

    QVariant formerValueAsVariant( const QStringList &dynamicKeyPartList ) const;
%Docstring
Returns the former value of the settings if it has been enabled in the
options Returns the current value (or default) if there is no former
value.

.. versionadded:: 3.26
%End

    bool copyValueFromKey( const QString &key, bool removeSettingAtKey = false ) const;
%Docstring
Copies the value from a given key if it exists.

:param key: the key to copy the setting value from.
:param removeSettingAtKey: if ``True``, the setting at the old key will
                           be removed.

:return: ``True`` if the key exists and the setting value could be
         copied.

.. versionadded:: 3.30
%End

    bool copyValueFromKey( const QString &key, const QStringList &dynamicKeyPartList, bool removeSettingAtKey = false ) const;
%Docstring
Copies the value from a given key if it exists.

:param key: the key to copy the setting value from.
:param dynamicKeyPartList: is the optional dynamic key part to determine
                           the key. It must be the same for origin and
                           destination keys.
:param removeSettingAtKey: if ``True``, the setting at the old key will
                           be removed.

:return: ``True`` if the key exists and the setting value could be
         copied.

.. versionadded:: 3.30
%End

    void copyValueToKey( const QString &key, const QStringList &dynamicKeyPartList = QStringList() ) const;
%Docstring
Copies the settings to the given key.

:param key: the key to copy the setting value to.
:param dynamicKeyPartList: is the optional dynamic key part to determine
                           the key. It must be the same for origin and
                           destination keys.

.. versionadded:: 3.30
%End

    void copyValueToKeyIfChanged( const QString &key, const QStringList &dynamicKeyPartList = QStringList() ) const;
%Docstring
Copies the settings to the given key, if it has changed during the
current QGIS session (see :py:func:`~QgsSettingsEntryBase.hasChanged`).

:param key: the key to copy the setting value to.
:param dynamicKeyPartList: is the optional dynamic key part to determine
                           the key. It must be the same for origin and
                           destination keys.

.. versionadded:: 3.36
%End

    QgsSettingsTreeNode *parent() const;
%Docstring
Returns the parent tree element

.. versionadded:: 3.30
%End

    virtual bool checkValueVariant( const QVariant &value ) const;
%Docstring
Returns ``True`` if the given ``value`` is valid towards the setting
definition
%End

    bool hasChanged() const;
%Docstring
Returns ``True`` if the setting was changed during the current QGIS
session.

.. versionadded:: 3.36
%End

};

template<T>
class QgsSettingsEntryBaseTemplate : QgsSettingsEntryBase
{
%Docstring(signature="appended")
Base abstract class for settings entries with typed get and set methods

.. seealso:: :py:class:`QgsSettingsEntryBase`

.. versionadded:: 3.32
%End

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

    QgsSettingsEntryBaseTemplate( const QString &name,
                                  QgsSettingsTreeNode *parent,
                                  const QVariant &defaultValue,
                                  const QString &description = QString(),
                                  Qgis::SettingsOptions options = Qgis::SettingsOptions() );
%Docstring
Constructor for :py:class:`QgsSettingsEntryByReference`.

:param name: specifies the key of the settings.
:param parent: specifies the parent in the tree of settings.
:param defaultValue: specifies the default value for the settings entry.
:param description: specifies a description for the settings entry.
:param options: specifies the options for the settings entry.

:raises QgsSettingsException: if the number of given parent named items
                              doesn't match the complete key definition

.. versionadded:: 3.30
%End

    QgsSettingsEntryBaseTemplate( const QString &key,
                                  const QString &section,
                                  const QVariant &defaultValue,
                                  const QString &description = QString(),
                                  Qgis::SettingsOptions options = Qgis::SettingsOptions() );
%Docstring
Constructor for :py:class:`QgsSettingsEntryByReference`.

:param key: specifies the key of the settings.
:param section: specifies the section.
:param defaultValue: specifies the default value for the settings entry.
:param description: specifies a description for the settings entry.
:param options: specifies the options for the settings entry.
%End


    virtual Qgis::SettingsType settingsType() const = 0;

    T value( const QString &dynamicKeyPart = QString() ) const;
%Docstring
Returns settings value.

:param dynamicKeyPart: specifies the dynamic part of the settings key.
%End

    T value( const QStringList &dynamicKeyPartList )  const;
%Docstring
Returns settings value.

:param dynamicKeyPartList: specifies the list of dynamic parts of the
                           settings key.
%End


    T valueWithDefaultOverride( const T &defaultValueOverride, const QString &dynamicKeyPart = QString() ) const;
%Docstring
Returns the settings value with a ``defaultValueOverride`` and with an
optional ``dynamicKeyPart``
%End

    T valueWithDefaultOverride( const T &defaultValueOverride, const QStringList &dynamicKeyPartList ) const;
%Docstring
Returns the settings value with a ``defaultValueOverride`` for the
``dynamicKeyPartList``
%End

    bool setValue( const T &value, const QString &dynamicKeyPart = QString() ) const;
%Docstring
Set settings value.

:param value: specifies the value to set.
:param dynamicKeyPart: specifies the dynamic part of the settings key.
%End

    bool setValue( const T &value, const QStringList &dynamicKeyPartList ) const;
%Docstring
Set settings value.

:param value: specifies the value to set.
:param dynamicKeyPartList: specifies the list of dynamic parts of the
                           settings key.
%End

    T defaultValue() const;
%Docstring
Returns settings default value.
%End

    T formerValue( const QString &dynamicKeyPart = QString() ) const;
%Docstring
Returns the former value. Returns the current value (or default) if
there is no former value.
%End

    T formerValue( const QStringList &dynamicKeyPartList ) const;
%Docstring
Returns the former value Returns the current value (or default) if there
is no former value.
%End

    virtual bool checkValueVariant( const QVariant &value ) const;

    virtual T convertFromVariant( const QVariant &value ) const = 0;
%Docstring
Converts the variant value to the value type of the setting
%End

  protected:
    virtual bool setValuePrivate( const T &value, const QStringList &dynamicKeyPartList ) const;
%Docstring
Sets the settings value with an optional list of dynamic parts
%End

    virtual QVariant convertToVariant( const T &value ) const;
%Docstring
Converts the value to a variant
%End

    virtual bool checkValuePrivate( const T &value ) const;
%Docstring
Check if the value is valid
%End
};




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