From f9e21602d2f90424a84b5bbfae841f337405d2ae Mon Sep 17 00:00:00 2001 From: Denis Rouzaud Date: Tue, 31 Jan 2023 16:48:08 +0100 Subject: [PATCH] add name method for settings + improve dox (#51661) --- python/core/additions/qgssettingsentry.py | 2 +- .../settings/qgssettingsentry.sip.in | 130 +++++++++-------- .../settings/qgssettingsentryimpl.sip.in | 32 ++--- src/core/settings/qgssettingsentry.cpp | 11 +- src/core/settings/qgssettingsentry.h | 135 ++++++++++-------- src/core/settings/qgssettingsentryenumflag.h | 24 ++-- src/core/settings/qgssettingsentryimpl.h | 54 +++---- tests/src/python/test_qgssettingsentry.py | 1 + 8 files changed, 205 insertions(+), 184 deletions(-) diff --git a/python/core/additions/qgssettingsentry.py b/python/core/additions/qgssettingsentry.py index 6bd23ccb898..b3fc35eaf63 100644 --- a/python/core/additions/qgssettingsentry.py +++ b/python/core/additions/qgssettingsentry.py @@ -39,7 +39,7 @@ class PyQgsSettingsEntryEnumFlag(QgsSettingsEntryBase): :param description: argument specifies a description for the settings entry. """ - # TODO QGIS 4: rename pluginName arg to parent + # TODO QGIS 4: rename pluginName arg to parent and key to name self.options = options defaultValueStr = str() diff --git a/python/core/auto_generated/settings/qgssettingsentry.sip.in b/python/core/auto_generated/settings/qgssettingsentry.sip.in index 1528bea7d88..5601ca48611 100644 --- a/python/core/auto_generated/settings/qgssettingsentry.sip.in +++ b/python/core/auto_generated/settings/qgssettingsentry.sip.in @@ -64,44 +64,53 @@ Transforms a dynamic key part string to list %Docstring Constructor for QgsSettingsEntryBase. -\arg key specifies the key of the settings. -\arg section specifies the section. -\arg defaultValue specifies the default value for the settings entry. -\arg description specifies a description for the settings entry. -\arg options specifies the options for the settings entry. +: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 &key, - QgsSettingsTreeNode *parentTreeElement, + 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. -\arg key specifies the key of the settings. -\arg parent specifies the parent in the tree of settings. -\arg defaultValue specifies the default value for the settings entry. -\arg description specifies a description for the settings entry. -\arg options specifies the options for the settings entry. +: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(); + 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. -\arg dynamicKeyPart specifies the dynamic part of the settings key. +:param dynamicKeyPart: specifies the dynamic part of the settings key. %End QString key( const QStringList &dynamicKeyPartList ) const; %Docstring Returns settings entry key. -\arg dynamicKeyParts specifies the list of dynamic parts of the settings key. +:param dynamicKeyPartList: specifies the list of dynamic parts of the settings key. %End bool keyIsValid( const QString &key ) const; @@ -112,7 +121,7 @@ This is useful for settings with dynamic keys. For example this permits one to c the settings key "NewsFeed/httpsfeedqgisorg/27/content" is valid for the settings entry defined with the key "NewsFeed/%1/%2/content" -\arg key to check +:param key: to check %End QString definitionKey() const; @@ -138,14 +147,14 @@ Returns the settings options %Docstring Returns ``True`` if the settings is contained in the underlying QSettings. -\arg dynamicKeyPart specifies the dynamic part of the settings key. +: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. -\arg dynamicKeyParts specifies the list of dynamic parts of the settings key. +:param dynamicKeyPartList: specifies the list of dynamic parts of the settings key. %End Qgis::SettingsOrigin origin( const QStringList &dynamicKeyPartList ) const; @@ -163,14 +172,14 @@ Returns the origin of the setting if it exists %Docstring Removes the settings from the underlying QSettings. -\arg dynamicKeyPart specifies the dynamic part of the settings key. +: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. -\arg dynamicKeyParts specifies the list of dynamic parts of the settings key. +:param dynamicKeyPartList: specifies the list of dynamic parts of the settings key. %End QgsSettings::Section section() const; @@ -185,8 +194,8 @@ Returns settings section. The settings section of the parent group is returned i %Docstring Set settings value. -The ``value`` to set. -\arg dynamicKeyPart specifies the dynamic part of the settings key. +:param value: specifies the value to set. +:param dynamicKeyPart: specifies the dynamic part of the settings key. .. deprecated:: QGIS 3.26 use setVariantValuePrivate or an implementation setValue instead @@ -196,8 +205,8 @@ The ``value`` to set. %Docstring Set settings value. -The ``value`` to set. -\arg dynamicKeyParts specifies the list of dynamic parts of the settings key. +:param value: specifies the value to set. +:param dynamicKeyPartList: specifies the list of dynamic parts of the settings key. .. deprecated:: QGIS 3.26 use setVariantValuePrivate or an implementation setValue instead @@ -205,12 +214,12 @@ The ``value`` to set. QVariant valueAsVariant( const QString &dynamicKeyPart = QString() ) const; %Docstring -Returns settings value with \arg dynamicKeyPart specifying the dynamic part of the settings key. +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 \arg dynamicKeyPart specifying the dynamic part of the settings key. +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; @@ -224,8 +233,8 @@ Returns settings value with a ``defaultValueOverride`` %Docstring Returns settings value. -\arg dynamicKeyPartList specifies the list of dynamic parts of the settings key. -\arg defaultValueOverride if valid is used instead of the normal default 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 @@ -352,7 +361,7 @@ Base abstract class for settings entry which are passed by reference %End public: - QgsSettingsEntryByReference( const QString &key, + QgsSettingsEntryByReference( const QString &name, QgsSettingsTreeNode *parent, const T &defaultValue, const QString &description = QString(), @@ -360,13 +369,15 @@ Base abstract class for settings entry which are passed by reference %Docstring Constructor for QgsSettingsEntryByReference. -\arg key specifies the key of the settings. -\arg parent specifies the parent in the tree of settings. -\arg defaultValue specifies the default value for the settings entry. -\arg description specifies a description for the settings entry. -\arg optionss specifies the options for the settings entry. +: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 QgsSettingsEntryByReference( const QString &key, @@ -377,11 +388,11 @@ Constructor for QgsSettingsEntryByReference. %Docstring Constructor for QgsSettingsEntryByReference. -\arg key specifies the key of the settings. -\arg section specifies the section. -\arg defaultValue specifies the default value for the settings entry. -\arg description specifies a description for the settings entry. -\arg optionss specifies the options for the settings entry. +: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 @@ -432,16 +443,16 @@ Returns the settings value for the ``dynamicKeyPartList`` and with a ``defaultV %Docstring Set settings value. -The ``value`` to set. -\arg dynamicKeyPart specifies the dynamic part of the settings key. +: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. -The ``value`` to set. -\arg dynamicKeyParts specifies the list of dynamic parts of the settings key. +:param value: specifies the value to set. +:param dynamicKeyPartList: specifies the list of dynamic parts of the settings key. %End T defaultValue() const; @@ -507,12 +518,11 @@ Base abstract class for settings entry which are passed by value %Docstring Constructor for QgsSettingsEntryByValue. -\arg key specifies the key of the settings. -\arg parent specifies the parent in the tree of settings. -\arg section specifies the section. -\arg defaultValue specifies the default value for the settings entry. -\arg description specifies a description for the settings entry. -\arg optionss specifies the options for the settings entry. +:param key: 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 %End @@ -521,11 +531,11 @@ Constructor for QgsSettingsEntryByValue. %Docstring Constructor for QgsSettingsEntryByValue. -\arg key specifies the key of the settings. -\arg section specifies the section. -\arg defaultValue specifies the default value for the settings entry. -\arg description specifies a description for the settings entry. -\arg optionss specifies the options for the settings entry. +: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; @@ -534,16 +544,14 @@ Constructor for QgsSettingsEntryByValue. %Docstring Returns settings value. -\arg dynamicKeyPart specifies the dynamic part of the settings key. -\arg defaultValueOverride if valid is used instead of the normal default value. +:param dynamicKeyPart: specifies the dynamic part of the settings key. %End T value( const QStringList &dynamicKeyPartList ) const; %Docstring Returns settings value. -\arg dynamicKeyPartList specifies the list of dynamic parts of the settings key. -\arg defaultValueOverride if valid is used instead of the normal default value. +:param dynamicKeyPartList: specifies the list of dynamic parts of the settings key. %End T valueWithDefaultOverride( T defaultValueOverride, const QString &dynamicKeyPart = QString() ) const; @@ -576,16 +584,16 @@ Returns the settings value for the ``dynamicKeyPartList`` and with a ``defaultV %Docstring Set settings value. -The ``value`` to set. -\arg dynamicKeyPart specifies the dynamic part of the settings key. +:param value: specifies the value to set. +:param dynamicKeyPart: specifies the dynamic part of the settings key. %End bool setValue( T value, const QStringList &dynamicKeyPartList ) const; %Docstring Set settings value. -The ``value`` to set. -\arg dynamicKeyParts specifies the list of dynamic parts of the settings key. +:param value: specifies the value to set. +:param dynamicKeyPartList: specifies the list of dynamic parts of the settings key. %End T defaultValue() const; diff --git a/python/core/auto_generated/settings/qgssettingsentryimpl.sip.in b/python/core/auto_generated/settings/qgssettingsentryimpl.sip.in index f64b23fb8ef..e8bdaf5d11c 100644 --- a/python/core/auto_generated/settings/qgssettingsentryimpl.sip.in +++ b/python/core/auto_generated/settings/qgssettingsentryimpl.sip.in @@ -29,7 +29,7 @@ typedef QgsSettingsEntryByReference QgsSettingsEntryByReferenceQVarian public: - QgsSettingsEntryVariant( const QString &key, + QgsSettingsEntryVariant( const QString &name, QgsSettingsTreeNode *parent, const QVariant &defaultValue = QVariant(), const QString &description = QString(), @@ -37,7 +37,7 @@ typedef QgsSettingsEntryByReference QgsSettingsEntryByReferenceQVarian %Docstring Constructor for QgsSettingsEntryVariant. -:param key: specifies the final part of the settings key. +: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. @@ -130,7 +130,7 @@ typedef QgsSettingsEntryByReference QgsSettingsEntryByReferenceQStringB %End public: - QgsSettingsEntryString( const QString &key, + QgsSettingsEntryString( const QString &name, QgsSettingsTreeNode *parent, const QString &defaultValue = QString(), const QString &description = QString(), @@ -140,7 +140,7 @@ typedef QgsSettingsEntryByReference QgsSettingsEntryByReferenceQStringB %Docstring Constructor for QgsSettingsEntryString. -:param key: specifies the final part of the settings key. +: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. @@ -230,7 +230,7 @@ typedef QgsSettingsEntryByReference QgsSettingsEntryByReferenceQStr %End public: - QgsSettingsEntryStringList( const QString &key, + QgsSettingsEntryStringList( const QString &name, QgsSettingsTreeNode *parent, const QStringList &defaultValue = QStringList(), const QString &description = QString(), @@ -238,7 +238,7 @@ typedef QgsSettingsEntryByReference QgsSettingsEntryByReferenceQStr %Docstring Constructor for QgsSettingsEntryStringList. -:param key: specifies the final part of the settings key. +: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. @@ -309,7 +309,7 @@ typedef QgsSettingsEntryByValue QgsSettingsEntryByValueboolBase; %End public: - QgsSettingsEntryBool( const QString &key, + QgsSettingsEntryBool( const QString &name, QgsSettingsTreeNode *parent, bool defaultValue = false, const QString &description = QString(), @@ -317,7 +317,7 @@ typedef QgsSettingsEntryByValue QgsSettingsEntryByValueboolBase; %Docstring Constructor for QgsSettingsEntryBool. -:param key: specifies the final part of the settings key. +: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. @@ -388,7 +388,7 @@ typedef QgsSettingsEntryByValue QgsSettingsEntryByValueintBase; %End public: - QgsSettingsEntryInteger( const QString &key, + QgsSettingsEntryInteger( const QString &name, QgsSettingsTreeNode *parent, int defaultValue = 0, const QString &description = QString(), @@ -398,7 +398,7 @@ typedef QgsSettingsEntryByValue QgsSettingsEntryByValueintBase; %Docstring Constructor for QgsSettingsEntryInteger. -:param key: specifies the final part of the settings key. +: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. @@ -490,7 +490,7 @@ typedef QgsSettingsEntryByValue QgsSettingsEntryByValuedoubleBase; %End public: - QgsSettingsEntryDouble( const QString &key, + QgsSettingsEntryDouble( const QString &name, QgsSettingsTreeNode *parent, double defaultValue = 0.0, const QString &description = QString(), @@ -501,7 +501,7 @@ typedef QgsSettingsEntryByValue QgsSettingsEntryByValuedoubleBase; %Docstring Constructor for QgsSettingsEntryDouble. -:param key: specifies the final part of the settings key. +: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. @@ -614,7 +614,7 @@ typedef QgsSettingsEntryByReference QgsSettingsEntryByReferenceQColorBas %End public: - QgsSettingsEntryColor( const QString &key, + QgsSettingsEntryColor( const QString &name, QgsSettingsTreeNode *parent, const QColor &defaultValue = QColor(), const QString &description = QString(), @@ -623,7 +623,7 @@ typedef QgsSettingsEntryByReference QgsSettingsEntryByReferenceQColorBas %Docstring Constructor for QgsSettingsEntryColor. -:param key: specifies the final part of the settings key. +: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. @@ -709,7 +709,7 @@ typedef QgsSettingsEntryByReference QgsSettingsEntryByReferenceQVar public: - QgsSettingsEntryVariantMap( const QString &key, + QgsSettingsEntryVariantMap( const QString &name, QgsSettingsTreeNode *parent, const QVariantMap &defaultValue = QVariantMap(), const QString &description = QString(), @@ -717,7 +717,7 @@ typedef QgsSettingsEntryByReference QgsSettingsEntryByReferenceQVar %Docstring Constructor for QgsSettingsEntryVariantMap. -:param key: specifies the final part of the settings key. +: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. diff --git a/src/core/settings/qgssettingsentry.cpp b/src/core/settings/qgssettingsentry.cpp index 4a096eb6bae..77875dd7490 100644 --- a/src/core/settings/qgssettingsentry.cpp +++ b/src/core/settings/qgssettingsentry.cpp @@ -20,17 +20,18 @@ #include -QgsSettingsEntryBase::QgsSettingsEntryBase( const QString &key, QgsSettingsTreeNode *parentTreeElement, const QVariant &defaultValue, const QString &description, Qgis::SettingsOptions options ) - : mParentTreeElement( parentTreeElement ) +QgsSettingsEntryBase::QgsSettingsEntryBase( const QString &key, QgsSettingsTreeNode *parent, const QVariant &defaultValue, const QString &description, Qgis::SettingsOptions options ) + : mParentTreeElement( parent ) + , mName( key ) , mDefaultValue( defaultValue ) , mDescription( description ) , mOptions( options ) { - mKey = QDir::cleanPath( QStringLiteral( "%1/%2" ).arg( parentTreeElement ? parentTreeElement->completeKey() : QString(), key ) ); + mKey = QDir::cleanPath( QStringLiteral( "%1/%2" ).arg( parent ? parent->completeKey() : QString(), key ) ); - if ( parentTreeElement ) + if ( parent ) { - parentTreeElement->registerChildSetting( this, key ); + parent->registerChildSetting( this, key ); } } diff --git a/src/core/settings/qgssettingsentry.h b/src/core/settings/qgssettingsentry.h index a8fca4cbbeb..57a86429a7b 100644 --- a/src/core/settings/qgssettingsentry.h +++ b/src/core/settings/qgssettingsentry.h @@ -77,18 +77,19 @@ class CORE_EXPORT QgsSettingsEntryBase /** * Constructor for QgsSettingsEntryBase. * - * \arg key specifies the key of the settings. - * \arg section specifies the section. - * \arg defaultValue specifies the default value for the settings entry. - * \arg description specifies a description for the settings entry. - * \arg options specifies the options for the settings entry. + * \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. */ QgsSettingsEntryBase( const QString &key, const QString §ion, const QVariant &defaultValue = QVariant(), const QString &description = QString(), Qgis::SettingsOptions options = Qgis::SettingsOptions() ) - : mKey( QStringLiteral( "%1/%2" ).arg( section, key ) ) + : mName( key ) + , mKey( QStringLiteral( "%1/%2" ).arg( section, key ) ) , mDefaultValue( defaultValue ) , mDescription( description ) , mOptions( options ) @@ -97,15 +98,17 @@ class CORE_EXPORT QgsSettingsEntryBase /** * Constructor for QgsSettingsEntryBase. * - * \arg key specifies the key of the settings. - * \arg parent specifies the parent in the tree of settings. - * \arg defaultValue specifies the default value for the settings entry. - * \arg description specifies a description for the settings entry. - * \arg options specifies the options for the settings entry. + * \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. * \throws QgsSettingsException if the number of given parent named items doesn't match the complete key definition + * + * \since QGIS 3.30 */ - QgsSettingsEntryBase( const QString &key, - QgsSettingsTreeNode *parentTreeElement, + QgsSettingsEntryBase( const QString &name, + QgsSettingsTreeNode *parent, const QVariant &defaultValue = QVariant(), const QString &description = QString(), Qgis::SettingsOptions options = Qgis::SettingsOptions() ) SIP_THROW( QgsSettingsException ); @@ -115,17 +118,23 @@ class CORE_EXPORT QgsSettingsEntryBase */ virtual ~QgsSettingsEntryBase(); + /** + * Returns the name of the settings + * \since QGIS 3.30 + */ + QString name() const {return mName;} + /** * Returns settings entry key. * - * \arg dynamicKeyPart specifies the dynamic part of the settings key. + * \param dynamicKeyPart specifies the dynamic part of the settings key. */ QString key( const QString &dynamicKeyPart = QString() ) const; /** * Returns settings entry key. * - * \arg dynamicKeyParts specifies the list of dynamic parts of the settings key. + * \param dynamicKeyPartList specifies the list of dynamic parts of the settings key. */ QString key( const QStringList &dynamicKeyPartList ) const; @@ -136,7 +145,7 @@ class CORE_EXPORT QgsSettingsEntryBase * the settings key "NewsFeed/httpsfeedqgisorg/27/content" is valid for the settings entry * defined with the key "NewsFeed/%1/%2/content" * - * \arg key to check + * \param key to check */ bool keyIsValid( const QString &key ) const; @@ -161,14 +170,14 @@ class CORE_EXPORT QgsSettingsEntryBase /** * Returns TRUE if the settings is contained in the underlying QSettings. * - * \arg dynamicKeyPart specifies the dynamic part of the settings key. + * \param dynamicKeyPart specifies the dynamic part of the settings key. */ bool exists( const QString &dynamicKeyPart = QString() ) const; /** * Returns TRUE if the settings is contained in the underlying QSettings. * - * \arg dynamicKeyParts specifies the list of dynamic parts of the settings key. + * \param dynamicKeyPartList specifies the list of dynamic parts of the settings key. */ bool exists( const QStringList &dynamicKeyPartList ) const; @@ -182,14 +191,14 @@ class CORE_EXPORT QgsSettingsEntryBase /** * Removes the settings from the underlying QSettings. * - * \arg dynamicKeyPart specifies the dynamic part of the settings key. + * \param dynamicKeyPart specifies the dynamic part of the settings key. */ void remove( const QString &dynamicKeyPart = QString() ) const; /** * Removes the settings from the underlying QSettings. * - * \arg dynamicKeyParts specifies the list of dynamic parts of the settings key. + * \param dynamicKeyPartList specifies the list of dynamic parts of the settings key. */ void remove( const QStringList &dynamicKeyPartList ) const; @@ -202,8 +211,8 @@ class CORE_EXPORT QgsSettingsEntryBase /** * Set settings value. * - * The \a value to set. - * \arg dynamicKeyPart specifies the dynamic part of the settings key. + * \param value specifies the value to set. + * \param dynamicKeyPart specifies the dynamic part of the settings key. * \deprecated since QGIS 3.26 use setVariantValuePrivate or an implementation setValue instead */ Q_DECL_DEPRECATED virtual bool setVariantValue( const QVariant &value, const QString &dynamicKeyPart = QString() ) const SIP_DEPRECATED; @@ -211,16 +220,16 @@ class CORE_EXPORT QgsSettingsEntryBase /** * Set settings value. * - * The \a value to set. - * \arg dynamicKeyParts specifies the list of dynamic parts of the settings key. + * \param value specifies the value to set. + * \param dynamicKeyPartList specifies the list of dynamic parts of the settings key. * \deprecated since QGIS 3.26 use setVariantValuePrivate or an implementation setValue instead */ Q_DECL_DEPRECATED virtual bool setVariantValue( const QVariant &value, const QStringList &dynamicKeyPartList ) const SIP_DEPRECATED; - //! Returns settings value with \arg dynamicKeyPart specifying the dynamic part of the settings key. + //! Returns settings value with \param dynamicKeyPart specifying the dynamic part of the settings key. QVariant valueAsVariant( const QString &dynamicKeyPart = QString() ) const; - //! Returns settings value with \arg dynamicKeyPart specifying the dynamic part of the settings key. + //! Returns settings value with \param dynamicKeyPartList specifying the dynamic part of the settings key. QVariant valueAsVariant( const QStringList &dynamicKeyPartList ) const; /** @@ -232,8 +241,8 @@ class CORE_EXPORT QgsSettingsEntryBase /** * Returns settings value. * - * \arg dynamicKeyPartList specifies the list of dynamic parts of the settings key. - * \arg defaultValueOverride if valid is used instead of the normal default 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. * \since QGIS 3.26 */ QVariant valueAsVariantWithDefaultOverride( const QVariant &defaultValueOverride, const QStringList &dynamicKeyPartList ) const; @@ -329,6 +338,7 @@ class CORE_EXPORT QgsSettingsEntryBase QString completeKeyPrivate( const QString &key, const QStringList &dynamicKeyPartList ) const; QgsSettingsTreeNode *mParentTreeElement = nullptr; + QString mName; QString mKey; QVariant mDefaultValue; QString mDescription; @@ -354,29 +364,31 @@ class QgsSettingsEntryByReference : public QgsSettingsEntryBase /** * Constructor for QgsSettingsEntryByReference. * - * \arg key specifies the key of the settings. - * \arg parent specifies the parent in the tree of settings. - * \arg defaultValue specifies the default value for the settings entry. - * \arg description specifies a description for the settings entry. - * \arg optionss specifies the options for the settings entry. + * \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. * \throws QgsSettingsException if the number of given parent named items doesn't match the complete key definition + * + * \since QGIS 3.30 */ - QgsSettingsEntryByReference( const QString &key, + QgsSettingsEntryByReference( const QString &name, QgsSettingsTreeNode *parent, const T &defaultValue, const QString &description = QString(), Qgis::SettingsOptions options = Qgis::SettingsOptions() ) - : QgsSettingsEntryBase( key, parent, defaultValue, description, options ) + : QgsSettingsEntryBase( name, parent, defaultValue, description, options ) {} /** * Constructor for QgsSettingsEntryByReference. * - * \arg key specifies the key of the settings. - * \arg section specifies the section. - * \arg defaultValue specifies the default value for the settings entry. - * \arg description specifies a description for the settings entry. - * \arg optionss specifies the options for the settings entry. + * \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. */ QgsSettingsEntryByReference( const QString &key, const QString §ion, @@ -443,8 +455,8 @@ class QgsSettingsEntryByReference : public QgsSettingsEntryBase /** * Set settings value. * - * The \a value to set. - * \arg dynamicKeyPart specifies the dynamic part of the settings key. + * \param value specifies the value to set. + * \param dynamicKeyPart specifies the dynamic part of the settings key. */ bool setValue( const T &value, const QString &dynamicKeyPart = QString() ) const { @@ -454,8 +466,8 @@ class QgsSettingsEntryByReference : public QgsSettingsEntryBase /** * Set settings value. * - * The \a value to set. - * \arg dynamicKeyParts specifies the list of dynamic parts of the settings key. + * \param value specifies the value to set. + * \param dynamicKeyPartList specifies the list of dynamic parts of the settings key. */ bool setValue( const T &value, const QStringList &dynamicKeyPartList ) const { @@ -523,12 +535,11 @@ class QgsSettingsEntryByValue : public QgsSettingsEntryBase /** * Constructor for QgsSettingsEntryByValue. * - * \arg key specifies the key of the settings. - * \arg parent specifies the parent in the tree of settings. - * \arg section specifies the section. - * \arg defaultValue specifies the default value for the settings entry. - * \arg description specifies a description for the settings entry. - * \arg optionss specifies the options for the settings entry. + * \param key 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. * \throws QgsSettingsException if the number of given parent named items doesn't match the complete key definition */ QgsSettingsEntryByValue( const QString &key, QgsSettingsTreeNode *parent, QVariant defaultValue, const QString &description = QString(), Qgis::SettingsOptions options = Qgis::SettingsOptions() ) @@ -538,11 +549,11 @@ class QgsSettingsEntryByValue : public QgsSettingsEntryBase /** * Constructor for QgsSettingsEntryByValue. * - * \arg key specifies the key of the settings. - * \arg section specifies the section. - * \arg defaultValue specifies the default value for the settings entry. - * \arg description specifies a description for the settings entry. - * \arg optionss specifies the options for the settings entry. + * \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. */ QgsSettingsEntryByValue( const QString &key, const QString §ion, QVariant defaultValue, const QString &description = QString(), Qgis::SettingsOptions options = Qgis::SettingsOptions() ) : QgsSettingsEntryBase( key, section, defaultValue, description, options ) @@ -553,16 +564,14 @@ class QgsSettingsEntryByValue : public QgsSettingsEntryBase /** * Returns settings value. * - * \arg dynamicKeyPart specifies the dynamic part of the settings key. - * \arg defaultValueOverride if valid is used instead of the normal default value. + * \param dynamicKeyPart specifies the dynamic part of the settings key. */ T value( const QString &dynamicKeyPart = QString() ) const { return this->convertFromVariant( valueAsVariant( dynamicKeyPart ) );} /** * Returns settings value. * - * \arg dynamicKeyPartList specifies the list of dynamic parts of the settings key. - * \arg defaultValueOverride if valid is used instead of the normal default value. + * \param dynamicKeyPartList specifies the list of dynamic parts of the settings key. */ T value( const QStringList &dynamicKeyPartList ) const { return this->convertFromVariant( valueAsVariant( dynamicKeyPartList ) );} @@ -605,8 +614,8 @@ class QgsSettingsEntryByValue : public QgsSettingsEntryBase /** * Set settings value. * - * The \a value to set. - * \arg dynamicKeyPart specifies the dynamic part of the settings key. + * \param value specifies the value to set. + * \param dynamicKeyPart specifies the dynamic part of the settings key. */ bool setValue( T value, const QString &dynamicKeyPart = QString() ) const { @@ -616,8 +625,8 @@ class QgsSettingsEntryByValue : public QgsSettingsEntryBase /** * Set settings value. * - * The \a value to set. - * \arg dynamicKeyParts specifies the list of dynamic parts of the settings key. + * \param value specifies the value to set. + * \param dynamicKeyPartList specifies the list of dynamic parts of the settings key. */ bool setValue( T value, const QStringList &dynamicKeyPartList ) const { diff --git a/src/core/settings/qgssettingsentryenumflag.h b/src/core/settings/qgssettingsentryenumflag.h index 935128b73d2..3676463f5b3 100644 --- a/src/core/settings/qgssettingsentryenumflag.h +++ b/src/core/settings/qgssettingsentryenumflag.h @@ -38,16 +38,18 @@ class QgsSettingsEntryEnumFlag : public QgsSettingsEntryByValue /** * Constructor for QgsSettingsEntryEnumFlagBase. * - * The \a key argument specifies the final part of the settings key. - * The \a parent argument specifies the parent in the tree of settings. - * The \a defaultValue argument specifies the default value for the settings entry. - * The \a description argument specifies a description for the settings entry. + * \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. * * \note The enum needs to be declared with Q_ENUM, and flags with Q_FLAG (not Q_FLAGS). * \note for Python bindings, a custom implementation is achieved in Python directly + * \since QGIS 3.30 */ - QgsSettingsEntryEnumFlag( const QString &key, QgsSettingsTreeNode *parent, T defaultValue, const QString &description = QString(), Qgis::SettingsOptions options = Qgis::SettingsOptions() ) - : QgsSettingsEntryByValue( key, + QgsSettingsEntryEnumFlag( const QString &name, QgsSettingsTreeNode *parent, T defaultValue, const QString &description = QString(), Qgis::SettingsOptions options = Qgis::SettingsOptions() ) + : QgsSettingsEntryByValue( name, parent, QMetaEnum::fromType().isFlag() ? qgsFlagValueToKeys( defaultValue ) : qgsEnumValueToKey( defaultValue ), description, @@ -62,11 +64,11 @@ class QgsSettingsEntryEnumFlag : public QgsSettingsEntryByValue /** * Constructor for QgsSettingsEntryEnumFlagBase. * - * The \a parent argument specifies the parent in the tree of settings. - * The \a key argument specifies the final part of the settings key. - * The \a section argument specifies the section. - * The \a defaultValue argument specifies the default value for the settings entry. - * The \a description argument specifies a description for the settings entry. + * \param key specifies the final part of the setting key. + * \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. * * \note The enum needs to be declared with Q_ENUM, and flags with Q_FLAG (not Q_FLAGS). * \note for Python bindings, a custom implementation is achieved in Python directly diff --git a/src/core/settings/qgssettingsentryimpl.h b/src/core/settings/qgssettingsentryimpl.h index 3392a692f11..33180d5bc18 100644 --- a/src/core/settings/qgssettingsentryimpl.h +++ b/src/core/settings/qgssettingsentryimpl.h @@ -34,19 +34,19 @@ class CORE_EXPORT QgsSettingsEntryVariant : public QgsSettingsEntryByReference( key, parent, defaultValue, description, options ) + : QgsSettingsEntryByReference( name, parent, defaultValue, description, options ) , mMinLength( minLength ) , mMaxLength( maxLength ) {} @@ -235,18 +235,18 @@ class CORE_EXPORT QgsSettingsEntryStringList : public QgsSettingsEntryByReferenc /** * Constructor for QgsSettingsEntryStringList. * - * \param key specifies the final part of the settings key. + * \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. */ - QgsSettingsEntryStringList( const QString &key, + QgsSettingsEntryStringList( const QString &name, QgsSettingsTreeNode *parent, const QStringList &defaultValue = QStringList(), const QString &description = QString(), Qgis::SettingsOptions options = Qgis::SettingsOptions() ) SIP_THROW( QgsSettingsException ) SIP_TRANSFER - : QgsSettingsEntryByReference( key, parent, defaultValue, description, options ) + : QgsSettingsEntryByReference( name, parent, defaultValue, description, options ) {} /** @@ -311,18 +311,18 @@ class CORE_EXPORT QgsSettingsEntryBool : public QgsSettingsEntryByValue /** * Constructor for QgsSettingsEntryBool. * - * \param key specifies the final part of the settings key. + * \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. */ - QgsSettingsEntryBool( const QString &key, + QgsSettingsEntryBool( const QString &name, QgsSettingsTreeNode *parent, bool defaultValue = false, const QString &description = QString(), Qgis::SettingsOptions options = Qgis::SettingsOptions() ) SIP_THROW( QgsSettingsException ) SIP_TRANSFER - : QgsSettingsEntryByValue( key, parent, defaultValue, description, options ) + : QgsSettingsEntryByValue( name, parent, defaultValue, description, options ) {} /** @@ -386,7 +386,7 @@ class CORE_EXPORT QgsSettingsEntryInteger : public QgsSettingsEntryByValue /** * Constructor for QgsSettingsEntryInteger. * - * \param key specifies the final part of the settings key. + * \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. @@ -394,14 +394,14 @@ class CORE_EXPORT QgsSettingsEntryInteger : public QgsSettingsEntryByValue * \param minValue specifies the minimal value. * \param maxValue specifies the maximal value. */ - QgsSettingsEntryInteger( const QString &key, + QgsSettingsEntryInteger( const QString &name, QgsSettingsTreeNode *parent, int defaultValue = 0, const QString &description = QString(), Qgis::SettingsOptions options = Qgis::SettingsOptions(), int minValue = std::numeric_limits::min(), int maxValue = std::numeric_limits::max() ) SIP_THROW( QgsSettingsException ) SIP_TRANSFER - : QgsSettingsEntryByValue( key, parent, defaultValue, description, options ) + : QgsSettingsEntryByValue( name, parent, defaultValue, description, options ) , mMinValue( minValue ) , mMaxValue( maxValue ) { } @@ -491,7 +491,7 @@ class CORE_EXPORT QgsSettingsEntryInteger64 : public QgsSettingsEntryByValue::min(), qlonglong maxValue = std::numeric_limits::max() ) SIP_THROW( QgsSettingsException ) - : QgsSettingsEntryByValue( key, parent, defaultValue, description, options ) + : QgsSettingsEntryByValue( name, parent, defaultValue, description, options ) , mMinValue( minValue ) , mMaxValue( maxValue ) { } @@ -568,7 +568,7 @@ class CORE_EXPORT QgsSettingsEntryDouble : public QgsSettingsEntryByValue::lowest(), double maxValue = std::numeric_limits::max(), int displayDecimals = 1 ) SIP_THROW( QgsSettingsException ) SIP_TRANSFER - : QgsSettingsEntryByValue( key, parent, defaultValue, description, options ) + : QgsSettingsEntryByValue( name, parent, defaultValue, description, options ) , mMinValue( minValue ) , mMaxValue( maxValue ) , mDisplayHintDecimals( displayDecimals ) @@ -698,20 +698,20 @@ class CORE_EXPORT QgsSettingsEntryColor : public QgsSettingsEntryByReference