QGIS API Documentation  3.26.3-Buenos Aires (65e4edfdad)
qgssettingsentry.h
Go to the documentation of this file.
1 /***************************************************************************
2  qgssettingsentry.h
3  --------------------------------------
4  Date : February 2021
5  Copyright : (C) 2021 by Damiano Lombardi
6  Email : damiano at opengis dot ch
7  ***************************************************************************
8  * *
9  * This program is free software; you can redistribute it and/or modify *
10  * it under the terms of the GNU General Public License as published by *
11  * the Free Software Foundation; either version 2 of the License, or *
12  * (at your option) any later version. *
13  * *
14  ***************************************************************************/
15 
16 #ifndef QGSSETTINGSENTRY_H
17 #define QGSSETTINGSENTRY_H
18 
19 #include <QString>
20 #include <QColor>
21 #include <limits>
22 
23 #include "qgis.h"
24 #include "qgis_core.h"
25 #include "qgis_sip.h"
26 #include "qgssettings.h"
27 
29 
30 
38 class CORE_EXPORT QgsSettingsEntryGroup
39 {
40  public:
42  QgsSettingsEntryGroup( const QList<const QgsSettingsEntryBase *> settings )
43  : QgsSettingsEntryGroup( settings, true )
44  {}
45 #ifdef SIP_RUN
46  % MethodCode
47  sipCpp = new QgsSettingsEntryGroup( *a0, false );
48  sipIsErr = sipCpp->isValid() ? 0 : 1;
49  if ( sipIsErr )
50  PyErr_SetString( PyExc_ValueError, QStringLiteral( "Settings do not share the same base definition key for this group. This will lead to unpredictable results." ).toUtf8().constData() );
51  % End
52 #endif
53 
55  QgsSettingsEntryGroup( const QList<const QgsSettingsEntryBase *> settings, bool fatalErrorIfInvalid ) SIP_SKIP;
56 
58  bool isValid() const {return mIsValid;}
59 
61  QString baseKey( const QStringList &dynamicKeyPartList = QStringList() ) const;
62 
64  const QList<const QgsSettingsEntryBase *> settings() const {return mSettings;}
65 
70  void removeAllSettingsAtBaseKey( const QStringList &dynamicKeyPartList = QStringList() ) const;
71 
76  void removeAllChildrenSettings( const QString &dynamicKeyPart = QString() ) const;
77 
82  void removeAllChildrenSettings( const QStringList &dynamicKeyPartList ) const;
83 
84  private:
85  bool hasDynamicKey() const;
86 
87  QList<const QgsSettingsEntryBase *> mSettings;
88  QString mDefinitionBaseKey;
89  bool mIsValid = true;
90 };
91 
102 class CORE_EXPORT QgsSettingsEntryBase
103 {
104 
105 #ifdef SIP_RUN
107  if ( dynamic_cast< QgsSettingsEntryVariant * >( sipCpp ) )
108  sipType = sipType_QgsSettingsEntryVariant;
109  else if ( dynamic_cast< QgsSettingsEntryString * >( sipCpp ) )
110  sipType = sipType_QgsSettingsEntryString;
111  else if ( dynamic_cast< QgsSettingsEntryStringList * >( sipCpp ) )
112  sipType = sipType_QgsSettingsEntryStringList;
113  else if ( dynamic_cast< QgsSettingsEntryBool * >( sipCpp ) )
114  sipType = sipType_QgsSettingsEntryBool;
115  else if ( dynamic_cast< QgsSettingsEntryInteger * >( sipCpp ) )
116  sipType = sipType_QgsSettingsEntryInteger;
117  else if ( dynamic_cast< QgsSettingsEntryDouble * >( sipCpp ) )
118  sipType = sipType_QgsSettingsEntryDouble;
119  else if ( dynamic_cast< QgsSettingsEntryColor * >( sipCpp ) )
120  sipType = sipType_QgsSettingsEntryColor;
121  else
122  sipType = NULL;
123  SIP_END
124 #endif
125 
126  public:
127 
132  static QStringList dynamicKeyPartToList( const QString &dynamicKeyPart );
133 
134 
144  QgsSettingsEntryBase( const QString &key,
145  const QString &section,
146  const QVariant &defaultValue = QVariant(),
147  const QString &description = QString(),
148  Qgis::SettingsOptions options = Qgis::SettingsOptions() )
149  : mKey( QStringLiteral( "%1/%2" ).arg( section, key ) )
150  , mDefaultValue( defaultValue )
151  , mDescription( description )
152  , mPluginName()
153  , mOptions( options )
154  {}
155 
160 
166  QString key( const QString &dynamicKeyPart = QString() ) const;
167 
173  QString key( const QStringList &dynamicKeyPartList ) const;
174 
184  bool keyIsValid( const QString &key ) const;
185 
191  QString definitionKey() const;
192 
196  bool hasDynamicKey() const;
197 
202  Qgis::SettingsOptions options() const {return mOptions;}
203 
209  bool exists( const QString &dynamicKeyPart = QString() ) const;
210 
216  bool exists( const QStringList &dynamicKeyPartList ) const;
217 
223  void remove( const QString &dynamicKeyPart = QString() ) const;
224 
230  void remove( const QStringList &dynamicKeyPartList ) const;
231 
236  Q_DECL_DEPRECATED QgsSettings::Section section() const {return QgsSettings::NoSection;}
237 
245  Q_DECL_DEPRECATED virtual bool setVariantValue( const QVariant &value, const QString &dynamicKeyPart = QString() ) const SIP_DEPRECATED;
246 
254  Q_DECL_DEPRECATED virtual bool setVariantValue( const QVariant &value, const QStringList &dynamicKeyPartList ) const SIP_DEPRECATED;
255 
257  QVariant valueAsVariant( const QString &dynamicKeyPart = QString() ) const;
258 
260  QVariant valueAsVariant( const QStringList &dynamicKeyPartList ) const;
261 
266  QVariant valueAsVariantWithDefaultOverride( const QVariant &defaultValueOverride, const QString &dynamicKeyPart = QString() ) const;
267 
275  QVariant valueAsVariantWithDefaultOverride( const QVariant &defaultValueOverride, const QStringList &dynamicKeyPartList ) const;
276 
281  Q_DECL_DEPRECATED QVariant valueAsVariant( const QString &dynamicKeyPart, bool useDefaultValueOverride, const QVariant &defaultValueOverride ) const SIP_DEPRECATED;
282 
287  Q_DECL_DEPRECATED QVariant valueAsVariant( const QStringList &dynamicKeyPartList, bool useDefaultValueOverride, const QVariant &defaultValueOverride ) const SIP_DEPRECATED;
288 
289 
293  QVariant defaultValueAsVariant() const;
294 
298  virtual Qgis::SettingsType settingsType() const = 0;
299 
303  QString description() const;
304 
310  QVariant formerValueAsVariant( const QString &dynamicKeyPart ) const;
311 
317  QVariant formerValueAsVariant( const QStringList &dynamicKeyPartList ) const;
318 
319  protected:
320 
326  bool setVariantValuePrivate( const QVariant &value, const QStringList &dynamicKeyPartList = QStringList() ) const;
327 
328  private:
329  QString formerValuekey( const QStringList &dynamicKeyPartList ) const;
330 
331  QString mKey;
332  QVariant mDefaultValue;
333  QString mDescription;
334  QString mPluginName;
335  Qgis::SettingsOptions mOptions;
336 };
337 
338 
349 template<class T>
351 {
352  public:
353 
362  QgsSettingsEntryByReference( const QString &key,
363  const QString &section,
364  const T &defaultValue,
365  const QString &description = QString(),
366  Qgis::SettingsOptions options = Qgis::SettingsOptions() )
367  : QgsSettingsEntryBase( key, section, defaultValue, description, options )
368  {}
369 
370 
371  virtual Qgis::SettingsType settingsType() const override = 0;
372 
379  T value( const QString &dynamicKeyPart = QString() ) const { return this->convertFromVariant( valueAsVariant( dynamicKeyPart ) );}
380 
387  T value( const QStringList &dynamicKeyPartList ) const { return this->convertFromVariant( valueAsVariant( dynamicKeyPartList ) );}
388 
390  T valueWithDefaultOverride( const T &defaultValueOverride, const QString &dynamicKeyPart = QString() ) const { return this->convertFromVariant( valueAsVariantWithDefaultOverride( defaultValueOverride, dynamicKeyPart ) );}
392  T valueWithDefaultOverride( const T &defaultValueOverride, const QStringList &dynamicKeyPartList ) const { return this->convertFromVariant( valueAsVariantWithDefaultOverride( defaultValueOverride, dynamicKeyPartList ) );}
393 
398  Q_DECL_DEPRECATED T value( const QString &dynamicKeyPart, bool useDefaultValueOverride, const T &defaultValueOverride ) const SIP_DEPRECATED
399  {
400  if ( useDefaultValueOverride )
401  return this->convertFromVariant( valueAsVariantWithDefaultOverride( defaultValueOverride, dynamicKeyPart ) );
402  else
403  return this->convertFromVariant( valueAsVariant( dynamicKeyPart ) );
404  }
405 
410  Q_DECL_DEPRECATED T value( const QStringList &dynamicKeyPartList, bool useDefaultValueOverride, const T &defaultValueOverride ) const SIP_DEPRECATED
411  {
412  if ( useDefaultValueOverride )
413  return this->convertFromVariant( valueAsVariantWithDefaultOverride( defaultValueOverride, dynamicKeyPartList ) );
414  else
415  return this->convertFromVariant( valueAsVariant( dynamicKeyPartList ) );
416  }
417 
424  bool setValue( const T &value, const QString &dynamicKeyPart = QString() ) const
425  {
426  return setValuePrivate( value, dynamicKeyPartToList( dynamicKeyPart ) );
427  }
428 
435  bool setValue( const T &value, const QStringList &dynamicKeyPartList ) const
436  {
437  return setValuePrivate( value, dynamicKeyPartList );
438  }
439 
441  T defaultValue() const {return convertFromVariant( defaultValueAsVariant() );}
442 
447  T formerValue( const QString &dynamicKeyPart = QString() ) const {return convertFromVariant( formerValueAsVariant( dynamicKeyPart ) );}
448 
453  T formerValue( const QStringList &dynamicKeyPartList ) const {return convertFromVariant( formerValueAsVariant( dynamicKeyPartList ) );}
454 
455  protected:
457  bool setValuePrivate( const T &value, const QStringList &dynamicKeyPartList ) const
458  {
459  if ( checkValue( value ) )
460  return QgsSettingsEntryBase::setVariantValuePrivate( convertToVariant( value ), dynamicKeyPartList );
461  else
462  return false;
463  }
464 
466  virtual T convertFromVariant( const QVariant &value ) const = 0;
467 
469  virtual QVariant convertToVariant( const T &value ) const
470  {
471  return QVariant::fromValue( value );
472  }
473 
475  virtual bool checkValue( const T &value ) const
476  {
477  Q_UNUSED( value )
478  return true;
479  }
480 };
481 
482 
493 template<class T>
495 {
496  public:
497 
498 
508  QgsSettingsEntryByValue( const QString &key, const QString &section, QVariant defaultValue, const QString &description = QString(), Qgis::SettingsOptions options = Qgis::SettingsOptions() )
509  : QgsSettingsEntryBase( key, section, defaultValue, description, options )
510  {}
511 
512  virtual Qgis::SettingsType settingsType() const override = 0;
513 
520  T value( const QString &dynamicKeyPart = QString() ) const { return this->convertFromVariant( valueAsVariant( dynamicKeyPart ) );}
521 
528  T value( const QStringList &dynamicKeyPartList ) const { return this->convertFromVariant( valueAsVariant( dynamicKeyPartList ) );}
529 
531  T valueWithDefaultOverride( T defaultValueOverride, const QString &dynamicKeyPart = QString() ) const { return this->convertFromVariant( valueAsVariantWithDefaultOverride( defaultValueOverride, dynamicKeyPart ) );}
533  T valueWithDefaultOverride( T defaultValueOverride, const QStringList &dynamicKeyPartList ) const { return this->convertFromVariant( valueAsVariantWithDefaultOverride( defaultValueOverride, dynamicKeyPartList ) );}
534 
539  Q_DECL_DEPRECATED T value( const QString &dynamicKeyPart, bool useDefaultValueOverride, T defaultValueOverride ) const SIP_DEPRECATED
540  {
541  if ( useDefaultValueOverride )
542  return this->convertFromVariant( valueAsVariantWithDefaultOverride( defaultValueOverride, dynamicKeyPart ) );
543  else
544  return this->convertFromVariant( valueAsVariant( dynamicKeyPart ) );
545  }
546 
551  Q_DECL_DEPRECATED T value( const QStringList &dynamicKeyPartList, bool useDefaultValueOverride, T defaultValueOverride ) const SIP_DEPRECATED
552  {
553  if ( useDefaultValueOverride )
554  return this->convertFromVariant( valueAsVariantWithDefaultOverride( defaultValueOverride, dynamicKeyPartList ) );
555  else
556  return this->convertFromVariant( valueAsVariant( dynamicKeyPartList ) );
557  }
558 
565  bool setValue( T value, const QString &dynamicKeyPart = QString() ) const
566  {
567  return setValuePrivate( value, dynamicKeyPartToList( dynamicKeyPart ) );
568  }
569 
576  bool setValue( T value, const QStringList &dynamicKeyPartList ) const
577  {
578  return setValuePrivate( value, dynamicKeyPartList );
579  }
580 
582  T defaultValue() const {return convertFromVariant( defaultValueAsVariant() );}
583 
588  T formerValue( const QString &dynamicKeyPart = QString() ) const {return convertFromVariant( formerValueAsVariant( dynamicKeyPart ) );}
589 
594  T formerValue( const QStringList &dynamicKeyPartList ) const {return convertFromVariant( formerValueAsVariant( dynamicKeyPartList ) );}
595 
596  protected:
598  virtual bool setValuePrivate( T value, const QStringList &dynamicKeyPartList ) const
599  {
600  if ( checkValue( value ) )
601  return QgsSettingsEntryBase::setVariantValuePrivate( convertToVariant( value ), dynamicKeyPartList );
602  else
603  return false;
604  }
605 
607  virtual T convertFromVariant( const QVariant &value ) const = 0;
608 
610  virtual QVariant convertToVariant( T value ) const
611  {
612  return QVariant::fromValue( value );
613  }
614 
616  virtual bool checkValue( T value ) const
617  {
618  Q_UNUSED( value )
619  return true;
620  }
621 };
622 
623 
624 #endif // QGSSETTINGSENTRY_H
QgsSettingsEntryByReference::valueWithDefaultOverride
T valueWithDefaultOverride(const T &defaultValueOverride, const QStringList &dynamicKeyPartList) const
Returns the settings value with a defaultValueOverride for the dynamicKeyPartList.
Definition: qgssettingsentry.h:392
QgsSettingsEntryByValue::formerValue
T formerValue(const QString &dynamicKeyPart=QString()) const
Returns the former value Returns the current value (or default) if there is no former value.
Definition: qgssettingsentry.h:588
QgsSettingsEntryByReference::setValue
bool setValue(const T &value, const QStringList &dynamicKeyPartList) const
Set settings value.
Definition: qgssettingsentry.h:435
QgsSettingsEntryByValue::formerValue
T formerValue(const QStringList &dynamicKeyPartList) const
Returns the former value Returns the current value (or default) if there is no former value.
Definition: qgssettingsentry.h:594
QgsSettingsEntryByReference::valueWithDefaultOverride
T valueWithDefaultOverride(const T &defaultValueOverride, const QString &dynamicKeyPart=QString()) const
Returns the settings value with a defaultValueOverride and with an optional dynamicKeyPart.
Definition: qgssettingsentry.h:390
QgsSettingsEntryGroup::isValid
bool isValid() const
Returns if the group is valid (if settings share the same base key)
Definition: qgssettingsentry.h:58
QgsSettingsEntryByReference::QgsSettingsEntryByReference
QgsSettingsEntryByReference(const QString &key, const QString &section, const T &defaultValue, const QString &description=QString(), Qgis::SettingsOptions options=Qgis::SettingsOptions())
Constructor for QgsSettingsEntryByReference.
Definition: qgssettingsentry.h:362
QgsSettingsEntryString
A string settings entry.
Definition: qgssettingsentryimpl.h:87
qgis.h
QgsSettingsEntryInteger
An integer settings entry.
Definition: qgssettingsentryimpl.h:299
QgsSettingsEntryBase::options
Qgis::SettingsOptions options() const
Returns the settings options.
Definition: qgssettingsentry.h:202
QgsSettingsEntryByValue::convertToVariant
virtual QVariant convertToVariant(T value) const
Converts the value to a variant.
Definition: qgssettingsentry.h:610
Qgis::SettingsType
SettingsType
Types of settings entries.
Definition: qgis.h:230
QgsSettingsEntryBase::setVariantValuePrivate
bool setVariantValuePrivate(const QVariant &value, const QStringList &dynamicKeyPartList=QStringList()) const
Sets the settings value with a variant value.
Definition: qgssettingsentry.cpp:203
QgsSettingsEntryGroup
Creates a group of setting which have a common definition of base key.
Definition: qgssettingsentry.h:38
QgsSettingsEntryByReference::checkValue
virtual bool checkValue(const T &value) const
Check if the value is valid.
Definition: qgssettingsentry.h:475
QgsSettingsEntryBase::~QgsSettingsEntryBase
virtual ~QgsSettingsEntryBase()
Destructor for QgsSettingsEntryBase.
Definition: qgssettingsentry.h:159
SIP_DEPRECATED
#define SIP_DEPRECATED
Definition: qgis_sip.h:106
SIP_CONVERT_TO_SUBCLASS_CODE
#define SIP_CONVERT_TO_SUBCLASS_CODE(code)
Definition: qgis_sip.h:186
SIP_SKIP
#define SIP_SKIP
Definition: qgis_sip.h:126
QgsSettingsEntryByValue::valueWithDefaultOverride
T valueWithDefaultOverride(T defaultValueOverride, const QStringList &dynamicKeyPartList) const
Returns the settings value with a defaultValueOverride for the dynamicKeyPartList.
Definition: qgssettingsentry.h:533
QgsSettingsEntryByValue::setValue
bool setValue(T value, const QString &dynamicKeyPart=QString()) const
Set settings value.
Definition: qgssettingsentry.h:565
QgsSettingsEntryByReference::value
Q_DECL_DEPRECATED T value(const QString &dynamicKeyPart, bool useDefaultValueOverride, const T &defaultValueOverride) const
Returns the settings value for the dynamicKeyPart and with a defaultValueOverride.
Definition: qgssettingsentry.h:398
QgsSettingsEntryByReference::setValuePrivate
bool setValuePrivate(const T &value, const QStringList &dynamicKeyPartList) const
Sets the settings value with an optional list of dynamic parts.
Definition: qgssettingsentry.h:457
QgsSettingsEntryBase::QgsSettingsEntryBase
QgsSettingsEntryBase(const QString &key, const QString &section, const QVariant &defaultValue=QVariant(), const QString &description=QString(), Qgis::SettingsOptions options=Qgis::SettingsOptions())
Constructor for QgsSettingsEntryBase.
Definition: qgssettingsentry.h:144
QgsSettingsEntryByValue::valueWithDefaultOverride
T valueWithDefaultOverride(T defaultValueOverride, const QString &dynamicKeyPart=QString()) const
Returns the settings value with a defaultValueOverride and with an optional dynamicKeyPart.
Definition: qgssettingsentry.h:531
qgis_sip.h
QgsSettingsEntryByReference
Base abstract class for settings entry which are passed by reference.
Definition: qgssettingsentry.h:350
QgsSettingsEntryVariant
A variant settings entry.
Definition: qgssettingsentryimpl.h:29
QgsSettingsEntryByReference::defaultValue
T defaultValue() const
Returns settings default value.
Definition: qgssettingsentry.h:441
QgsSettings::Section
Section
Sections for namespaced settings.
Definition: qgssettings.h:67
QgsSettingsEntryGroup::settings
const QList< const QgsSettingsEntryBase * > settings() const
Returns all the settings.
Definition: qgssettingsentry.h:64
QgsSettingsEntryDouble
A double settings entry.
Definition: qgssettingsentryimpl.h:394
QgsSettingsEntryByValue::value
Q_DECL_DEPRECATED T value(const QString &dynamicKeyPart, bool useDefaultValueOverride, T defaultValueOverride) const
Returns the settings value for the dynamicKeyPart and with a defaultValueOverride.
Definition: qgssettingsentry.h:539
QgsSettingsEntryByReference::convertToVariant
virtual QVariant convertToVariant(const T &value) const
Converts the value to a variant.
Definition: qgssettingsentry.h:469
QgsSettingsEntryColor
A color settings entry.
Definition: qgssettingsentryimpl.h:511
QgsSettingsEntryByValue
Base abstract class for settings entry which are passed by value.
Definition: qgssettingsentry.h:494
QgsSettingsEntryByReference::value
T value(const QString &dynamicKeyPart=QString()) const
Returns settings value.
Definition: qgssettingsentry.h:379
QgsSettingsEntryByValue::value
T value(const QStringList &dynamicKeyPartList) const
Returns settings value.
Definition: qgssettingsentry.h:528
QgsSettingsEntryByValue::setValue
bool setValue(T value, const QStringList &dynamicKeyPartList) const
Set settings value.
Definition: qgssettingsentry.h:576
QgsSettingsEntryGroup::QgsSettingsEntryGroup
QgsSettingsEntryGroup(const QList< const QgsSettingsEntryBase * > settings)
Constructor.
Definition: qgssettingsentry.h:42
qgssettings.h
QgsSettingsEntryBase
Represent settings entry and provides methods for reading and writing settings values....
Definition: qgssettingsentry.h:102
QgsSettingsEntryByReference::setValue
bool setValue(const T &value, const QString &dynamicKeyPart=QString()) const
Set settings value.
Definition: qgssettingsentry.h:424
QgsSettingsEntryByValue::QgsSettingsEntryByValue
QgsSettingsEntryByValue(const QString &key, const QString &section, QVariant defaultValue, const QString &description=QString(), Qgis::SettingsOptions options=Qgis::SettingsOptions())
Constructor for QgsSettingsEntryByValue.
Definition: qgssettingsentry.h:508
QgsSettingsEntryByValue::value
Q_DECL_DEPRECATED T value(const QStringList &dynamicKeyPartList, bool useDefaultValueOverride, T defaultValueOverride) const
Returns the settings value for the dynamicKeyPartList and with a defaultValueOverride.
Definition: qgssettingsentry.h:551
Qgis
The Qgis class provides global constants for use throughout the application.
Definition: qgis.h:71
QgsSettings::NoSection
@ NoSection
Definition: qgssettings.h:69
QgsSettingsEntryByReference::value
T value(const QStringList &dynamicKeyPartList) const
Returns settings value.
Definition: qgssettingsentry.h:387
QgsSettingsEntryByReference::value
Q_DECL_DEPRECATED T value(const QStringList &dynamicKeyPartList, bool useDefaultValueOverride, const T &defaultValueOverride) const
Returns the settings value for the dynamicKeyPartList and with a defaultValueOverride.
Definition: qgssettingsentry.h:410
QgsSettingsEntryStringList
A string list settings entry.
Definition: qgssettingsentryimpl.h:182
QgsSettingsEntryByValue::checkValue
virtual bool checkValue(T value) const
Check if the value is valid.
Definition: qgssettingsentry.h:616
SIP_END
#define SIP_END
Definition: qgis_sip.h:203
QgsSettingsEntryByValue::setValuePrivate
virtual bool setValuePrivate(T value, const QStringList &dynamicKeyPartList) const
Sets the settings value with an optional list of dynamic parts.
Definition: qgssettingsentry.h:598
QgsSettingsEntryByValue::defaultValue
T defaultValue() const
Returns settings default value.
Definition: qgssettingsentry.h:582
QgsSettingsEntryByReference::formerValue
T formerValue(const QString &dynamicKeyPart=QString()) const
Returns the former value.
Definition: qgssettingsentry.h:447
QgsSettingsEntryBase::section
Q_DECL_DEPRECATED QgsSettings::Section section() const
Returns settings section.
Definition: qgssettingsentry.h:236
QgsSettingsEntryBool
A boolean settings entry.
Definition: qgssettingsentryimpl.h:241
QgsSettingsEntryByValue::value
T value(const QString &dynamicKeyPart=QString()) const
Returns settings value.
Definition: qgssettingsentry.h:520
QgsSettingsEntryByReference::formerValue
T formerValue(const QStringList &dynamicKeyPartList) const
Returns the former value Returns the current value (or default) if there is no former value.
Definition: qgssettingsentry.h:453