1QSettings(3qt)                                                  QSettings(3qt)
2
3
4

NAME

6       QSettings - Persistent platform-independent application settings
7

SYNOPSIS

9       #include <qsettings.h>
10
11   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

DESCRIPTION

49       The QSettings class provides persistent platform-independent
50       application settings.
51
52       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
56       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
64       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
69       Example settings:
70
71           /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
82       A typical usage pattern for reading settings at application startup:
83
84           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
90       A typical usage pattern for saving settings at application exit or
91       'save preferences':
92
93           QSettings settings;
94           settings.setPath( "MyCompany.com", "MyApplication" );
95           settings.writeEntry( "/colors/background", bgColor );
96           settings.writeEntry( "/geometry/width", width );
97           // ...
98
99       A key prefix can be prepended to all keys using beginGroup(). The
100       application of the prefix is stopped using endGroup(). For example:
101
102           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
113       You can get a list of entry-holding keys by calling entryList(), and a
114       list of key-holding keys using subkeyList().
115
116           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
125       Since settings for Windows are stored in the registry there are some
126       size limitations as follows:
127
128       A subkey may not exceed 255 characters.
129
130       An entry's value may not exceed 16,300 characters.
131
132       All the values of a key (for example, all the 'recent files' subkeys
133       values), may not exceed 65,535 characters.
134
135       These limitations are not enforced on Unix or Mac OS X.
136
137       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

Notes for Mac OS X Applications

142       The location where settings are stored is not formally defined by the
143       CFPreferences API.
144
145       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
151       For further information on CFPreferences see Apple's Specifications
152

Notes for Unix Applications

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
158       SYSCONF - the default value is INSTALL/etc/settings
159
160       /opt/MyCompany/share/etc
161
162       /opt/MyCompany/share/MyApplication/etc
163
164       $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
172       If you want to put the settings in a particular place in the filesystem
173       you could do this:
174
175           settings.insertSearchPath( QSettings::Unix, "/opt/MyCompany/share" );
176
177       But in practice you may prefer not to use a search path for Unix. For
178       example the following code:
179
180           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
185       For cross-platform applications you should ensure that the Windows size
186       limitations are not exceeded.
187
188       Warning: QSettings doesn't write the settings until it is destroyed so
189       you should construct the QSettings object on the stack.
190
191       See also Input/Output and Networking and Miscellaneous Classes.
192
193   Member Type Documentation

QSettings::Format

195       QSettings::Native - Store the settings in a platform dependent location
196
197       QSettings::Ini - Store the settings in a text file
198

QSettings::Scope

200       QSettings::Global - Save settings as global as possible
201
202       QSettings::User - Save settings in user space
203

QSettings::System

205       QSettings::Mac - Macintosh execution environments
206
207       QSettings::Unix - Mac OS X, Unix, Linux and Unix-like execution
208       environments
209
210       QSettings::Windows - Windows execution environments
211

MEMBER FUNCTION DOCUMENTATION

QSettings::QSettings ()

214       Creates a settings object.
215
216       Be aware that you must call setPath() or insertSearchPath() before you
217       can use the QSettings object.
218

QSettings::QSettings ( Format format )

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
225       Be aware that you must call setPath() or insertSearchPath() before you
226       can use the QSettings object.
227

QSettings::~QSettings ()

229       Destroys the settings object. All modifications made to the settings
230       will automatically be saved.
231

void QSettings::beginGroup ( const QString & group )

233       Appends group to the current key prefix.
234
235           QSettings settings;
236           settings.beginGroup( "/MainWindow" );
237           // read values
238           settings.endGroup();
239

void QSettings::endGroup ()

241       Undo previous calls to beginGroup(). Note that a single
242       beginGroup("a/b/c") is undone by a single call to endGroup().
243
244           QSettings settings;
245           settings.beginGroup( "/MainWindow/Geometry" );
246           // read values
247           settings.endGroup();
248

QStringList QSettings::entryList ( const QString & key ) const

