Qt 4.8
qsettings.h
Go to the documentation of this file.
1 /****************************************************************************
2 **
3 ** Copyright (C) 2014 Digia Plc and/or its subsidiary(-ies).
4 ** Contact: http://www.qt-project.org/legal
5 **
6 ** This file is part of the QtCore module of the Qt Toolkit.
7 **
8 ** $QT_BEGIN_LICENSE:LGPL$
9 ** Commercial License Usage
10 ** Licensees holding valid commercial Qt licenses may use this file in
11 ** accordance with the commercial license agreement provided with the
12 ** Software or, alternatively, in accordance with the terms contained in
13 ** a written agreement between you and Digia. For licensing terms and
14 ** conditions see http://qt.digia.com/licensing. For further information
15 ** use the contact form at http://qt.digia.com/contact-us.
16 **
17 ** GNU Lesser General Public License Usage
18 ** Alternatively, this file may be used under the terms of the GNU Lesser
19 ** General Public License version 2.1 as published by the Free Software
20 ** Foundation and appearing in the file LICENSE.LGPL included in the
21 ** packaging of this file. Please review the following information to
22 ** ensure the GNU Lesser General Public License version 2.1 requirements
23 ** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html.
24 **
25 ** In addition, as a special exception, Digia gives you certain additional
26 ** rights. These rights are described in the Digia Qt LGPL Exception
27 ** version 1.1, included in the file LGPL_EXCEPTION.txt in this package.
28 **
29 ** GNU General Public License Usage
30 ** Alternatively, this file may be used under the terms of the GNU
31 ** General Public License version 3.0 as published by the Free Software
32 ** Foundation and appearing in the file LICENSE.GPL included in the
33 ** packaging of this file. Please review the following information to
34 ** ensure the GNU General Public License version 3.0 requirements will be
35 ** met: http://www.gnu.org/copyleft/gpl.html.
36 **
37 **
38 ** $QT_END_LICENSE$
39 **
40 ****************************************************************************/
41 
42 #ifndef QSETTINGS_H
43 #define QSETTINGS_H
44 
45 #include <QtCore/qobject.h>
46 #include <QtCore/qvariant.h>
47 #include <QtCore/qstring.h>
48 
50 
52 QT_MODULE(Core)
54 
55 #ifndef QT_NO_SETTINGS
56 
57 #ifdef QT3_SUPPORT
58 #include <QtCore/qstringlist.h>
59 #endif
60 
61 #include <ctype.h>
62 
64 
65 #ifdef Status // we seem to pick up a macro Status --> int somewhere
66 #undef Status
67 #endif
68 
69 class QIODevice;
70 class QSettingsPrivate;
71 
72 #ifndef QT_NO_QOBJECT
74 #else
76 #endif
77 {
78 #ifndef QT_NO_QOBJECT
79  Q_OBJECT
80 #else
82 #endif
84 
85 public:
86  enum Status {
87  NoError = 0,
89  FormatError
90  };
91 
92  enum Format {
95 
96  InvalidFormat = 16,
112  CustomFormat16
113  };
114 
115  enum Scope {
117  SystemScope
118 #ifdef QT3_SUPPORT
119  ,
120  User = UserScope,
121  Global = SystemScope
122 #endif
123  };
124 
125 #ifndef QT_NO_QOBJECT
126  explicit QSettings(const QString &organization,
127  const QString &application = QString(), QObject *parent = 0);
128  QSettings(Scope scope, const QString &organization,
129  const QString &application = QString(), QObject *parent = 0);
130  QSettings(Format format, Scope scope, const QString &organization,
131  const QString &application = QString(), QObject *parent = 0);
132  QSettings(const QString &fileName, Format format, QObject *parent = 0);
133  explicit QSettings(QObject *parent = 0);
134 #else
135  explicit QSettings(const QString &organization,
136  const QString &application = QString());
137  QSettings(Scope scope, const QString &organization,
138  const QString &application = QString());
139  QSettings(Format format, Scope scope, const QString &organization,
140  const QString &application = QString());
141  QSettings(const QString &fileName, Format format);
142 #endif
143  ~QSettings();
144 
145  void clear();
146  void sync();
147  Status status() const;
148 
149  void beginGroup(const QString &prefix);
150  void endGroup();
151  QString group() const;
152 
153  int beginReadArray(const QString &prefix);
154  void beginWriteArray(const QString &prefix, int size = -1);
155  void endArray();
156  void setArrayIndex(int i);
157 
158  QStringList allKeys() const;
159  QStringList childKeys() const;
160  QStringList childGroups() const;
161  bool isWritable() const;
162 
163  void setValue(const QString &key, const QVariant &value);
164  QVariant value(const QString &key, const QVariant &defaultValue = QVariant()) const;
165 
166  void remove(const QString &key);
167  bool contains(const QString &key) const;
168 
169  void setFallbacksEnabled(bool b);
170  bool fallbacksEnabled() const;
171 
172  QString fileName() const;
173  Format format() const;
174  Scope scope() const;
175  QString organizationName() const;
176  QString applicationName() const;
177 
178 #ifndef QT_NO_TEXTCODEC
180  void setIniCodec(const char *codecName);
181  QTextCodec *iniCodec() const;
182 #endif
183 
184  static void setDefaultFormat(Format format);
185  static Format defaultFormat();
186  static void setSystemIniPath(const QString &dir); // ### remove in 5.0 (use setPath() instead)
187  static void setUserIniPath(const QString &dir); // ### remove in 5.0 (use setPath() instead)
188  static void setPath(Format format, Scope scope, const QString &path);
189 
191  typedef bool (*ReadFunc)(QIODevice &device, SettingsMap &map);
192  typedef bool (*WriteFunc)(QIODevice &device, const SettingsMap &map);
193 
194  static Format registerFormat(const QString &extension, ReadFunc readFunc, WriteFunc writeFunc,
195  Qt::CaseSensitivity caseSensitivity = Qt::CaseSensitive);
196 
197 #ifdef QT3_SUPPORT
198  inline QT3_SUPPORT bool writeEntry(const QString &key, bool value)
199  { setValue(key, value); return isWritable(); }
200  inline QT3_SUPPORT bool writeEntry(const QString &key, double value)
201  { setValue(key, value); return isWritable(); }
202  inline QT3_SUPPORT bool writeEntry(const QString &key, int value)
203  { setValue(key, value); return isWritable(); }
204  inline QT3_SUPPORT bool writeEntry(const QString &key, const char *value)
205  { setValue(key, QString::fromAscii(value)); return isWritable(); }
206  inline QT3_SUPPORT bool writeEntry(const QString &key, const QString &value)
207  { setValue(key, value); return isWritable(); }
208  inline QT3_SUPPORT bool writeEntry(const QString &key, const QStringList &value)
209  { setValue(key, value); return isWritable(); }
210  inline QT3_SUPPORT bool writeEntry(const QString &key, const QStringList &value, QChar separator)
211  { setValue(key, value.join(QString(separator))); return isWritable(); }
212  inline QT3_SUPPORT QStringList readListEntry(const QString &key, bool *ok = 0)
213  {
214  if (ok)
215  *ok = contains(key);
216  return value(key).toStringList();
217  }
218  inline QT3_SUPPORT QStringList readListEntry(const QString &key, QChar separator, bool *ok = 0)
219  {
220  if (ok)
221  *ok = contains(key);
222  QString str = value(key).toString();
223  if (str.isEmpty())
224  return QStringList();
225  return str.split(separator);
226  }
227  inline QT3_SUPPORT QString readEntry(const QString &key, const QString &defaultValue = QString(),
228  bool *ok = 0)
229  {
230  if (ok)
231  *ok = contains(key);
232  return value(key, defaultValue).toString();
233  }
234  inline QT3_SUPPORT int readNumEntry(const QString &key, int defaultValue = 0, bool *ok = 0)
235  {
236  if (ok)
237  *ok = contains(key);
238  return value(key, defaultValue).toInt();
239  }
240  inline QT3_SUPPORT double readDoubleEntry(const QString &key, double defaultValue = 0,
241  bool *ok = 0)
242  {
243  if (ok)
244  *ok = contains(key);
245  return value(key, defaultValue).toDouble();
246  }
247  inline QT3_SUPPORT bool readBoolEntry(const QString &key, bool defaultValue = false,
248  bool *ok = 0)
249  {
250  if (ok)
251  *ok = contains(key);
252  return value(key, defaultValue).toBool();
253  }
254  inline QT3_SUPPORT bool removeEntry(const QString &key)
255  { remove(key); return true; }
256 
257  enum System { Unix, Windows, Mac };
258  inline QT3_SUPPORT void insertSearchPath(System, const QString &) {}
259  inline QT3_SUPPORT void removeSearchPath(System, const QString &) {}
260 
261  inline QT3_SUPPORT void setPath(const QString &organization, const QString &application,
262  Scope scope = Global)
263  {
264  setPath_helper(scope == Global ? QSettings::SystemScope : QSettings::UserScope,
265  organization, application);
266  }
267  inline QT3_SUPPORT void resetGroup()
268  {
269  while (!group().isEmpty())
270  endGroup();
271  }
272  inline QT3_SUPPORT QStringList entryList(const QString &key) const
273  {
274  QSettings *that = const_cast<QSettings *>(this);
275  QStringList result;
276 
277  that->beginGroup(key);
278  result = that->childKeys();
279  that->endGroup();
280  return result;
281  }
282  inline QT3_SUPPORT QStringList subkeyList(const QString &key) const
283  {
284  QSettings *that = const_cast<QSettings *>(this);
285  QStringList result;
286 
287  that->beginGroup(key);
288  result = that->childGroups();
289  that->endGroup();
290  return result;
291  }
292 #endif
293 
294 protected:
295 #ifndef QT_NO_QOBJECT
296  bool event(QEvent *event);
297 #endif
298 
299 private:
300 #ifdef QT3_SUPPORT
301  void setPath_helper(Scope scope, const QString &organization, const QString &application);
302 #endif
303 
305 };
306 
308 
309 #endif // QT_NO_SETTINGS
310 
312 
313 #endif // QSETTINGS_H
The QVariant class acts like a union for the most common Qt data types.
Definition: qvariant.h:92
Scope
) in file paths:
Definition: qsettings.h:115
static void allKeys(HKEY parentHandle, const QString &rSubKey, NameSet *result)
Status
The following status values are possible:
Definition: qsettings.h:86
void setValue(const QString &key, const QVariant &value)
Sets the value of setting key to value.
Definition: qsettings.cpp:3328
QVariant value(const QString &key, const QVariant &defaultValue=QVariant()) const
Returns the value for setting key.
Definition: qsettings.cpp:3460
Scope scope() const
Returns the scope used for storing the settings.
Definition: qsettings.cpp:2929
static Format defaultFormat()
Definition: qsettings.cpp:3494
#define QT_END_NAMESPACE
This macro expands to.
Definition: qglobal.h:90
EventRef event
static QString fromAscii(const char *, int size=-1)
Returns a QString initialized with the first size characters from the string str. ...
Definition: qstring.cpp:4276
#define QT_MODULE(x)
Definition: qglobal.h:2783
bool isWritable() const
Returns true if settings can be written using this QSettings object; returns false otherwise...
Definition: qsettings.cpp:3306
#define QT_BEGIN_HEADER
Definition: qglobal.h:136
int beginReadArray(const QString &prefix)
Adds prefix to the current group and starts reading from an array.
Definition: qsettings.cpp:3129
The QSettings class provides persistent platform-independent application settings.
Definition: qsettings.h:73
void endGroup()
Resets the group to what it was before the corresponding beginGroup() call.
Definition: qsettings.cpp:3089
Format
This enum type specifies the storage format used by QSettings.
Definition: qsettings.h:92
void beginGroup(const QString &prefix)
Appends prefix to the current group.
Definition: qsettings.cpp:3073
static void clear(QVariant::Private *d)
Definition: qvariant.cpp:197
QString toString() const
Returns the variant as a QString if the variant has type() String , Bool , ByteArray ...
Definition: qvariant.cpp:2270
static LibLoadStatus status
Definition: qlocale_icu.cpp:69
void setIniCodec(QTextCodec *codec)
Sets the codec for accessing INI files (including .
Definition: qsettings.cpp:2986
bool toBool() const
Returns the variant as a bool if the variant has type() Bool.
Definition: qvariant.cpp:2691
#define Q_DISABLE_COPY(Class)
Disables the use of copy constructors and assignment operators for the given Class.
Definition: qglobal.h:2523
The QString class provides a Unicode character string.
Definition: qstring.h:83
The QObject class is the base class of all Qt objects.
Definition: qobject.h:111
virtual bool event(QEvent *)
This virtual function receives events to an object and should return true if the event e was recogniz...
Definition: qobject.cpp:1200
static void setPath(Format format, Scope scope, const QString &path)
Sets the path used for storing settings for the given format and scope, to path.
Definition: qsettings.cpp:3578
void sync()
Writes any unsaved changes to permanent storage, and reloads any settings that have been changed in t...
Definition: qsettings.cpp:2882
void endArray()
Closes the array that was started using beginReadArray() or beginWriteArray().
Definition: qsettings.cpp:3182
The QChar class provides a 16-bit Unicode character.
Definition: qchar.h:72
QTextCodec * iniCodec() const
Returns the codec that is used for accessing INI files.
Definition: qsettings.cpp:3023
QString group() const
Returns the current group.
Definition: qsettings.cpp:3111
QStringList childGroups() const
Returns a list of all key top-level groups that contain keys that can be read using the QSettings obj...
Definition: qsettings.cpp:3288
The QScopedPointer class stores a pointer to a dynamically allocated object, and deletes it upon dest...
int toInt(bool *ok=0) const
Returns the variant as an int if the variant has type() Int , Bool , ByteArray , Char ...
Definition: qvariant.cpp:2625
QStringList toStringList() const
Returns the variant as a QStringList if the variant has type() StringList, String ...
Definition: qvariant.cpp:2259
QFuture< void > map(Sequence &sequence, MapFunction function)
#define QT_BEGIN_NAMESPACE
This macro expands to.
Definition: qglobal.h:89
static bool isEmpty(const char *str)
bool isEmpty() const
Returns true if the string has no characters; otherwise returns false.
Definition: qstring.h:704
static void setUserIniPath(const QString &dir)
Use setPath() instead.
Definition: qsettings.cpp:3531
The QStringList class provides a list of strings.
Definition: qstringlist.h:66
static QTextCodec * codec(MYSQL *mysql)
Definition: qsql_mysql.cpp:220
QString organizationName() const
Returns the organization name used for storing the settings.
Definition: qsettings.cpp:2945
QStringList childKeys() const
Returns a list of all top-level keys that can be read using the QSettings object. ...
Definition: qsettings.cpp:3264
#define Q_OBJECT
Definition: qobjectdefs.h:157
void setArrayIndex(int i)
Sets the current array index to i.
Definition: qsettings.cpp:3211
QString join(const QString &sep) const
Joins all the string list&#39;s strings into a single string with each element separated by the given sep...
Definition: qstringlist.h:162
CaseSensitivity
Definition: qnamespace.h:1451
~QSettings()
Destroys the QSettings object.
Definition: qsettings.cpp:2841
#define Q_CORE_EXPORT
Definition: qglobal.h:1449
int key
bool contains(const QString &key) const
Returns true if there exists a setting called key; returns false otherwise.
Definition: qsettings.cpp:3394
QSettings(const QString &organization, const QString &application=QString(), QObject *parent=0)
Constructs a QSettings object for accessing settings of the application called application from the o...
Definition: qsettings.cpp:2666
double toDouble(bool *ok=0) const
Returns the variant as a double if the variant has type() Double , QMetaType::Float ...
Definition: qvariant.cpp:2710
static Format registerFormat(const QString &extension, ReadFunc readFunc, WriteFunc writeFunc, Qt::CaseSensitivity caseSensitivity=Qt::CaseSensitive)
Registers a custom storage format.
Definition: qsettings.cpp:3663
QScopedPointer< QObjectData > d_ptr
Definition: qobject.h:320
QMap< QString, QVariant > SettingsMap
Typedef for QMap<QString, QVariant>.
Definition: qsettings.h:190
#define Q_DECLARE_PRIVATE(Class)
Definition: qglobal.h:2467
QStringList split(const QString &sep, SplitBehavior behavior=KeepEmptyParts, Qt::CaseSensitivity cs=Qt::CaseSensitive) const Q_REQUIRED_RESULT
Splits the string into substrings wherever sep occurs, and returns the list of those strings...
Definition: qstring.cpp:6526
static void setSystemIniPath(const QString &dir)
Use setPath() instead.
Definition: qsettings.cpp:3514
The QTextCodec class provides conversions between text encodings.
Definition: qtextcodec.h:62
QString applicationName() const
Returns the application name used for storing the settings.
Definition: qsettings.cpp:2961
#define class
void beginWriteArray(const QString &prefix, int size=-1)
Adds prefix to the current group and starts writing an array of size size.
Definition: qsettings.cpp:3165
The QIODevice class is the base interface class of all I/O devices in Qt.
Definition: qiodevice.h:66
The QEvent class is the base class of all event classes.
Definition: qcoreevent.h:56
#define QT_END_HEADER
Definition: qglobal.h:137
static QString fileName(const QString &fileUrl)
static void setDefaultFormat(Format format)
Definition: qsettings.cpp:3481
void setFallbacksEnabled(bool b)
Sets whether fallbacks are enabled to b.
Definition: qsettings.cpp:3408
bool fallbacksEnabled() const
Returns true if fallbacks are enabled; returns false otherwise.
Definition: qsettings.cpp:3421