1 /*---------------------------------------------------------------------\
3 | __ __ ____ _____ ____ |
4 | \ \ / /_ _/ ___|_ _|___ \ |
5 | \ V / _` \___ \ | | __) | |
6 | | | (_| |___) || | / __/ |
7 | |_|\__,_|____/ |_| |_____| |
9 | contributed Qt classes |
11 \----------------------------------------------------------------------/
15 Author: Stefan Hundhammer <sh@suse.de>
17 This is a pure Qt class - it can be used independently of YaST2.
25 #include <Qt/qstring.h>
27 #include <Qt3Support/q3dict.h>
28 #include <qstringlist.h>
29 #include <Qt3Support/q3textstream.h>
32 * Utility class that handles program settings in .ini file format:
43 * key3 = _( "message that needs to be translated" )
49 * key=value pairs appear one on a line each. Leading and trailing whitespace
50 * is disregarded around both key and value. Value should be quoted (but
51 * doesn't need to). Quotes in value are escaped with \".
65 * Constructor. Reads settings from the specified file.
67 * Use readError() or readOk() afterwards to check for read errors.
69 QY2Settings( const QString & fileName, AccessMode accessMode=ReadOnly );
74 * Writes any pending changes back to the file if there are any left
75 * if accessMode() is ReadWrite or WriteOnly.
80 * Returns 'true' if the settings couldn't be read from the file specified
83 bool readError() const { return _readError; }
86 * Returns 'true' if the settings were read without problems from the file
87 * specified in the constructor. This is simply the opposite of
90 bool readOk() const { return ! _readError; }
93 * Select the specified section in the settings for subsequent get()
94 * calls. Until is used, the unnamed default section is used.
96 * In the settings file, a section is marked with
100 * Using a null string (QString::null) switches back to the unnamed default
103 * Returns 'true' upon success, 'false' if there is no such section (in
104 * which case the unnamed default section will be selected).
106 bool selectSection( const QString & section );
109 * Select the default (unnamed) section for subsequent get() calls.
110 * This is the default unless selectSection() was called.
112 void selectDefaultSection();
115 * Returns the name of the current section or QString::null if the default
118 QString currentSection() const { return _currentSectionName; }
121 * Returns a list of all sections.
122 * 'includeUnnamed' specifies if the unnamed default section should be
123 * included in the list.
124 * The list sort order is undefined.
126 QStringList sections( bool includeUnnamed = false ) const;
129 * Returns the value for the specified key in the current section.
130 * If there is no such key, the specified fallback value is returned.
132 QString get( const QString & key,
133 const QString & fallback = "") const;
136 * Same as get() with fallback always an empty string
138 QString operator[] ( const QString & key );
141 * Checks if the current section has the specified key.
143 bool hasKey( const QString & key );
146 * Returns a list of all keys in the current section.
147 * The list sort order is undefined.
149 QStringList keys() const;
154 // All write access functions will fail if the current access mode is not
155 // one of ReadWrite / WriteOnly.
159 * Set the specified key to the specified value. Overwrites any existing
160 * key-value pair or adds a new one if there is no such key yet.
162 void set( const QString & key, const QString & value );
165 * Add a section with the specified name. If a section with that name
166 * already exists, it will only be selected and its old contents will
168 * In any case, this section becomes the current section.
170 void addSection( const QString & section );
173 * Clear all key=value pairs from the current section.
178 * Writes changed settings back to the file specified in the constructor if
179 * accessMode() is ReadWrite or WriteOnly.
181 * Returns 'true' on success.
186 * Returns 'true' if there are any changes that need to be written.
188 * Always returns 'false' if accessMode() is ReadOnly.
190 bool pendingChanges() const { return _dirty; }
193 * Returns the file name.
195 QString fileName() const { return _fileName; }
198 * Returns the access mode - one of ReadOnly, ReadWrite, WriteOnly.
200 AccessMode accessMode() const { return _accessMode; }
205 class Section: public QMap<QString, QString>
208 Section( const QString & name )
209 : QMap<QString, QString>()
212 QString name() const { return _name; }
222 * Initialize the section data
227 * Read the settings file. Sets _readError depending on success or failure.
228 * Returns 'true' upon success.
233 * Save one section to a stream
235 void saveSection( Q3TextStream & stream, Section * section );
243 AccessMode _accessMode;
245 QString _currentSectionName;
246 Section * _currentSection;
249 Section * _defaultSection;
250 Q3Dict<Section> _sections;
252 typedef Q3DictIterator<Section> SectionIterator;
255 #endif // QY2Settings_h