250       Returns a list of the keys which contain entries under key. Does not
251       return any keys that contain subkeys.
252
253       Example settings:
254
255           /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
262           QStringList keys = settings.entryList( "/MyCompany/MyApplication" );
263
264       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
268       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
272       See also subkeyList().
273

QString QSettings::group () const

275       Returns the current key prefix, or a null string if there is no key
276       prefix set.
277
278       See also beginGroup().
279

void QSettings::insertSearchPath ( System s, const QString & path )

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
285       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
289       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
293       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
298       HKEY_CURRENT_USER/Software/MyCompany/MyApplication
299
300       HKEY_LOCAL_MACHINE/Software/MyCompany/MyApplication
301
302       HKEY_CURRENT_USER/Software/MyApplication
303
304       HKEY_LOCAL_MACHINE/Software/MyApplication
305
306         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
313       HKEY_LOCAL_MACHINE/Software/MyCompany/MyApplication
314
315       HKEY_CURRENT_USER/Software/MyCompany/MyApplication
316
317       HKEY_LOCAL_MACHINE/Software/MyApplication
318
319       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
323       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
328       <ol type=1>
329
330       SYSCONF - where SYSCONF is a directory specified when configuring Qt;
331       by default it is INSTALL/etc/settings.
332
333       $HOME/.qt/ - where $HOME is the user's home directory.
334
335       All insertions into the search path will go before $HOME/.qt/. For
336       example:
337
338         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
344       SYSCONF
345
346       /opt/MyCompany/share/etc
347
348       /opt/MyCompany/share/MyApplication/etc
349
350       $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
356       Note that paths in the file system are not created by this function, so
357       they must already exist to be useful.
358
359       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
366       See also removeSearchPath().
367
368       Example: chart/chartform.cpp.
369

