]>
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"
20 // ----------------------------------------------------------------------------
22 // ----------------------------------------------------------------------------
24 // it won't compile without it anyhow
26 #error "Please define USE_WXCONFIG or remove fileconf.cpp from your makefile"
27 #endif // USE_WXCONFIG
29 // ----------------------------------------------------------------------------
31 // ----------------------------------------------------------------------------
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
42 # comments are allowed after either ';' or '#' (Win/UNIX standard)
44 # blank lines (as above) are ignored
46 # global entries are members of special (no name) top group
50 # the start of the group 'Foo'
51 [Foo] # may put comments like this also
52 # following 3 lines are entries
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)
58 # subgroup of the group 'Foo'
59 # (order is not important, only the name is: separator is '/', as in paths)
61 # entries prefixed with "!" are immutable, i.e. can't be changed if they are
62 # set in the system-wide config file
66 [Foo/Bar/Fubar] # depth is (theoretically :-) unlimited
67 # may have the same name as key in another section
68 bar_entry = whatever not
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)
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
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
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).
98 class wxFileConfig
: public wxConfigBase
101 // construct the "standard" full name for global (system-wide) and
102 // local (user-specific) config files from the base file name.
104 // the following are the filenames returned by this functions:
106 // Unix /etc/file.ext ~/.file
107 // Win %windir%\file.ext %USERPROFILE%\file.ext
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
);
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
127 wxFileConfig(const wxString
& strLocal
, const wxString
& strGlobal
);
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
= wxEmptyString
,
133 const wxString
& localFilename
= wxEmptyString
, const wxString
& globalFilename
= wxEmptyString
,
134 long style
= wxCONFIG_USE_LOCAL_FILE
);
136 // dtor will save unsaved data
137 virtual ~wxFileConfig();
139 // implement inherited pure virtual functions
140 virtual void SetPath(const wxString
& strPath
);
141 virtual const wxString
& GetPath() const { return m_strPath
; }
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;
148 virtual size_t GetNumberOfEntries(bool bRecursive
= FALSE
) const;
149 virtual size_t GetNumberOfGroups(bool bRecursive
= FALSE
) const;
151 virtual bool HasGroup(const wxString
& strName
) const;
152 virtual bool HasEntry(const wxString
& strName
) const;
155 virtual bool Read(wxString
*pstr
, const char *szKey
,
156 const char *szDefault
= 0) const;
157 virtual const char *Read(const char *szKey
,
158 const char *szDefault
= 0) const;
159 virtual bool Read(long *pl
, const char *szKey
, long lDefault
) const;
160 virtual long Read(const char *szKey
, long lDefault
) const
161 { return wxConfigBase::Read(szKey
, lDefault
); }
162 virtual bool Write(const char *szKey
, const char *szValue
);
163 virtual bool Write(const char *szKey
, long lValue
);
166 virtual bool Read(const wxString
& key
, wxString
*pStr
) const;
167 virtual bool Read(const wxString
& key
, wxString
*pStr
, const wxString
& defValue
) const;
168 virtual bool Read(const wxString
& key
, long *pl
) const;
170 // The following are necessary to satisfy the compiler
171 wxString
Read(const wxString
& key
, const wxString
& defVal
) const
172 { return wxConfigBase::Read(key
, defVal
); }
173 bool Read(const wxString
& key
, long *pl
, long defVal
) const
174 { return wxConfigBase::Read(key
, pl
, defVal
); }
175 long Read(const wxString
& key
, long defVal
) const
176 { return wxConfigBase::Read(key
, defVal
); }
177 bool Read(const wxString
& key
, double* val
) const
178 { return wxConfigBase::Read(key
, val
); }
179 bool Read(const wxString
& key
, double* val
, double defVal
) const
180 { return wxConfigBase::Read(key
, val
, defVal
); }
182 virtual bool Write(const wxString
& key
, const wxString
& szValue
);
183 virtual bool Write(const wxString
& key
, long lValue
);
185 virtual bool Flush(bool bCurrentOnly
= FALSE
);
187 virtual bool DeleteEntry(const wxString
& key
, bool bGroupIfEmptyAlso
);
188 virtual bool DeleteGroup(const wxString
& szKey
);
189 virtual bool DeleteAll();
196 // we store all lines of the local config file as a linked list in memory
201 LineList(const wxString
& str
, LineList
*pNext
= (LineList
*) NULL
) : m_strLine(str
)
202 { SetNext(pNext
); SetPrev((LineList
*) NULL
); }
205 LineList
*Next() const { return m_pNext
; }
206 LineList
*Prev() const { return m_pPrev
; }
207 void SetNext(LineList
*pNext
) { m_pNext
= pNext
; }
208 void SetPrev(LineList
*pPrev
) { m_pPrev
= pPrev
; }
211 void SetText(const wxString
& str
) { m_strLine
= str
; }
212 const wxString
& Text() const { return m_strLine
; }
215 wxString m_strLine
; // line contents
216 LineList
*m_pNext
, // next node
217 *m_pPrev
; // previous one
220 // functions to work with this list
221 LineList
*LineListAppend(const wxString
& str
);
222 LineList
*LineListInsert(const wxString
& str
,
223 LineList
*pLine
); // NULL => Prepend()
224 void LineListRemove(LineList
*pLine
);
225 bool LineListIsEmpty();
228 // GetXXXFileame helpers: return ('/' terminated) directory names
229 static wxString
GetGlobalDir();
230 static wxString
GetLocalDir();
232 // common part of all ctors (assumes that m_str{Local|Global}File are already
236 // common part of from dtor and DeleteAll
239 // parse the whole file
240 void Parse(wxTextFile
& file
, bool bLocal
);
242 // the same as SetPath("/")
247 LineList
*m_linesHead
, // head of the linked list
248 *m_linesTail
; // tail
250 wxString m_strLocalFile
, // local file name passed to ctor
251 m_strGlobalFile
; // global
252 wxString m_strPath
; // current path (not '/' terminated)
254 ConfigGroup
*m_pRootGroup
, // the top (unnamed) group
255 *m_pCurrentGroup
; // the current group
257 //protected: --- if wxFileConfig::ConfigEntry is not public, functions in
258 // ConfigGroup such as Find/AddEntry can't return "ConfigEntry *"
260 WX_DEFINE_SORTED_ARRAY(ConfigEntry
*, ArrayEntries
);
261 WX_DEFINE_SORTED_ARRAY(ConfigGroup
*, ArrayGroups
);
266 ConfigGroup
*m_pParent
; // group that contains us
267 wxString m_strName
, // entry name
269 bool m_bDirty
, // changed since last read?
270 m_bImmutable
; // can be overriden locally?
271 int m_nLine
; // used if m_pLine == NULL only
272 LineList
*m_pLine
; // pointer to our line in the linked list
273 // or NULL if it was found in global file
276 ConfigEntry(ConfigGroup
*pParent
, const wxString
& strName
, int nLine
);
279 const wxString
& Name() const { return m_strName
; }
280 const wxString
& Value() const { return m_strValue
; }
281 ConfigGroup
*Group() const { return m_pParent
; }
282 bool IsDirty() const { return m_bDirty
; }
283 bool IsImmutable() const { return m_bImmutable
; }
284 bool IsLocal() const { return m_pLine
!= 0; }
285 int Line() const { return m_nLine
; }
286 LineList
*GetLine() const { return m_pLine
; }
288 // modify entry attributes
289 void SetValue(const wxString
& strValue
, bool bUser
= TRUE
);
291 void SetLine(LineList
*pLine
);
297 wxFileConfig
*m_pConfig
; // config object we belong to
298 ConfigGroup
*m_pParent
; // parent group (NULL for root group)
299 ArrayEntries m_aEntries
; // entries in this group
300 ArrayGroups m_aSubgroups
; // subgroups
301 wxString m_strName
; // group's name
302 bool m_bDirty
; // if FALSE => all subgroups are not dirty
303 LineList
*m_pLine
; // pointer to our line in the linked list
304 ConfigEntry
*m_pLastEntry
; // last entry/subgroup of this group in the
305 ConfigGroup
*m_pLastGroup
; // local file (we insert new ones after it)
307 // DeleteSubgroupByName helper
308 bool DeleteSubgroup(ConfigGroup
*pGroup
);
312 ConfigGroup(ConfigGroup
*pParent
, const wxString
& strName
, wxFileConfig
*);
314 // dtor deletes all entries and subgroups also
318 const wxString
& Name() const { return m_strName
; }
319 ConfigGroup
*Parent() const { return m_pParent
; }
320 wxFileConfig
*Config() const { return m_pConfig
; }
321 bool IsDirty() const { return m_bDirty
; }
323 bool IsEmpty() const { return Entries().IsEmpty() && Groups().IsEmpty(); }
324 const ArrayEntries
& Entries() const { return m_aEntries
; }
325 const ArrayGroups
& Groups() const { return m_aSubgroups
; }
327 // find entry/subgroup (NULL if not found)
328 ConfigGroup
*FindSubgroup(const char *szName
) const;
329 ConfigEntry
*FindEntry (const char *szName
) const;
331 // delete entry/subgroup, return FALSE if doesn't exist
332 bool DeleteSubgroupByName(const char *szName
);
333 bool DeleteEntry(const char *szName
);
335 // create new entry/subgroup returning pointer to newly created element
336 ConfigGroup
*AddSubgroup(const wxString
& strName
);
337 ConfigEntry
*AddEntry (const wxString
& strName
, int nLine
= NOT_FOUND
);
339 // will also recursively set parent's dirty flag
341 void SetLine(LineList
*pLine
);
344 wxString
GetFullName() const;
346 // get the last line belonging to an entry/subgroup of this group
347 LineList
*GetGroupLine(); // line which contains [group]
348 LineList
*GetLastEntryLine(); // after which our subgroups start
349 LineList
*GetLastGroupLine(); // after which the next group starts
351 // called by entries/subgroups when they're created/deleted
352 void SetLastEntry(ConfigEntry
*pEntry
) { m_pLastEntry
= pEntry
; }
353 void SetLastGroup(ConfigGroup
*pGroup
) { m_pLastGroup
= pGroup
; }