]>
git.saurik.com Git - wxWidgets.git/blob - include/wx/fileconf.h
1 ///////////////////////////////////////////////////////////////////////////////
3 // Purpose: wxFileConfig derivation of wxConfigBase
4 // Author: Vadim Zeitlin
6 // Created: 07.04.98 (adapted from appconf.cpp)
8 // Copyright: (c) 1997 Karsten Ballüder & Vadim Zeitlin
9 // Ballueder@usa.net <zeitlin@dptmaths.ens-cachan.fr>
10 // Licence: wxWindows license
11 ///////////////////////////////////////////////////////////////////////////////
17 #pragma interface "fileconf.h"
21 #include "wx/textfile.h"
22 #include "wx/string.h"
24 // ----------------------------------------------------------------------------
26 // ----------------------------------------------------------------------------
28 // it won't compile without it anyhow
30 #error "Please define USE_CONFIG or remove fileconf.cpp from your makefile"
33 // ----------------------------------------------------------------------------
35 // ----------------------------------------------------------------------------
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
46 # comments are allowed after either ';' or '#' (Win/UNIX standard)
48 # blank lines (as above) are ignored
50 # global entries are members of special (no name) top group
54 # the start of the group 'Foo'
55 [Foo] # may put comments like this also
56 # following 3 lines are entries
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)
62 # subgroup of the group 'Foo'
63 # (order is not important, only the name is: separator is '/', as in paths)
65 # entries prefixed with "!" are immutable, i.e. can't be changed if they are
66 # set in the system-wide config file
70 [Foo/Bar/Fubar] # depth is (theoretically :-) unlimited
71 # may have the same name as key in another section
72 bar_entry = whatever not
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)
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
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
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).
102 class wxFileConfig
: public wxConfigBase
105 // construct the "standard" full name for global (system-wide) and
106 // local (user-specific) config files from the base file name.
108 // the following are the filenames returned by this functions:
110 // Unix /etc/file.ext ~/.file
111 // Win %windir%\file.ext %USERPROFILE%\file.ext
113 // where file is the basename of szFile, ext is it's extension
114 // or .conf (Unix) or .ini (Win) if it has none
115 static wxString
GetGlobalFileName(const char *szFile
);
116 static wxString
GetLocalFileName(const char *szFile
);
121 // the names of local and global (if not disabled) config files are
122 // constructed using Get{Local|Global}FileName functions described above
123 // (szAppName is just the (short) name of your application)
124 wxFileConfig(const char *szAppName
, bool bLocalOnly
= FALSE
);
125 // this ctor allows you to specify custom names for both files (if strGlobal
126 // isn't a full path, it's considered to be relative to the standard
127 // directory, i.e. /etc under Unix and %windir% under Windows, if strLocal
128 // is not an absolute path, it's considered to be relative to the user's
129 // directory). If either of strings is empty, the corresponding file is not
131 wxFileConfig(const wxString
& strLocal
, const wxString
& strGlobal
);
134 // New constructor: one size fits all. Specify wxCONFIG_USE_LOCAL_FILE
135 // or wxCONFIG_USE_GLOBAL_FILE to say which files should be used.
136 wxFileConfig(const wxString
& appName
, const wxString
& vendorName
= wxEmptyString
,
137 const wxString
& localFilename
= wxEmptyString
, const wxString
& globalFilename
= wxEmptyString
,
138 long style
= wxCONFIG_USE_LOCAL_FILE
);
140 // dtor will save unsaved data
141 virtual ~wxFileConfig();
143 // implement inherited pure virtual functions
144 virtual void SetPath(const wxString
& strPath
);
145 virtual const wxString
& GetPath() const { return m_strPath
; }
147 virtual bool GetFirstGroup(wxString
& str
, long& lIndex
) const;
148 virtual bool GetNextGroup (wxString
& str
, long& lIndex
) const;
149 virtual bool GetFirstEntry(wxString
& str
, long& lIndex
) const;
150 virtual bool GetNextEntry (wxString
& str
, long& lIndex
) const;
152 virtual size_t GetNumberOfEntries(bool bRecursive
= FALSE
) const;
153 virtual size_t GetNumberOfGroups(bool bRecursive
= FALSE
) const;
155 virtual bool HasGroup(const wxString
& strName
) const;
156 virtual bool HasEntry(const wxString
& strName
) const;
159 virtual bool Read(wxString
*pstr
, const char *szKey
,
160 const char *szDefault
= 0) const;
161 virtual const char *Read(const char *szKey
,
162 const char *szDefault
= 0) const;
163 virtual bool Read(long *pl
, const char *szKey
, long lDefault
) const;
164 virtual long Read(const char *szKey
, long lDefault
) const
165 { return wxConfigBase::Read(szKey
, lDefault
); }
166 virtual bool Write(const char *szKey
, const char *szValue
);
167 virtual bool Write(const char *szKey
, long lValue
);
170 virtual bool Read(const wxString
& key
, wxString
*pStr
) const;
171 virtual bool Read(const wxString
& key
, wxString
*pStr
, const wxString
& defValue
) const;
172 virtual bool Read(const wxString
& key
, long *pl
) const;
174 // The following are necessary to satisfy the compiler
175 wxString
Read(const wxString
& key
, const wxString
& defVal
) const
176 { return wxConfigBase::Read(key
, defVal
); }
177 bool Read(const wxString
& key
, long *pl
, long defVal
) const
178 { return wxConfigBase::Read(key
, pl
, defVal
); }
179 long Read(const wxString
& key
, long defVal
) const
180 { return wxConfigBase::Read(key
, defVal
); }
181 bool Read(const wxString
& key
, double* val
) const
182 { return wxConfigBase::Read(key
, val
); }
183 bool Read(const wxString
& key
, double* val
, double defVal
) const
184 { return wxConfigBase::Read(key
, val
, defVal
); }
186 virtual bool Write(const wxString
& key
, const wxString
& szValue
);
187 virtual bool Write(const wxString
& key
, long lValue
);
189 virtual bool Flush(bool bCurrentOnly
= FALSE
);
191 virtual bool DeleteEntry(const wxString
& key
, bool bGroupIfEmptyAlso
);
192 virtual bool DeleteGroup(const wxString
& szKey
);
193 virtual bool DeleteAll();
200 // we store all lines of the local config file as a linked list in memory
205 LineList(const wxString
& str
, LineList
*pNext
= (LineList
*) NULL
) : m_strLine(str
)
206 { SetNext(pNext
); SetPrev((LineList
*) NULL
); }
209 LineList
*Next() const { return m_pNext
; }
210 LineList
*Prev() const { return m_pPrev
; }
211 void SetNext(LineList
*pNext
) { m_pNext
= pNext
; }
212 void SetPrev(LineList
*pPrev
) { m_pPrev
= pPrev
; }
215 void SetText(const wxString
& str
) { m_strLine
= str
; }
216 const wxString
& Text() const { return m_strLine
; }
219 wxString m_strLine
; // line contents
220 LineList
*m_pNext
, // next node
221 *m_pPrev
; // previous one
224 // functions to work with this list
225 LineList
*LineListAppend(const wxString
& str
);
226 LineList
*LineListInsert(const wxString
& str
,
227 LineList
*pLine
); // NULL => Prepend()
228 void LineListRemove(LineList
*pLine
);
229 bool LineListIsEmpty();
232 // GetXXXFileame helpers: return ('/' terminated) directory names
233 static wxString
GetGlobalDir();
234 static wxString
GetLocalDir();
236 // common part of all ctors (assumes that m_str{Local|Global}File are already
240 // common part of from dtor and DeleteAll
243 // parse the whole file
244 void Parse(wxTextFile
& file
, bool bLocal
);
246 // the same as SetPath("/")
251 LineList
*m_linesHead
, // head of the linked list
252 *m_linesTail
; // tail
254 wxString m_strLocalFile
, // local file name passed to ctor
255 m_strGlobalFile
; // global
256 wxString m_strPath
; // current path (not '/' terminated)
258 ConfigGroup
*m_pRootGroup
, // the top (unnamed) group
259 *m_pCurrentGroup
; // the current group
261 //protected: --- if wxFileConfig::ConfigEntry is not public, functions in
262 // ConfigGroup such as Find/AddEntry can't return "ConfigEntry *"
264 WX_DEFINE_SORTED_ARRAY(ConfigEntry
*, ArrayEntries
);
265 WX_DEFINE_SORTED_ARRAY(ConfigGroup
*, ArrayGroups
);
270 ConfigGroup
*m_pParent
; // group that contains us
271 wxString m_strName
, // entry name
273 bool m_bDirty
, // changed since last read?
274 m_bImmutable
; // can be overriden locally?
275 int m_nLine
; // used if m_pLine == NULL only
276 LineList
*m_pLine
; // pointer to our line in the linked list
277 // or NULL if it was found in global file
280 ConfigEntry(ConfigGroup
*pParent
, const wxString
& strName
, int nLine
);
283 const wxString
& Name() const { return m_strName
; }
284 const wxString
& Value() const { return m_strValue
; }
285 ConfigGroup
*Group() const { return m_pParent
; }
286 bool IsDirty() const { return m_bDirty
; }
287 bool IsImmutable() const { return m_bImmutable
; }
288 bool IsLocal() const { return m_pLine
!= 0; }
289 int Line() const { return m_nLine
; }
290 LineList
*GetLine() const { return m_pLine
; }
292 // modify entry attributes
293 void SetValue(const wxString
& strValue
, bool bUser
= TRUE
);
295 void SetLine(LineList
*pLine
);
301 wxFileConfig
*m_pConfig
; // config object we belong to
302 ConfigGroup
*m_pParent
; // parent group (NULL for root group)
303 ArrayEntries m_aEntries
; // entries in this group
304 ArrayGroups m_aSubgroups
; // subgroups
305 wxString m_strName
; // group's name
306 bool m_bDirty
; // if FALSE => all subgroups are not dirty
307 LineList
*m_pLine
; // pointer to our line in the linked list
308 ConfigEntry
*m_pLastEntry
; // last entry/subgroup of this group in the
309 ConfigGroup
*m_pLastGroup
; // local file (we insert new ones after it)
311 // DeleteSubgroupByName helper
312 bool DeleteSubgroup(ConfigGroup
*pGroup
);
316 ConfigGroup(ConfigGroup
*pParent
, const wxString
& strName
, wxFileConfig
*);
318 // dtor deletes all entries and subgroups also
322 const wxString
& Name() const { return m_strName
; }
323 ConfigGroup
*Parent() const { return m_pParent
; }
324 wxFileConfig
*Config() const { return m_pConfig
; }
325 bool IsDirty() const { return m_bDirty
; }
327 bool IsEmpty() const { return Entries().IsEmpty() && Groups().IsEmpty(); }
328 const ArrayEntries
& Entries() const { return m_aEntries
; }
329 const ArrayGroups
& Groups() const { return m_aSubgroups
; }
331 // find entry/subgroup (NULL if not found)
332 ConfigGroup
*FindSubgroup(const char *szName
) const;
333 ConfigEntry
*FindEntry (const char *szName
) const;
335 // delete entry/subgroup, return FALSE if doesn't exist
336 bool DeleteSubgroupByName(const char *szName
);
337 bool DeleteEntry(const char *szName
);
339 // create new entry/subgroup returning pointer to newly created element
340 ConfigGroup
*AddSubgroup(const wxString
& strName
);
341 ConfigEntry
*AddEntry (const wxString
& strName
, int nLine
= NOT_FOUND
);
343 // will also recursively set parent's dirty flag
345 void SetLine(LineList
*pLine
);
348 wxString
GetFullName() const;
350 // get the last line belonging to an entry/subgroup of this group
351 LineList
*GetGroupLine(); // line which contains [group]
352 LineList
*GetLastEntryLine(); // after which our subgroups start
353 LineList
*GetLastGroupLine(); // after which the next group starts
355 // called by entries/subgroups when they're created/deleted
356 void SetLastEntry(ConfigEntry
*pEntry
) { m_pLastEntry
= pEntry
; }
357 void SetLastGroup(ConfigGroup
*pGroup
) { m_pLastGroup
= pGroup
; }