]> git.saurik.com Git - wxWidgets.git/blob - include/wx/fileconf.h
no message
[wxWidgets.git] / include / wx / fileconf.h
1 ///////////////////////////////////////////////////////////////////////////////
2 // Name: fileconf.h
3 // Purpose: wxFileConfig derivation of wxConfigBase
4 // Author: Vadim Zeitlin
5 // Modified by:
6 // Created: 07.04.98 (adapted from appconf.cpp)
7 // RCS-ID: $Id$
8 // Copyright: (c) 1997 Karsten Ballüder & Vadim Zeitlin
9 // Ballueder@usa.net <zeitlin@dptmaths.ens-cachan.fr>
10 // Licence: wxWindows license
11 ///////////////////////////////////////////////////////////////////////////////
12
13 #ifndef _FILECONF_H
14 #define _FILECONF_H
15
16 #ifdef __GNUG__
17 #pragma interface "fileconf.h"
18 #endif
19
20 #include "wx/defs.h"
21
22 #ifdef wxUSE_CONFIG
23
24 #include "wx/confbase.h"
25 #include "wx/textfile.h"
26 #include "wx/string.h"
27
28
29 // ----------------------------------------------------------------------------
30 // wxFileConfig
31 // ----------------------------------------------------------------------------
32
33 /*
34 wxFileConfig derives from base Config and implements file based config class,
35 i.e. it uses ASCII disk files to store the information. These files are
36 alternatively called INI, .conf or .rc in the documentation. They are
37 organized in groups or sections, which can nest (i.e. a group contains
38 subgroups, which contain their own subgroups &c). Each group has some
39 number of entries, which are "key = value" pairs. More precisely, the format
40 is:
41
42 # comments are allowed after either ';' or '#' (Win/UNIX standard)
43
44 # blank lines (as above) are ignored
45
46 # global entries are members of special (no name) top group
47 written_for = Windows
48 platform = Linux
49
50 # the start of the group 'Foo'
51 [Foo] # may put comments like this also
52 # following 3 lines are entries
53 key = value
54 another_key = " strings with spaces in the beginning should be quoted, \
55 otherwise the spaces are lost"
56 last_key = but you don't have to put " normally (nor quote them, like here)
57
58 # subgroup of the group 'Foo'
59 # (order is not important, only the name is: separator is '/', as in paths)
60 [Foo/Bar]
61 # entries prefixed with "!" are immutable, i.e. can't be changed if they are
62 # set in the system-wide config file
63 !special_key = value
64 bar_entry = whatever
65
66 [Foo/Bar/Fubar] # depth is (theoretically :-) unlimited
67 # may have the same name as key in another section
68 bar_entry = whatever not
69
70 You have {read/write/delete}Entry functions (guess what they do) and also
71 setCurrentPath to select current group. enum{Subgroups/Entries} allow you
72 to get all entries in the config file (in the current group). Finally,
73 flush() writes immediately all changed entries to disk (otherwise it would
74 be done automatically in dtor)
75
76 wxFileConfig manages not less than 2 config files for each program: global
77 and local (or system and user if you prefer). Entries are read from both of
78 them and the local entries override the global ones unless the latter is
79 immutable (prefixed with '!') in which case a warning message is generated
80 and local value is ignored. Of course, the changes are always written to local
81 file only.
82
83 The names of these files can be specified in a number of ways. First of all,
84 you can use the standard convention: using the ctor which takes 'strAppName'
85 parameter will probably be sufficient for 90% of cases. If, for whatever
86 reason you wish to use the files with some other names, you can always use the
87 second ctor.
88
89 wxFileConfig also may automatically expand the values of environment variables
90 in the entries it reads: for example, if you have an entry
91 score_file = $HOME/.score
92 a call to Read(&str, "score_file") will return a complete path to .score file
93 unless the expansion was previousle disabled with SetExpandEnvVars(FALSE) call
94 (it's on by default, the current status can be retrieved with
95 IsExpandingEnvVars function).
96 */
97
98 class WXDLLEXPORT wxFileConfig : public wxConfigBase
99 {
100 public:
101 // construct the "standard" full name for global (system-wide) and
102 // local (user-specific) config files from the base file name.
103 //
104 // the following are the filenames returned by this functions:
105 // global local
106 // Unix /etc/file.ext ~/.file
107 // Win %windir%\file.ext %USERPROFILE%\file.ext
108 //
109 // where file is the basename of szFile, ext is it's extension
110 // or .conf (Unix) or .ini (Win) if it has none
111 static wxString GetGlobalFileName(const char *szFile);
112 static wxString GetLocalFileName(const char *szFile);
113
114 // ctor & dtor
115
116 #if 0
117 // the names of local and global (if not disabled) config files are
118 // constructed using Get{Local|Global}FileName functions described above
119 // (szAppName is just the (short) name of your application)
120 wxFileConfig(const char *szAppName, bool bLocalOnly = FALSE);
121 // this ctor allows you to specify custom names for both files (if strGlobal
122 // isn't a full path, it's considered to be relative to the standard
123 // directory, i.e. /etc under Unix and %windir% under Windows, if strLocal
124 // is not an absolute path, it's considered to be relative to the user's
125 // directory). If either of strings is empty, the corresponding file is not
126 // used.
127 wxFileConfig(const wxString& strLocal, const wxString& strGlobal);
128 #endif
129
130 // New constructor: one size fits all. Specify wxCONFIG_USE_LOCAL_FILE
131 // or wxCONFIG_USE_GLOBAL_FILE to say which files should be used.
132 wxFileConfig(const wxString& appName, const wxString& vendorName = "",
133 const wxString& localFilename = "", const wxString& globalFilename = "",
134 long style = wxCONFIG_USE_LOCAL_FILE);
135
136 // dtor will save unsaved data
137 virtual ~wxFileConfig();
138
139 // implement inherited pure virtual functions
140 virtual void SetPath(const wxString& strPath);
141 virtual const wxString& GetPath() const { return m_strPath; }
142
143 virtual bool GetFirstGroup(wxString& str, long& lIndex) const;
144 virtual bool GetNextGroup (wxString& str, long& lIndex) const;
145 virtual bool GetFirstEntry(wxString& str, long& lIndex) const;
146 virtual bool GetNextEntry (wxString& str, long& lIndex) const;
147
148 virtual size_t GetNumberOfEntries(bool bRecursive = FALSE) const;
149 virtual size_t GetNumberOfGroups(bool bRecursive = FALSE) const;
150
151 virtual bool HasGroup(const wxString& strName) const;
152 virtual bool HasEntry(const wxString& strName) const;
153
154 virtual bool Read(const wxString& key, wxString *pStr) const;
155 virtual bool Read(const wxString& key, wxString *pStr, const wxString& defValue) const;
156 virtual bool Read(const wxString& key, long *pl) const;
157
158 // The following are necessary to satisfy the compiler
159 wxString Read(const wxString& key, const wxString& defVal) const
160 { return wxConfigBase::Read(key, defVal); }
161 bool Read(const wxString& key, long *pl, long defVal) const
162 { return wxConfigBase::Read(key, pl, defVal); }
163 long Read(const wxString& key, long defVal) const
164 { return wxConfigBase::Read(key, defVal); }
165 bool Read(const wxString& key, int *pi, int defVal) const
166 { return wxConfigBase::Read(key, pi, defVal); }
167 bool Read(const wxString& key, int *pi) const
168 { return wxConfigBase::Read(key, pi); }
169 bool Read(const wxString& key, double* val) const
170 { return wxConfigBase::Read(key, val); }
171 bool Read(const wxString& key, double* val, double defVal) const
172 { return wxConfigBase::Read(key, val, defVal); }
173
174 virtual bool Write(const wxString& key, const wxString& szValue);
175 virtual bool Write(const wxString& key, long lValue);
176
177 virtual bool Flush(bool bCurrentOnly = FALSE);
178
179 virtual bool DeleteEntry(const wxString& key, bool bGroupIfEmptyAlso);
180 virtual bool DeleteGroup(const wxString& szKey);
181 virtual bool DeleteAll();
182
183 public:
184 // fwd decl
185 class ConfigGroup;
186 class ConfigEntry;
187
188 // we store all lines of the local config file as a linked list in memory
189 class LineList
190 {
191 public:
192 void SetNext(LineList *pNext) { m_pNext = pNext; }
193 void SetPrev(LineList *pPrev) { m_pPrev = pPrev; }
194
195 // ctor
196 LineList(const wxString& str, LineList *pNext = (LineList *) NULL) : m_strLine(str)
197 { SetNext(pNext); SetPrev((LineList *) NULL); }
198
199 //
200 LineList *Next() const { return m_pNext; }
201 LineList *Prev() const { return m_pPrev; }
202
203 //
204 void SetText(const wxString& str) { m_strLine = str; }
205 const wxString& Text() const { return m_strLine; }
206
207 private:
208 wxString m_strLine; // line contents
209 LineList *m_pNext, // next node
210 *m_pPrev; // previous one
211 };
212
213 // functions to work with this list
214 LineList *LineListAppend(const wxString& str);
215 LineList *LineListInsert(const wxString& str,
216 LineList *pLine); // NULL => Prepend()
217 void LineListRemove(LineList *pLine);
218 bool LineListIsEmpty();
219
220 private:
221 // GetXXXFileame helpers: return ('/' terminated) directory names
222 static wxString GetGlobalDir();
223 static wxString GetLocalDir();
224
225 // common part of all ctors (assumes that m_str{Local|Global}File are already
226 // initialized
227 void Init();
228
229 // common part of from dtor and DeleteAll
230 void CleanUp();
231
232 // parse the whole file
233 void Parse(wxTextFile& file, bool bLocal);
234
235 // the same as SetPath("/")
236 void SetRootPath();
237
238 // member variables
239 // ----------------
240 LineList *m_linesHead, // head of the linked list
241 *m_linesTail; // tail
242
243 wxString m_strLocalFile, // local file name passed to ctor
244 m_strGlobalFile; // global
245 wxString m_strPath; // current path (not '/' terminated)
246
247 ConfigGroup *m_pRootGroup, // the top (unnamed) group
248 *m_pCurrentGroup; // the current group
249
250 //protected: --- if wxFileConfig::ConfigEntry is not public, functions in
251 // ConfigGroup such as Find/AddEntry can't return "ConfigEntry *"
252 public:
253 WX_DEFINE_SORTED_ARRAY(ConfigEntry *, ArrayEntries);
254 WX_DEFINE_SORTED_ARRAY(ConfigGroup *, ArrayGroups);
255
256 class ConfigEntry
257 {
258 private:
259 ConfigGroup *m_pParent; // group that contains us
260 wxString m_strName, // entry name
261 m_strValue; // value
262 bool m_bDirty, // changed since last read?
263 m_bImmutable; // can be overriden locally?
264 int m_nLine; // used if m_pLine == NULL only
265 LineList *m_pLine; // pointer to our line in the linked list
266 // or NULL if it was found in global file
267
268 public:
269 ConfigEntry(ConfigGroup *pParent, const wxString& strName, int nLine);
270
271 // simple accessors
272 const wxString& Name() const { return m_strName; }
273 const wxString& Value() const { return m_strValue; }
274 ConfigGroup *Group() const { return m_pParent; }
275 bool IsDirty() const { return m_bDirty; }
276 bool IsImmutable() const { return m_bImmutable; }
277 bool IsLocal() const { return m_pLine != 0; }
278 int Line() const { return m_nLine; }
279 LineList *GetLine() const { return m_pLine; }
280
281 // modify entry attributes
282 void SetValue(const wxString& strValue, bool bUser = TRUE);
283 void SetDirty();
284 void SetLine(LineList *pLine);
285 };
286
287 class ConfigGroup
288 {
289 private:
290 wxFileConfig *m_pConfig; // config object we belong to
291 ConfigGroup *m_pParent; // parent group (NULL for root group)
292 ArrayEntries m_aEntries; // entries in this group
293 ArrayGroups m_aSubgroups; // subgroups
294 wxString m_strName; // group's name
295 bool m_bDirty; // if FALSE => all subgroups are not dirty
296 LineList *m_pLine; // pointer to our line in the linked list
297 ConfigEntry *m_pLastEntry; // last entry/subgroup of this group in the
298 ConfigGroup *m_pLastGroup; // local file (we insert new ones after it)
299
300 // DeleteSubgroupByName helper
301 bool DeleteSubgroup(ConfigGroup *pGroup);
302
303 public:
304 // ctor
305 ConfigGroup(ConfigGroup *pParent, const wxString& strName, wxFileConfig *);
306
307 // dtor deletes all entries and subgroups also
308 ~ConfigGroup();
309
310 // simple accessors
311 const wxString& Name() const { return m_strName; }
312 ConfigGroup *Parent() const { return m_pParent; }
313 wxFileConfig *Config() const { return m_pConfig; }
314 bool IsDirty() const { return m_bDirty; }
315
316 const ArrayEntries& Entries() const { return m_aEntries; }
317 const ArrayGroups& Groups() const { return m_aSubgroups; }
318 bool IsEmpty() const { return Entries().IsEmpty() && Groups().IsEmpty(); }
319
320 // find entry/subgroup (NULL if not found)
321 ConfigGroup *FindSubgroup(const char *szName) const;
322 ConfigEntry *FindEntry (const char *szName) const;
323
324 // delete entry/subgroup, return FALSE if doesn't exist
325 bool DeleteSubgroupByName(const char *szName);
326 bool DeleteEntry(const char *szName);
327
328 // create new entry/subgroup returning pointer to newly created element
329 ConfigGroup *AddSubgroup(const wxString& strName);
330 ConfigEntry *AddEntry (const wxString& strName, int nLine = NOT_FOUND);
331
332 // will also recursively set parent's dirty flag
333 void SetDirty();
334 void SetLine(LineList *pLine);
335
336 //
337 wxString GetFullName() const;
338
339 // get the last line belonging to an entry/subgroup of this group
340 LineList *GetGroupLine(); // line which contains [group]
341 LineList *GetLastEntryLine(); // after which our subgroups start
342 LineList *GetLastGroupLine(); // after which the next group starts
343
344 // called by entries/subgroups when they're created/deleted
345 void SetLastEntry(ConfigEntry *pEntry) { m_pLastEntry = pEntry; }
346 void SetLastGroup(ConfigGroup *pGroup) { m_pLastGroup = pGroup; }
347 };
348 };
349
350 #endif
351 // wxUSE_CONFIG
352
353 #endif
354 //_FILECONF_H
355