QGIS API Documentation  3.2.0-Bonn (bc43194)
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.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();
158  QStringList allKeys() const;
160  QStringList childKeys() const;
162  QStringList childGroups() const;
164  QStringList globalChildGroups() const;
166  static QString globalSettingsPath() { return sGlobalSettingsPath; }
168  static bool setGlobalSettingsPath( const QString &path );
170  int beginReadArray( const QString &prefix );
171 
177  void beginWriteArray( const QString &prefix, int size = -1 );
179  void endArray();
180 
185  void setArrayIndex( int i );
186 
191  void setValue( const QString &key, const QVariant &value, QgsSettings::Section section = QgsSettings::NoSection );
192 
199 #ifndef SIP_RUN
200  QVariant value( const QString &key, const QVariant &defaultValue = QVariant(),
201  Section section = NoSection ) const;
202 #else
203  SIP_PYOBJECT value( const QString &key, const QVariant &defaultValue = QVariant(),
204  SIP_PYOBJECT type = 0,
205  QgsSettings::Section section = QgsSettings::NoSection ) const / ReleaseGIL /;
206  % MethodCode
207  typedef PyObject *( *pyqt5_from_qvariant_by_type )( QVariant &value, PyObject *type );
208  QVariant value;
209 
210  // QSettings has an internal mutex so release the GIL to avoid the possibility of deadlocks.
211  Py_BEGIN_ALLOW_THREADS
212  value = sipCpp->value( *a0, *a1, a3 );
213  Py_END_ALLOW_THREADS
214 
215  pyqt5_from_qvariant_by_type f = ( pyqt5_from_qvariant_by_type ) sipImportSymbol( "pyqt5_from_qvariant_by_type" );
216  sipRes = f( value, a2 );
217 
218  sipIsErr = !sipRes;
219  % End
220 #endif
221 
222 #ifndef SIP_RUN
223 
234  template <class T>
235  T enumValue( const QString &key, const T &defaultValue,
236  const Section section = NoSection )
237  {
238  QMetaEnum metaEnum = QMetaEnum::fromType<T>();
239  Q_ASSERT( metaEnum.isValid() );
240  if ( !metaEnum.isValid() )
241  {
242  QgsDebugMsg( "Invalid metaenum. Enum probably misses Q_ENUM or Q_FLAG declaration." );
243  }
244 
245  T v;
246  bool ok = false;
247 
248  if ( metaEnum.isValid() )
249  {
250  // read as string
251  QByteArray ba = value( key, metaEnum.valueToKey( defaultValue ) ).toString().toUtf8();
252  const char *vs = ba.data();
253  v = static_cast<T>( metaEnum.keyToValue( vs, &ok ) );
254  if ( ok )
255  return v;
256  }
257 
258  // if failed, try to read as int (old behavior)
259  // this code shall be removed later (probably after QGIS 3.4 LTR for 3.6)
260  // then the method could be marked as const
261  v = static_cast<T>( value( key, static_cast<int>( defaultValue ), section ).toInt( &ok ) );
262  if ( metaEnum.isValid() )
263  {
264  if ( !ok || !metaEnum.valueToKey( static_cast<int>( v ) ) )
265  {
266  v = defaultValue;
267  }
268  else
269  {
270  // found setting as an integer
271  // convert the setting to the new form (string)
272  setEnumValue( key, v, section );
273  }
274  }
275 
276  return v;
277  }
278 
286  template <class T>
287  void setEnumValue( const QString &key, const T &value,
288  const Section section = NoSection )
289  {
290  QMetaEnum metaEnum = QMetaEnum::fromType<T>();
291  Q_ASSERT( metaEnum.isValid() );
292  if ( metaEnum.isValid() )
293  {
294  setValue( key, metaEnum.valueToKey( value ), section );
295  }
296  else
297  {
298  QgsDebugMsg( "Invalid metaenum. Enum probably misses Q_ENUM or Q_FLAG declaration." );
299  }
300  }
301 
312  template <class T>
313  T flagValue( const QString &key, const T &defaultValue,
314  const Section section = NoSection )
315  {
316  QMetaEnum metaEnum = QMetaEnum::fromType<T>();
317  Q_ASSERT( metaEnum.isValid() );
318  if ( !metaEnum.isValid() )
319  {
320  QgsDebugMsg( "Invalid metaenum. Enum probably misses Q_ENUM or Q_FLAG declaration." );
321  }
322 
323  T v;
324  bool ok = false;
325 
326  if ( metaEnum.isValid() )
327  {
328  // read as string
329  QByteArray ba = value( key, metaEnum.valueToKeys( defaultValue ) ).toString().toUtf8();
330  const char *vs = ba.data();
331  v = static_cast<T>( metaEnum.keysToValue( vs, &ok ) );
332  }
333  if ( !ok )
334  {
335  // if failed, try to read as int (old behavior)
336  // this code shall be removed later (probably after QGIS 3.4 LTR for 3.6)
337  // then the method could be marked as const
338  v = T( value( key, static_cast<int>( defaultValue ), section ).toInt( &ok ) );
339  if ( metaEnum.isValid() )
340  {
341  if ( !ok || !metaEnum.valueToKeys( static_cast<int>( v ) ).size() )
342  {
343  v = defaultValue;
344  }
345  else
346  {
347  // found setting as an integer
348  // convert the setting to the new form (string)
349  setFlagValue( key, v, section );
350  }
351  }
352  }
353 
354  return v;
355  }
356 
364  template <class T>
365  void setFlagValue( const QString &key, const T &value,
366  const Section section = NoSection )
367  {
368  QMetaEnum metaEnum = QMetaEnum::fromType<T>();
369  Q_ASSERT( metaEnum.isValid() );
370  if ( metaEnum.isValid() )
371  {
372  setValue( key, metaEnum.valueToKeys( value ), section );
373  }
374  else
375  {
376  QgsDebugMsg( "Invalid metaenum. Enum probably misses Q_ENUM or Q_FLAG declaration." );
377  }
378  }
379 #endif
380 
385  bool contains( const QString &key, QgsSettings::Section section = QgsSettings::NoSection ) const;
387  QString fileName() const;
388 
395  void sync();
397  void remove( const QString &key, QgsSettings::Section section = QgsSettings::NoSection );
399  QString prefixedKey( const QString &key, QgsSettings::Section section ) const;
401  void clear();
402 
403  private:
404 
405  static QString sGlobalSettingsPath;
406  void init();
407  QString sanitizeKey( const QString &key ) const;
408  QSettings *mUserSettings = nullptr;
409  QSettings *mGlobalSettings = nullptr;
410  bool mUsingGlobalArray = false;
411  Q_DISABLE_COPY( QgsSettings )
412 
413 };
414 
415 #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:365
static QString globalSettingsPath()
Returns the path to the Global Settings QSettings storage file.
Definition: qgssettings.h:166
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:313
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:287
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:235