1QSettings(3qt) QSettings(3qt)
2
6 QSettings - Persistent platform-independent application settings
7
9 #include <qsettings.h>
10 Public Members
12 enum Format { Native = 0, Ini }
13 enum System { Unix = 0, Windows, Mac }
14 enum Scope { User, Global }
15 QSettings ()
16 QSettings ( Format format )
17 ~QSettings ()
18 bool writeEntry ( const QString & key, bool value )
19 bool writeEntry ( const QString & key, double value )
20 bool writeEntry ( const QString & key, int value )
21 bool writeEntry ( const QString & key, const QString & value )
22 bool writeEntry ( const QString & key, const QStringList & value )
23 bool writeEntry ( const QString & key, const QStringList & value, const
24 QChar & separator ) (obsolete)
25 QStringList entryList ( const QString & key ) const
26 QStringList subkeyList ( const QString & key ) const
27 QStringList readListEntry ( const QString & key, bool * ok = 0 ) const
28 QStringList readListEntry ( const QString & key, const QChar &
29 separator, bool * ok = 0 ) const (obsolete)
30 QString readEntry ( const QString & key, const QString & def =
31 QString::null, bool * ok = 0 ) const
32 int readNumEntry ( const QString & key, int def = 0, bool * ok = 0 )
33 const
34 double readDoubleEntry ( const QString & key, double def = 0, bool * ok
35 = 0 ) const
36 bool readBoolEntry ( const QString & key, bool def = FALSE, bool * ok =
37 0 ) const
38 bool removeEntry ( const QString & key )
39 void insertSearchPath ( System s, const QString & path )
40 void removeSearchPath ( System s, const QString & path )
41 void setPath ( const QString & domain, const QString & product, Scope
42 scope = Global )
43 void beginGroup ( const QString & group )
44 void endGroup ()
45 void resetGroup ()
46 QString group () const
47
49 The QSettings class provides persistent platform-independent
50 application settings.
51 On Unix systems, QSettings uses text files to store settings. On
53 Windows systems, QSettings uses the system registry. On Mac OS X,
54 QSettings uses the Carbon preferences API.
55 Each setting comprises an identifying key and the data associated with
57 the key. A key is a unicode string which consists of two or more
58 subkeys. A subkey is a slash, '/', followed by one or more unicode
59 characters (excluding slashes, newlines, carriage returns and equals,
60 '=', signs). The associated data, called the entry or value, may be a
61 boolean, an integer, a double, a string or a list of strings. Entry
62 strings may contain any unicode characters.
63 If you want to save and restore the entire desktop's settings, i.e.
65 which applications are running, use QSettings to save the settings for
66 each individual application and QSessionManager to save the desktop's
67 session.
68 Example settings:
70 /MyCompany/MyApplication/background color
72 /MyCompany/MyApplication/foreground color
73 /MyCompany/MyApplication/geometry/x
74 /MyCompany/MyApplication/geometry/y
75 /MyCompany/MyApplication/geometry/width
76 /MyCompany/MyApplication/geometry/height
77 /MyCompany/MyApplication/recent files/1
78 /MyCompany/MyApplication/recent files/2
79 /MyCompany/MyApplication/recent files/3
80 Each line above is a complete key, made up of subkeys.
81 A typical usage pattern for reading settings at application startup:
83 QSettings settings;
85 settings.setPath( "MyCompany.com", "MyApplication" );
86 QString bgColor = settings.readEntry( "/colors/background", "white" );
87 int width = settings.readNumEntry( "/geometry/width", 640 );
88 // ...
89 A typical usage pattern for saving settings at application exit or
91 'save preferences':
92 QSettings settings;
94 settings.setPath( "MyCompany.com", "MyApplication" );
95 settings.writeEntry( "/colors/background", bgColor );
96 settings.writeEntry( "/geometry/width", width );
97 // ...
98 A key prefix can be prepended to all keys using beginGroup(). The
100 application of the prefix is stopped using endGroup(). For example:
101 QSettings settings;
103 settings.beginGroup( "/MainWindow" );
104 settings.beginGroup( "/Geometry" );
105 int x = settings.readEntry( "/x" );
106 // ...
107 settings.endGroup();
108 settings.beginGroup( "/Toolbars" );
109 // ...
110 settings.endGroup();
111 settings.endGroup();
112 You can get a list of entry-holding keys by calling entryList(), and a
114 list of key-holding keys using subkeyList().
115 QStringList keys = settings.entryList( "/MyApplication" );
117 // keys contains 'background color' and 'foreground color'.
118 QStringList keys = settings.entryList( "/MyApplication/recent files" );
119 // keys contains '1', '2' and '3'.
120 QStringList subkeys = settings.subkeyList( "/MyApplication" );
121 // subkeys contains 'geometry' and 'recent files'
122 QStringList subkeys = settings.subkeyList( "/MyApplication/recent files" );
123 // subkeys is empty.
124 Since settings for Windows are stored in the registry there are some
126 size limitations as follows:
127 A subkey may not exceed 255 characters.
129 An entry's value may not exceed 16,300 characters.
131 All the values of a key (for example, all the 'recent files' subkeys
133 values), may not exceed 65,535 characters.
134 These limitations are not enforced on Unix or Mac OS X.
136 Warning: Creating multiple, simultaneous instances of QSettings writing
138 to a text file may lead to data loss! This is a known issue which will
139 be fixed in a future release of Qt.
140
142 The location where settings are stored is not formally defined by the
143 CFPreferences API.
144 At the time of writing settings are stored (either on a global or user
146 basis, preferring locally) into a plist file in
147 $ROOT/System/Library/Preferences (in XML format). QSettings will create
148 an appropriate plist file (com.<first group name>.plist) out of the
149 full path to a key.
150 For further information on CFPreferences see Apple's Specifications
152
154 There is no universally accepted place for storing application settings
155 under Unix. In the examples the settings file will be searched for in
156 the following directories: <ol type=1>
157 SYSCONF - the default value is INSTALL/etc/settings
159 /opt/MyCompany/share/etc
161 /opt/MyCompany/share/MyApplication/etc
163 $HOME/.qt When reading settings the files are searched in the order
165 shown above, with later settings overriding earlier settings. Files for
166 which the user doesn't have read permission are ignored. When saving
167 settings QSettings works in the order shown above, writing to the first
168 settings file for which the user has write permission. (INSTALL is the
169 directory where Qt was installed. This can be modified by using the
170 configure script's -prefix argument )
171 If you want to put the settings in a particular place in the filesystem
173 you could do this:
174 settings.insertSearchPath( QSettings::Unix, "/opt/MyCompany/share" );
176 But in practice you may prefer not to use a search path for Unix. For
178 example the following code:
179 settings.writeEntry( "/MyApplication/geometry/width", width );
181 will end up writing the "geometry/width" setting to the file
182 $HOME/.qt/myapplicationrc (assuming that the application is being run
183 by an ordinary user, i.e. not by root).
184 For cross-platform applications you should ensure that the Windows size
186 limitations are not exceeded.
187 Warning: QSettings doesn't write the settings until it is destroyed so
189 you should construct the QSettings object on the stack.
190 See also Input/Output and Networking and Miscellaneous Classes.
192 Member Type Documentation
195 QSettings::Native - Store the settings in a platform dependent location
196 QSettings::Ini - Store the settings in a text file
198
200 QSettings::Global - Save settings as global as possible
201 QSettings::User - Save settings in user space
203
205 QSettings::Mac - Macintosh execution environments
206 QSettings::Unix - Mac OS X, Unix, Linux and Unix-like execution
208 environments
209 QSettings::Windows - Windows execution environments
211
214 Creates a settings object.
215 Be aware that you must call setPath() or insertSearchPath() before you
217 can use the QSettings object.
218
220 Creates a settings object. If format is 'Ini' the settings will be
221 stored in a text file, using the Unix strategy (see above). If format
222 is 'Native', the settings will be stored in a platform specific way
223 (ie. the Windows registry).
224 Be aware that you must call setPath() or insertSearchPath() before you
226 can use the QSettings object.
227
229 Destroys the settings object. All modifications made to the settings
230 will automatically be saved.
231
233 Appends group to the current key prefix.
234 QSettings settings;
236 settings.beginGroup( "/MainWindow" );
237 // read values
238 settings.endGroup();
239
241 Undo previous calls to beginGroup(). Note that a single
242 beginGroup("a/b/c") is undone by a single call to endGroup().
243 QSettings settings;
245 settings.beginGroup( "/MainWindow/Geometry" );
246 // read values
247 settings.endGroup();
248
250 Returns a list of the keys which contain entries under key. Does not
251 return any keys that contain subkeys.
252 Example settings:
254 /MyCompany/MyApplication/background color
256 /MyCompany/MyApplication/foreground color
257 /MyCompany/MyApplication/geometry/x
258 /MyCompany/MyApplication/geometry/y
259 /MyCompany/MyApplication/geometry/width
260 /MyCompany/MyApplication/geometry/height
261 QStringList keys = settings.entryList( "/MyCompany/MyApplication" );
263 In the above example, keys will contain 'background color' and
265 'foreground color'. It will not contain 'geometry' because this key
266 contains subkeys not entries.
267 To access the geometry values, you could either use subkeyList() to
269 read the keys then read each entry, or simply read each entry directly
270 by specifying its full key, e.g." /MyCompany/MyApplication/geometry/y".
271 See also subkeyList().
273
275 Returns the current key prefix, or a null string if there is no key
276 prefix set.
277 See also beginGroup().
279
281 Inserts path into the settings search path. The semantics of path
282 depends on the system s. It is usually easier and better to use
283 setPath() instead of this function.
284 When s is Windows and the execution environment is not Windows the
286 function does nothing. Similarly when s is Unix and the execution
287 environment is not Unix the function does nothing.
288 When s is Windows, and the execution environment is Windows, the search
290 path list will be used as the first subfolder of the "Software" folder
291 in the registry.
292 When reading settings the folders are searched forwards from the first
294 folder (listed below) to the last, returning the first settings found,
295 and ignoring any folders for which the user doesn't have read
296 permission. <ol type=1>
297 HKEY_CURRENT_USER/Software/MyCompany/MyApplication
299 HKEY_LOCAL_MACHINE/Software/MyCompany/MyApplication
301 HKEY_CURRENT_USER/Software/MyApplication
303 HKEY_LOCAL_MACHINE/Software/MyApplication
305 QSettings settings;
307 settings.insertSearchPath( QSettings::Windows, "/MyCompany" );
308 settings.writeEntry( "/MyApplication/Tip of the day", TRUE );
309 The code above will write the subkey "Tip of the day" into the first of
310 the registry folders listed below that is found and for which the user
311 has write permission. <ol type=1>
312 HKEY_LOCAL_MACHINE/Software/MyCompany/MyApplication
314 HKEY_CURRENT_USER/Software/MyCompany/MyApplication
316 HKEY_LOCAL_MACHINE/Software/MyApplication
318 HKEY_CURRENT_USER/Software/MyApplication If a setting is found in the
320 HKEY_CURRENT_USER space, this setting is overwritten independently of
321 write permissions in the HKEY_LOCAL_MACHINE space.
322 When s is Unix, and the execution environment is Unix, the search path
324 list will be used when trying to determine a suitable filename for
325 reading and writing settings files. By default, there are two entries
326 in the search path:
327 <ol type=1>
329 SYSCONF - where SYSCONF is a directory specified when configuring Qt;
331 by default it is INSTALL/etc/settings.
332 $HOME/.qt/ - where $HOME is the user's home directory.
334 All insertions into the search path will go before $HOME/.qt/. For
336 example:
337 QSettings settings;
339 settings.insertSearchPath( QSettings::Unix, "/opt/MyCompany/share/etc" );
340 settings.insertSearchPath( QSettings::Unix, "/opt/MyCompany/share/MyApplication/etc" );
341 // ...
342 Will result in a search path of: <ol type=1>
343 SYSCONF
345 /opt/MyCompany/share/etc
347 /opt/MyCompany/share/MyApplication/etc
349 $HOME/.qt When reading settings the files are searched in the order
351 shown above, with later settings overriding earlier settings. Files for
352 which the user doesn't have read permission are ignored. When saving
353 settings QSettings works in the order shown above, writing to the first
354 settings file for which the user has write permission.
355 Note that paths in the file system are not created by this function, so
357 they must already exist to be useful.
358 Settings under Unix are stored in files whose names are based on the
360 first subkey of the key (not including the search path). The algorithm
361 for creating names is essentially: lowercase the first subkey, replace
362 spaces with underscores and add 'rc', e.g.
363 /MyCompany/MyApplication/background color will be stored in
364 myapplicationrc (assuming that /MyCompany is part of the search path).
365 See also removeSearchPath().
367 Example: chart/chartform.cpp.
369
371 ok = 0 ) const
372 Reads the entry specified by key, and returns a bool, or the default
373 value, def, if the entry couldn't be read. If ok is non-null, *ok is
374 set to TRUE if the key was read, FALSE otherwise.
375 See also readEntry(), readNumEntry(), readDoubleEntry(), writeEntry(),
377 and removeEntry().
378
380 * ok = 0 ) const
381 Reads the entry specified by key, and returns a double, or the default
382 value, def, if the entry couldn't be read. If ok is non-null, *ok is
383 set to TRUE if the key was read, FALSE otherwise.
384 See also readEntry(), readNumEntry(), readBoolEntry(), writeEntry(),
386 and removeEntry().
387
389 QString::null, bool * ok = 0 ) const
390 Reads the entry specified by key, and returns a QString, or the default
391 value, def, if the entry couldn't be read. If ok is non-null, *ok is
392 set to TRUE if the key was read, FALSE otherwise.
393 See also readListEntry(), readNumEntry(), readDoubleEntry(),
395 readBoolEntry(), writeEntry(), and removeEntry().
396
398 const
399 Reads the entry specified by key as a string. If ok is not 0, *ok is
400 set to TRUE if the key was read, otherwise *ok is set to FALSE.
401 Note that if you want to iterate over the list, you should iterate over
403 a copy, e.g.
404 QStringList list = mySettings.readListEntry( "recentfiles" );
406 QStringList::Iterator it = list.begin();
407 while( it != list.end() ) {
408 myProcessing( *it );
409 ++it;
410 }
411 See also readEntry(), readDoubleEntry(), readBoolEntry(), writeEntry(),
413 removeEntry(), and QStringList::split().
414
416 separator, bool * ok = 0 ) const
417 This is an overloaded member function, provided for convenience. It
418 behaves essentially like the above function.
419 This function is obsolete. It is provided to keep old source working.
421 We strongly advise against using it in new code.
422 Reads the entry specified by key as a string. The separator is used to
424 create a QStringList by calling QStringList::split(separator, entry).
425 If ok is not 0: *ok is set to TRUE if the key was read, otherwise *ok
426 is set to FALSE.
427 Warning: As the documentation states, QStringList::split() will omit
429 empty strings from the list. Because of this, it is impossible to
430 retrieve identical list data with this function. We recommend using the
431 readListEntry() and writeEntry() overloads that do not take a separator
432 argument.
433 Note that if you want to iterate over the list, you should iterate over
435 a copy, e.g.
436 QStringList list = mySettings.readListEntry( "size", " " );
438 QStringList::Iterator it = list.begin();
439 while( it != list.end() ) {
440 myProcessing( *it );
441 ++it;
442 }
443 See also readEntry(), readDoubleEntry(), readBoolEntry(), writeEntry(),
445 removeEntry(), and QStringList::split().
446
448 ) const
449 Reads the entry specified by key, and returns an integer, or the
450 default value, def, if the entry couldn't be read. If ok is non-null,
451 *ok is set to TRUE if the key was read, FALSE otherwise.
452 See also readEntry(), readDoubleEntry(), readBoolEntry(), writeEntry(),
454 and removeEntry().
455
457 Removes the entry specified by key.
458 Returns true if the entry was successfully removed; otherwise returns
460 false. Note that removing the last entry in any given folder, will also
461 remove the folder.
462 See also readEntry() and writeEntry().
464
466 Removes all occurrences of path (using exact matching) from the
467 settings search path for system s. Note that the default search paths
468 cannot be removed.
469 See also insertSearchPath().
471
473 Set the current key prefix to the empty string.
474
476 Scope scope = Global )
477 Insert platform-dependent paths from platform-independent information.
478 The domain should be an Internet domain name controlled by the producer
480 of the software, eg. Trolltech products use "trolltech.com".
481 The product should be the official name of the product.
483 The scope should be QSettings::User for user-specific settings, or
485 QSettings::Global for system-wide settings (generally these will be
486 read-only to many users).
487 Not all information is relevant on all systems.
489
491 Returns a list of the keys which contain subkeys under key. Does not
492 return any keys that contain entries.
493 Example settings:
495 /MyCompany/MyApplication/background color
497 /MyCompany/MyApplication/foreground color
498 /MyCompany/MyApplication/geometry/x
499 /MyCompany/MyApplication/geometry/y
500 /MyCompany/MyApplication/geometry/width
501 /MyCompany/MyApplication/geometry/height
502 /MyCompany/MyApplication/recent files/1
503 /MyCompany/MyApplication/recent files/2
504 /MyCompany/MyApplication/recent files/3
505 QStringList keys = settings.subkeyList( "/MyCompany/MyApplication" );
507 In the above example, keys will contain 'geometry' and 'recent files'.
509 It will not contain 'background color' or 'foreground color' because
510 those keys contain entries not subkeys. To get a list of keys that
511 contain entries rather than subkeys use entryList() instead.
512 Warning: In the above example, if QSettings is writing to an Ini file,
514 then a call to
515 subkeyList("/MyCompany")
517 will return an empty list. This happens because a key like
518 /MyCompany/MyApplication/background color
520 is written to the file "mycompanyrc", under the section
521 [MyApplication]. This call is therefore a request to list the sections
522 in an ini file, which is not supported in this version of QSettings.
523 This is a known issue which will be fixed in Qt-4.
524 See also entryList().
526
528 Writes the boolean entry value into key key. The key is created if it
529 doesn't exist. Any previous value is overwritten by value.
530 If an error occurs the settings are left unchanged and FALSE is
532 returned; otherwise TRUE is returned.
533 Warning: On certain platforms, keys are required to contain at least
535 two components (e.g., "/foo/bar"). This limitation does not apply to Qt
536 4.
537 See also readListEntry(), readNumEntry(), readDoubleEntry(),
539 readBoolEntry(), and removeEntry().
540 Example: chart/chartform.cpp.
542
544 This is an overloaded member function, provided for convenience. It
545 behaves essentially like the above function.
546 Writes the double entry value into key key. The key is created if it
548 doesn't exist. Any previous value is overwritten by value.
549 If an error occurs the settings are left unchanged and FALSE is
551 returned; otherwise TRUE is returned.
552 See also readListEntry(), readNumEntry(), readDoubleEntry(),
554 readBoolEntry(), and removeEntry().
555
557 This is an overloaded member function, provided for convenience. It
558 behaves essentially like the above function.
559 Writes the integer entry value into key key. The key is created if it
561 doesn't exist. Any previous value is overwritten by value.
562 If an error occurs the settings are left unchanged and FALSE is
564 returned; otherwise TRUE is returned.
565 See also readListEntry(), readNumEntry(), readDoubleEntry(),
567 readBoolEntry(), and removeEntry().
568
570 This is an overloaded member function, provided for convenience. It
571 behaves essentially like the above function.
572 Writes the string entry value into key key. The key is created if it
574 doesn't exist. Any previous value is overwritten by value. If value is
575 an empty string or a null string the key's value will be an empty
576 string.
577 If an error occurs the settings are left unchanged and FALSE is
579 returned; otherwise TRUE is returned.
580 See also readListEntry(), readNumEntry(), readDoubleEntry(),
582 readBoolEntry(), and removeEntry().
583
585 This is an overloaded member function, provided for convenience. It
586 behaves essentially like the above function.
587 Writes the string list entry value into key key. The key is created if
589 it doesn't exist. Any previous value is overwritten by value.
590 If an error occurs the settings are left unchanged and FALSE is
592 returned; otherwise returns TRUE.
593 See also readListEntry(), readNumEntry(), readDoubleEntry(),
595 readBoolEntry(), and removeEntry().
596
598 const QChar & separator )
599 This is an overloaded member function, provided for convenience. It
600 behaves essentially like the above function.
601 This function is obsolete. It is provided to keep old source working.
603 We strongly advise against using it in new code.
604 Writes the string list entry value into key key. The key is created if
606 it doesn't exist. Any previous value is overwritten by value. The list
607 is stored as a sequence of strings separated by separator (using
608 QStringList::join()), so none of the strings in the list should contain
609 the separator. If the list is empty or null the key's value will be an
610 empty string.
611 Warning: The list should not contain empty or null strings, as
613 readListEntry() will use QStringList::split() to recreate the list. As
614 the documentation states, QStringList::split() will omit empty strings
615 from the list. Because of this, it is impossible to retrieve identical
616 list data that is stored with this function. We recommend using the
617 writeEntry() and readListEntry() overloads that do not take a separator
618 argument.
619 If an error occurs the settings are left unchanged and FALSE is
621 returned; otherwise returns TRUE.
622 See also readListEntry(), readNumEntry(), readDoubleEntry(),
624 readBoolEntry(), removeEntry(), and QStringList::join().
625
628 http://doc.trolltech.com/qsettings.html
629 http://www.trolltech.com/faq/tech.html
630
632 Copyright 1992-2007 Trolltech ASA, http://www.trolltech.com. See the
633 license file included in the distribution for a complete license
634 statement.
635
637 Generated automatically from the source code.
638
640 If you find a bug in Qt, please report it as described in
641 http://doc.trolltech.com/bughowto.html. Good bug reports help us to
642 help you. Thank you.
643 The definitive Qt documentation is provided in HTML format; it is
645 located at $QTDIR/doc/html and can be read using Qt Assistant or with a
646 web browser. This man page is provided as a convenience for those users
647 who prefer man pages, although this format is not officially supported
648 by Trolltech.
649 If you find errors in this manual page, please report them to qt-
651 bugs@trolltech.com. Please include the name of the manual page
652 (qsettings.3qt) and the Qt version (3.3.8).
653Trolltech AS 2 February 2007 QSettings(3qt)