]>
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 wxUSE_CONFIG or remove fileconf.cpp from your makefile"
31 #endif // wxUSE_CONFIG
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).
105 // we store all lines of the local config file as a linked list in memory
109 void SetNext(LineList
*pNext
) { m_pNext
= pNext
; }
110 void SetPrev(LineList
*pPrev
) { m_pPrev
= pPrev
; }
113 LineList(const wxString
& str
, LineList
*pNext
= (LineList
*) NULL
) : m_strLine(str
)
114 { SetNext(pNext
); SetPrev((LineList
*) NULL
); }
117 LineList
*Next() const { return m_pNext
; }
118 LineList
*Prev() const { return m_pPrev
; }
121 void SetText(const wxString
& str
) { m_strLine
= str
; }
122 const wxString
& Text() const { return m_strLine
; }
125 wxString m_strLine
; // line contents
126 LineList
*m_pNext
, // next node
127 *m_pPrev
; // previous one
130 class wxFileConfig
: public wxConfigBase
133 // construct the "standard" full name for global (system-wide) and
134 // local (user-specific) config files from the base file name.
136 // the following are the filenames returned by this functions:
138 // Unix /etc/file.ext ~/.file
139 // Win %windir%\file.ext %USERPROFILE%\file.ext
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
);
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
159 wxFileConfig(const wxString
& strLocal
, const wxString
& strGlobal
);
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
);
168 // dtor will save unsaved data
169 virtual ~wxFileConfig();
171 // implement inherited pure virtual functions
172 virtual void SetPath(const wxString
& strPath
);
173 virtual const wxString
& GetPath() const { return m_strPath
; }
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;
180 virtual size_t GetNumberOfEntries(bool bRecursive
= FALSE
) const;
181 virtual size_t GetNumberOfGroups(bool bRecursive
= FALSE
) const;
183 virtual bool HasGroup(const wxString
& strName
) const;
184 virtual bool HasEntry(const wxString
& strName
) const;
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;
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
); }
206 virtual bool Write(const wxString
& key
, const wxString
& szValue
);
207 virtual bool Write(const wxString
& key
, long lValue
);
209 virtual bool Flush(bool bCurrentOnly
= FALSE
);
211 virtual bool RenameEntry(const wxString
& oldName
, const wxString
& newName
);
212 virtual bool RenameGroup(const wxString
& oldName
, const wxString
& newName
);
214 virtual bool DeleteEntry(const wxString
& key
, bool bGroupIfEmptyAlso
);
215 virtual bool DeleteGroup(const wxString
& szKey
);
216 virtual bool DeleteAll();
219 // functions to work with this list
220 LineList
*LineListAppend(const wxString
& str
);
221 LineList
*LineListInsert(const wxString
& str
,
222 LineList
*pLine
); // NULL => Prepend()
223 void LineListRemove(LineList
*pLine
);
224 bool LineListIsEmpty();
227 // GetXXXFileName helpers: return ('/' terminated) directory names
228 static wxString
GetGlobalDir();
229 static wxString
GetLocalDir();
231 // common part of all ctors (assumes that m_str{Local|Global}File are already
235 // common part of from dtor and DeleteAll
238 // parse the whole file
239 void Parse(wxTextFile
& file
, bool bLocal
);
241 // the same as SetPath("/")
246 LineList
*m_linesHead
, // head of the linked list
247 *m_linesTail
; // tail
249 wxString m_strLocalFile
, // local file name passed to ctor
250 m_strGlobalFile
; // global
251 wxString m_strPath
; // current path (not '/' terminated)
253 ConfigGroup
*m_pRootGroup
, // the top (unnamed) group
254 *m_pCurrentGroup
; // the current group
257 WX_DEFINE_SORTED_ARRAY(ConfigEntry
*, ArrayEntries
);
258 WX_DEFINE_SORTED_ARRAY(ConfigGroup
*, ArrayGroups
);
264 ConfigGroup
*m_pParent
; // group that contains us
265 wxString m_strName
, // entry name
267 bool m_bDirty
, // changed since last read?
268 m_bImmutable
; // can be overriden locally?
269 int m_nLine
; // used if m_pLine == NULL only
270 LineList
*m_pLine
; // pointer to our line in the linked list
271 // or NULL if it was found in global file
274 ConfigEntry(ConfigGroup
*pParent
, const wxString
& strName
, int nLine
);
277 const wxString
& Name() const { return m_strName
; }
278 const wxString
& Value() const { return m_strValue
; }
279 ConfigGroup
*Group() const { return m_pParent
; }
280 bool IsDirty() const { return m_bDirty
; }
281 bool IsImmutable() const { return m_bImmutable
; }
282 bool IsLocal() const { return m_pLine
!= 0; }
283 int Line() const { return m_nLine
; }
284 LineList
*GetLine() const { return m_pLine
; }
286 // modify entry attributes
287 void SetValue(const wxString
& strValue
, bool bUser
= TRUE
);
289 void SetLine(LineList
*pLine
);
295 wxFileConfig
*m_pConfig
; // config object we belong to
296 ConfigGroup
*m_pParent
; // parent group (NULL for root group)
297 wxFileConfig::ArrayEntries m_aEntries
; // entries in this group
298 wxFileConfig::ArrayGroups m_aSubgroups
; // subgroups
299 wxString m_strName
; // group's name
300 bool m_bDirty
; // if FALSE => all subgroups are not dirty
301 LineList
*m_pLine
; // pointer to our line in the linked list
302 ConfigEntry
*m_pLastEntry
; // last entry/subgroup of this group in the
303 ConfigGroup
*m_pLastGroup
; // local file (we insert new ones after it)
305 // DeleteSubgroupByName helper
306 bool DeleteSubgroup(ConfigGroup
*pGroup
);
310 ConfigGroup(ConfigGroup
*pParent
, const wxString
& strName
, wxFileConfig
*);
312 // dtor deletes all entries and subgroups also
316 const wxString
& Name() const { return m_strName
; }
317 ConfigGroup
*Parent() const { return m_pParent
; }
318 wxFileConfig
*Config() const { return m_pConfig
; }
319 bool IsDirty() const { return m_bDirty
; }
321 const wxFileConfig::ArrayEntries
& Entries() const { return m_aEntries
; }
322 const wxFileConfig::ArrayGroups
& Groups() const { return m_aSubgroups
; }
323 bool IsEmpty() const { return Entries().IsEmpty() && Groups().IsEmpty(); }
325 // find entry/subgroup (NULL if not found)
326 ConfigGroup
*FindSubgroup(const char *szName
) const;
327 ConfigEntry
*FindEntry (const char *szName
) const;
329 // delete entry/subgroup, return FALSE if doesn't exist
330 bool DeleteSubgroupByName(const char *szName
);
331 bool DeleteEntry(const char *szName
);
333 // create new entry/subgroup returning pointer to newly created element
334 ConfigGroup
*AddSubgroup(const wxString
& strName
);
335 ConfigEntry
*AddEntry (const wxString
& strName
, int nLine
= wxNOT_FOUND
);
337 // will also recursively set parent's dirty flag
339 void SetLine(LineList
*pLine
);
341 // rename: no checks are done to ensure that the name is unique!
342 void Rename(const wxString
& newName
);
345 wxString
GetFullName() const;
347 // get the last line belonging to an entry/subgroup of this group
348 LineList
*GetGroupLine(); // line which contains [group]
349 LineList
*GetLastEntryLine(); // after which our subgroups start
350 LineList
*GetLastGroupLine(); // after which the next group starts
352 // called by entries/subgroups when they're created/deleted
353 void SetLastEntry(ConfigEntry
*pEntry
) { m_pLastEntry
= pEntry
; }
354 void SetLastGroup(ConfigGroup
*pGroup
) { m_pLastGroup
= pGroup
; }