bool QSettings::readBoolEntry ( const QString & key, bool def = FALSE, bool *

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
376       See also readEntry(), readNumEntry(), readDoubleEntry(), writeEntry(),
377       and removeEntry().
378

double QSettings::readDoubleEntry ( const QString & key, double def = 0, bool

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
385       See also readEntry(), readNumEntry(), readBoolEntry(), writeEntry(),
386       and removeEntry().
387

QString QSettings::readEntry ( const QString & key, const QString & def =

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
394       See also readListEntry(), readNumEntry(), readDoubleEntry(),
395       readBoolEntry(), writeEntry(), and removeEntry().
396

QStringList QSettings::readListEntry ( const QString & key, bool * ok = 0 )

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
402       Note that if you want to iterate over the list, you should iterate over
403       a copy, e.g.
404
405           QStringList list = mySettings.readListEntry( "recentfiles" );
406           QStringList::Iterator it = list.begin();
407           while( it != list.end() ) {
408               myProcessing( *it );
409               ++it;
410           }
411
412       See also readEntry(), readDoubleEntry(), readBoolEntry(), writeEntry(),
413       removeEntry(), and QStringList::split().
414

QStringList QSettings::readListEntry ( const QString & key, const QChar &

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
420       This function is obsolete. It is provided to keep old source working.
421       We strongly advise against using it in new code.
422
423       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
428       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
434       Note that if you want to iterate over the list, you should iterate over
435       a copy, e.g.
436
437           QStringList list = mySettings.readListEntry( "size", " " );
438           QStringList::Iterator it = list.begin();
439           while( it != list.end() ) {
440               myProcessing( *it );
441               ++it;
442           }
443
444       See also readEntry(), readDoubleEntry(), readBoolEntry(), writeEntry(),
445       removeEntry(), and QStringList::split().
446

int QSettings::readNumEntry ( const QString & key, int def = 0, bool * ok = 0

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
453       See also readEntry(), readDoubleEntry(), readBoolEntry(), writeEntry(),
454       and removeEntry().
455

bool QSettings::removeEntry ( const QString & key )

457       Removes the entry specified by key.
458
459       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
463       See also readEntry() and writeEntry().
464

void QSettings::removeSearchPath ( System s, const QString & path )

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
470       See also insertSearchPath().
471

void QSettings::resetGroup ()

473       Set the current key prefix to the empty string.
474

void QSettings::setPath ( const QString & domain, const QString & product,

476       Scope scope = Global )
477       Insert platform-dependent paths from platform-independent information.
478
479       The domain should be an Internet domain name controlled by the producer
480       of the software, eg. Trolltech products use "trolltech.com".
481
482       The product should be the official name of the product.
483
484       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
488       Not all information is relevant on all systems.
489

QStringList QSettings::subkeyList ( const QString & key ) const

491       Returns a list of the keys which contain subkeys under key. Does not
492       return any keys that contain entries.
493
494       Example settings:
495
496           /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
506           QStringList keys = settings.subkeyList( "/MyCompany/MyApplication" );
507
508       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
513       Warning: In the above example, if QSettings is writing to an Ini file,
514       then a call to
515
516        subkeyList("/MyCompany")
517       will return an empty list. This happens because a key like
518
519        /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
525       See also entryList().
526

bool QSettings::writeEntry ( const QString & key, bool value )

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
531       If an error occurs the settings are left unchanged and FALSE is
532       returned; otherwise TRUE is returned.
533
534       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
538       See also readListEntry(), readNumEntry(), readDoubleEntry(),
539       readBoolEntry(), and removeEntry().
540
541       Example: chart/chartform.cpp.
542

bool QSettings::writeEntry ( const QString & key, double value )

544       This is an overloaded member function, provided for convenience. It
545       behaves essentially like the above function.
546
547       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
550       If an error occurs the settings are left unchanged and FALSE is
551       returned; otherwise TRUE is returned.
552
553       See also readListEntry(), readNumEntry(), readDoubleEntry(),
554       readBoolEntry(), and removeEntry().
555

bool QSettings::writeEntry ( const QString & key, int value )

557       This is an overloaded member function, provided for convenience. It
558       behaves essentially like the above function.
559
560       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
563       If an error occurs the settings are left unchanged and FALSE is
564       returned; otherwise TRUE is returned.
565
566       See also readListEntry(), readNumEntry(), readDoubleEntry(),
567       readBoolEntry(), and removeEntry().
568

bool QSettings::writeEntry ( const QString & key, const QString & value )

570       This is an overloaded member function, provided for convenience. It
571       behaves essentially like the above function.
572
573       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
578       If an error occurs the settings are left unchanged and FALSE is
579       returned; otherwise TRUE is returned.
580
581       See also readListEntry(), readNumEntry(), readDoubleEntry(),
582       readBoolEntry(), and removeEntry().
583

bool QSettings::writeEntry ( const QString & key, const QStringList & value )

585       This is an overloaded member function, provided for convenience. It
586       behaves essentially like the above function.
587
588       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
591       If an error occurs the settings are left unchanged and FALSE is
592       returned; otherwise returns TRUE.
593
594       See also readListEntry(), readNumEntry(), readDoubleEntry(),
595       readBoolEntry(), and removeEntry().
596

bool QSettings::writeEntry ( const QString & key, const QStringList & value,

598       const QChar & separator )
599       This is an overloaded member function, provided for convenience. It
600       behaves essentially like the above function.
601
602       This function is obsolete. It is provided to keep old source working.
603       We strongly advise against using it in new code.
604
605       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
612       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
620       If an error occurs the settings are left unchanged and FALSE is
621       returned; otherwise returns TRUE.
622
623       See also readListEntry(), readNumEntry(), readDoubleEntry(),
624       readBoolEntry(), removeEntry(), and QStringList::join().
625
626

SEE ALSO

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

AUTHOR

637       Generated automatically from the source code.
638

BUGS

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
644       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
650       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).
653
654
655
656Trolltech AS                    2 February 2007                 QSettings(3qt)
Impressum