QGIS API Documentation  3.13.0-Master (9729a43df7)
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 
61 class CORE_EXPORT QgsSettings : public QObject
62 {
63  Q_OBJECT
64  public:
65 
67  enum Section
68  {
71  Gui,
75  App,
78  Misc
79  };
80 
85  explicit QgsSettings( const QString &organization,
86  const QString &application = QString(), QObject *parent = nullptr );
87 
102  QgsSettings( QSettings::Scope scope, const QString &organization,
103  const QString &application = QString(), QObject *parent = nullptr );
104 
119  QgsSettings( QSettings::Format format, QSettings::Scope scope, const QString &organization,
120  const QString &application = QString(), QObject *parent = nullptr );
121 
142  QgsSettings( const QString &fileName, QSettings::Format format, QObject *parent = nullptr );
143 
153  explicit QgsSettings( QObject *parent = nullptr );
154  ~QgsSettings() override;
155 
162  void beginGroup( const QString &prefix, QgsSettings::Section section = QgsSettings::NoSection );
164  void endGroup();
165 
172  QString group() const;
173 
175  QStringList allKeys() const;
177  QStringList childKeys() const;
179  QStringList childGroups() const;
181  QStringList globalChildGroups() const;
183  static QString globalSettingsPath();
185  static bool setGlobalSettingsPath( const QString &path );
187  int beginReadArray( const QString &prefix );
188 
194  void beginWriteArray( const QString &prefix, int size = -1 );
196  void endArray();
197 
202  void setArrayIndex( int i );
203 
208  void setValue( const QString &key, const QVariant &value, QgsSettings::Section section = QgsSettings::NoSection );
209 
216 #ifndef SIP_RUN
217  QVariant value( const QString &key, const QVariant &defaultValue = QVariant(),
218  Section section = NoSection ) const;
219 #else
220  SIP_PYOBJECT value( const QString &key, const QVariant &defaultValue = QVariant(),
221  SIP_PYOBJECT type = 0,
222  QgsSettings::Section section = QgsSettings::NoSection ) const / ReleaseGIL /;
223  % MethodCode
224  typedef PyObject *( *pyqt5_from_qvariant_by_type )( QVariant &value, PyObject *type );
225  QVariant value;
226 
227  // QSettings has an internal mutex so release the GIL to avoid the possibility of deadlocks.
228  Py_BEGIN_ALLOW_THREADS
229  value = sipCpp->value( *a0, *a1, a3 );
230  Py_END_ALLOW_THREADS
231 
232  pyqt5_from_qvariant_by_type f = ( pyqt5_from_qvariant_by_type ) sipImportSymbol( "pyqt5_from_qvariant_by_type" );
233  sipRes = f( value, a2 );
234 
235  sipIsErr = !sipRes;
236  % End
237 #endif
238 
239 #ifndef SIP_RUN
240 
251  template <class T>
252  T enumValue( const QString &key, const T &defaultValue,
253  const Section section = NoSection )
254  {
255  QMetaEnum metaEnum = QMetaEnum::fromType<T>();
256  Q_ASSERT( metaEnum.isValid() );
257  if ( !metaEnum.isValid() )
258  {
259  QgsDebugMsg( QStringLiteral( "Invalid metaenum. Enum probably misses Q_ENUM or Q_FLAG declaration." ) );
260  }
261 
262  T v;
263  bool ok = false;
264 
265  if ( metaEnum.isValid() )
266  {
267  // read as string
268  QByteArray ba = value( key, metaEnum.valueToKey( static_cast<int>( defaultValue ) ), section ).toString().toUtf8();
269  const char *vs = ba.data();
270  v = static_cast<T>( metaEnum.keyToValue( vs, &ok ) );
271  if ( ok )
272  return v;
273  }
274 
275  // if failed, try to read as int (old behavior)
276  // this code shall be removed later (probably after QGIS 3.4 LTR for 3.6)
277  // then the method could be marked as const
278  v = static_cast<T>( value( key, static_cast<int>( defaultValue ), section ).toInt( &ok ) );
279  if ( metaEnum.isValid() )
280  {
281  if ( !ok || !metaEnum.valueToKey( static_cast<int>( v ) ) )
282  {
283  v = defaultValue;
284  }
285  else
286  {
287  // found setting as an integer
288  // convert the setting to the new form (string)
289  setEnumValue( key, v, section );
290  }
291  }
292 
293  return v;
294  }
295 
303  template <class T>
304  void setEnumValue( const QString &key, const T &value,
305  const Section section = NoSection )
306  {
307  QMetaEnum metaEnum = QMetaEnum::fromType<T>();
308  Q_ASSERT( metaEnum.isValid() );
309  if ( metaEnum.isValid() )
310  {
311  setValue( key, metaEnum.valueToKey( static_cast<int>( value ) ), section );
312  }
313  else
314  {
315  QgsDebugMsg( QStringLiteral( "Invalid metaenum. Enum probably misses Q_ENUM or Q_FLAG declaration." ) );
316  }
317  }
318 
329  template <class T>
330  T flagValue( const QString &key, const T &defaultValue,
331  const Section section = NoSection )
332  {
333  QMetaEnum metaEnum = QMetaEnum::fromType<T>();
334  Q_ASSERT( metaEnum.isValid() );
335  if ( !metaEnum.isValid() )
336  {
337  QgsDebugMsg( QStringLiteral( "Invalid metaenum. Enum probably misses Q_ENUM or Q_FLAG declaration." ) );
338  }
339 
340  T v = defaultValue;
341  bool ok = false;
342 
343  if ( metaEnum.isValid() )
344  {
345  // read as string
346  QByteArray ba = value( key, metaEnum.valueToKeys( defaultValue ) ).toString().toUtf8();
347  const char *vs = ba.data();
348  v = static_cast<T>( metaEnum.keysToValue( vs, &ok ) );
349  }
350  if ( !ok )
351  {
352  // if failed, try to read as int (old behavior)
353  // this code shall be removed later (probably after QGIS 3.4 LTR for 3.6)
354  // then the method could be marked as const
355  v = T( value( key, static_cast<int>( defaultValue ), section ).toInt( &ok ) );
356  if ( metaEnum.isValid() )
357  {
358  if ( !ok || metaEnum.valueToKeys( static_cast<int>( v ) ).isEmpty() )
359  {
360  v = defaultValue;
361  }
362  else
363  {
364  // found setting as an integer
365  // convert the setting to the new form (string)
366  setFlagValue( key, v, section );
367  }
368  }
369  }
370 
371  return v;
372  }
373 
381  template <class T>
382  void setFlagValue( const QString &key, const T &value,
383  const Section section = NoSection )
384  {
385  QMetaEnum metaEnum = QMetaEnum::fromType<T>();
386  Q_ASSERT( metaEnum.isValid() );
387  if ( metaEnum.isValid() )
388  {
389  setValue( key, metaEnum.valueToKeys( value ), section );
390  }
391  else
392  {
393  QgsDebugMsg( QStringLiteral( "Invalid metaenum. Enum probably misses Q_ENUM or Q_FLAG declaration." ) );
394  }
395  }
396 #endif
397 
402  bool contains( const QString &key, QgsSettings::Section section = QgsSettings::NoSection ) const;
404  QString fileName() const;
405 
412  void sync();
414  void remove( const QString &key, QgsSettings::Section section = QgsSettings::NoSection );
416  QString prefixedKey( const QString &key, QgsSettings::Section section ) const;
418  void clear();
419 
420  private:
421  void init();
422  QString sanitizeKey( const QString &key ) const;
423  QSettings *mUserSettings = nullptr;
424  QSettings *mGlobalSettings = nullptr;
425  bool mUsingGlobalArray = false;
426  Q_DISABLE_COPY( QgsSettings )
427 
428 };
429 
430 #endif // QGSSETTINGS_H
This class is a composition of two QSettings instances:
Definition: qgssettings.h:61
#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:382
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:330
Section
Sections for namespaced settings.
Definition: qgssettings.h:67
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:304
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:252