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