QGIS API Documentation  3.9.0-Master (224899f119)
qgssettings.h
Go to the documentation of this file.
1 /***************************************************************************
2  qgssettings.h
3  --------------------------------------
4  Date : January 2017
5  Copyright : (C) 2017 by Alessandro Pasotti
6  Email : apasotti at boundlessgeo dot com
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 
17 #ifndef QGSSETTINGS_H
18 #define QGSSETTINGS_H
19 
20 #include <QSettings>
21 #include <QMetaEnum>
22 
23 #include "qgis_core.h"
24 #include "qgis_sip.h"
25 #include "qgslogger.h"
26 
58 class CORE_EXPORT QgsSettings : public QObject
59 {
60  Q_OBJECT
61  public:
62 
64  enum Section
65  {
68  Gui,
72  App,
74  Misc
75  };
76 
81  explicit QgsSettings( const QString &organization,
82  const QString &application = QString(), QObject *parent = nullptr );
83 
97  QgsSettings( QSettings::Scope scope, const QString &organization,
98  const QString &application = QString(), QObject *parent = nullptr );
99 
112  QgsSettings( QSettings::Format format, QSettings::Scope scope, const QString &organization,
113  const QString &application = QString(), QObject *parent = nullptr );
114 
134  QgsSettings( const QString &fileName, QSettings::Format format, QObject *parent = nullptr );
135 
145  explicit QgsSettings( QObject *parent = nullptr );
146  ~QgsSettings() override;
147 
154  void beginGroup( const QString &prefix, QgsSettings::Section section = QgsSettings::NoSection );
156  void endGroup();
157 
164  QString group() const;
165 
167  QStringList allKeys() const;
169  QStringList childKeys() const;
171  QStringList childGroups() const;
173  QStringList globalChildGroups() const;
175  static QString globalSettingsPath() { return sGlobalSettingsPath; }
177  static bool setGlobalSettingsPath( const QString &path );
179  int beginReadArray( const QString &prefix );
180 
186  void beginWriteArray( const QString &prefix, int size = -1 );
188  void endArray();
189 
194  void setArrayIndex( int i );
195 
200  void setValue( const QString &key, const QVariant &value, QgsSettings::Section section = QgsSettings::NoSection );
201 
208 #ifndef SIP_RUN
209  QVariant value( const QString &key, const QVariant &defaultValue = QVariant(),
210  Section section = NoSection ) const;
211 #else
212  SIP_PYOBJECT value( const QString &key, const QVariant &defaultValue = QVariant(),
213  SIP_PYOBJECT type = 0,
214  QgsSettings::Section section = QgsSettings::NoSection ) const / ReleaseGIL /;
215  % MethodCode
216  typedef PyObject *( *pyqt5_from_qvariant_by_type )( QVariant &value, PyObject *type );
217  QVariant value;
218 
219  // QSettings has an internal mutex so release the GIL to avoid the possibility of deadlocks.
220  Py_BEGIN_ALLOW_THREADS
221  value = sipCpp->value( *a0, *a1, a3 );
222  Py_END_ALLOW_THREADS
223 
224  pyqt5_from_qvariant_by_type f = ( pyqt5_from_qvariant_by_type ) sipImportSymbol( "pyqt5_from_qvariant_by_type" );
225  sipRes = f( value, a2 );
226 
227  sipIsErr = !sipRes;
228  % End
229 #endif
230 
231 #ifndef SIP_RUN
232 
243  template <class T>
244  T enumValue( const QString &key, const T &defaultValue,
245  const Section section = NoSection )
246  {
247  QMetaEnum metaEnum = QMetaEnum::fromType<T>();
248  Q_ASSERT( metaEnum.isValid() );
249  if ( !metaEnum.isValid() )
250  {
251  QgsDebugMsg( QStringLiteral( "Invalid metaenum. Enum probably misses Q_ENUM or Q_FLAG declaration." ) );
252  }
253 
254  T v;
255  bool ok = false;
256 
257  if ( metaEnum.isValid() )
258  {
259  // read as string
260  QByteArray ba = value( key, metaEnum.valueToKey( defaultValue ), section ).toString().toUtf8();
261  const char *vs = ba.data();
262  v = static_cast<T>( metaEnum.keyToValue( vs, &ok ) );
263  if ( ok )
264  return v;
265  }
266 
267  // if failed, try to read as int (old behavior)
268  // this code shall be removed later (probably after QGIS 3.4 LTR for 3.6)
269  // then the method could be marked as const
270  v = static_cast<T>( value( key, static_cast<int>( defaultValue ), section ).toInt( &ok ) );
271  if ( metaEnum.isValid() )
272  {
273  if ( !ok || !metaEnum.valueToKey( static_cast<int>( v ) ) )
274  {
275  v = defaultValue;
276  }
277  else
278  {
279  // found setting as an integer
280  // convert the setting to the new form (string)
281  setEnumValue( key, v, section );
282  }
283  }
284 
285  return v;
286  }
287 
295  template <class T>
296  void setEnumValue( const QString &key, const T &value,
297  const Section section = NoSection )
298  {
299  QMetaEnum metaEnum = QMetaEnum::fromType<T>();
300  Q_ASSERT( metaEnum.isValid() );
301  if ( metaEnum.isValid() )
302  {
303  setValue( key, metaEnum.valueToKey( value ), section );
304  }
305  else
306  {
307  QgsDebugMsg( QStringLiteral( "Invalid metaenum. Enum probably misses Q_ENUM or Q_FLAG declaration." ) );
308  }
309  }
310 
321  template <class T>
322  T flagValue( const QString &key, const T &defaultValue,
323  const Section section = NoSection )
324  {
325  QMetaEnum metaEnum = QMetaEnum::fromType<T>();
326  Q_ASSERT( metaEnum.isValid() );
327  if ( !metaEnum.isValid() )
328  {
329  QgsDebugMsg( QStringLiteral( "Invalid metaenum. Enum probably misses Q_ENUM or Q_FLAG declaration." ) );
330  }
331 
332  T v = defaultValue;
333  bool ok = false;
334 
335  if ( metaEnum.isValid() )
336  {
337  // read as string
338  QByteArray ba = value( key, metaEnum.valueToKeys( defaultValue ) ).toString().toUtf8();
339  const char *vs = ba.data();
340  v = static_cast<T>( metaEnum.keysToValue( vs, &ok ) );
341  }
342  if ( !ok )
343  {
344  // if failed, try to read as int (old behavior)
345  // this code shall be removed later (probably after QGIS 3.4 LTR for 3.6)
346  // then the method could be marked as const
347  v = T( value( key, static_cast<int>( defaultValue ), section ).toInt( &ok ) );
348  if ( metaEnum.isValid() )
349  {
350  if ( !ok || metaEnum.valueToKeys( static_cast<int>( v ) ).isEmpty() )
351  {
352  v = defaultValue;
353  }
354  else
355  {
356  // found setting as an integer
357  // convert the setting to the new form (string)
358  setFlagValue( key, v, section );
359  }
360  }
361  }
362 
363  return v;
364  }
365 
373  template <class T>
374  void setFlagValue( const QString &key, const T &value,
375  const Section section = NoSection )
376  {
377  QMetaEnum metaEnum = QMetaEnum::fromType<T>();
378  Q_ASSERT( metaEnum.isValid() );
379  if ( metaEnum.isValid() )
380  {
381  setValue( key, metaEnum.valueToKeys( value ), section );
382  }
383  else
384  {
385  QgsDebugMsg( QStringLiteral( "Invalid metaenum. Enum probably misses Q_ENUM or Q_FLAG declaration." ) );
386  }
387  }
388 #endif
389 
394  bool contains( const QString &key, QgsSettings::Section section = QgsSettings::NoSection ) const;
396  QString fileName() const;
397 
404  void sync();
406  void remove( const QString &key, QgsSettings::Section section = QgsSettings::NoSection );
408  QString prefixedKey( const QString &key, QgsSettings::Section section ) const;
410  void clear();
411 
412  private:
413 
414  static QString sGlobalSettingsPath;
415  void init();
416  QString sanitizeKey( const QString &key ) const;
417  QSettings *mUserSettings = nullptr;
418  QSettings *mGlobalSettings = nullptr;
419  bool mUsingGlobalArray = false;
420  Q_DISABLE_COPY( QgsSettings )
421 
422 };
423 
424 #endif // QGSSETTINGS_H
This class is a composition of two QSettings instances:
Definition: qgssettings.h:58
#define QgsDebugMsg(str)
Definition: qgslogger.h:38
void setFlagValue(const QString &key, const T &value, const Section section=NoSection)
Set the value of a setting based on a flaf.
Definition: qgssettings.h:374
static QString globalSettingsPath()
Returns the path to the Global Settings QSettings storage file.
Definition: qgssettings.h:175
T flagValue(const QString &key, const T &defaultValue, const Section section=NoSection)
Returns the setting value for a setting based on a flag.
Definition: qgssettings.h:322
Section
Sections for namespaced settings.
Definition: qgssettings.h:64
void setEnumValue(const QString &key, const T &value, const Section section=NoSection)
Set the value of a setting based on an enum.
Definition: qgssettings.h:296
T enumValue(const QString &key, const T &defaultValue, const Section section=NoSection)
Returns the setting value for a setting based on an enum.
Definition: qgssettings.h:244