]> git.saurik.com Git - wxWidgets.git/blame - interface/wx/textfile.h
make wxRearrangeDialog more customizable and add an example of customizing it to...
[wxWidgets.git] / interface / wx / textfile.h
CommitLineData
23324ae1
FM
1/////////////////////////////////////////////////////////////////////////////
2// Name: textfile.h
e54c96f1 3// Purpose: interface of wxTextFile
23324ae1
FM
4// Author: wxWidgets team
5// RCS-ID: $Id$
6// Licence: wxWindows license
7/////////////////////////////////////////////////////////////////////////////
8
c6cf894a 9
59b9603a
FM
10/**
11 The line termination type (kept wxTextFileType name for compability).
12*/
c6cf894a
FM
13enum wxTextFileType
14{
15 wxTextFileType_None, //!< incomplete (the last line of the file only)
4876436a 16 wxTextFileType_Unix, //!< line is terminated with 'LF' = 0xA = 10 = '\\n'
c6cf894a 17 wxTextFileType_Dos, //!< line is terminated with 'CR' 'LF'
4876436a 18 wxTextFileType_Mac, //!< line is terminated with 'CR' = 0xD = 13 = '\\r'
c6cf894a
FM
19 wxTextFileType_Os2 //!< line is terminated with 'CR' 'LF'
20};
21
23324ae1
FM
22/**
23 @class wxTextFile
7c913512 24
23324ae1
FM
25 The wxTextFile is a simple class which allows to work with text files on line by
26 line basis. It also understands the differences in line termination characters
27 under different platforms and will not do anything bad to files with "non
28 native" line termination sequences - in fact, it can be also used to modify the
29 text files and change the line termination characters from one type (say DOS) to
30 another (say Unix).
7c913512 31
23324ae1
FM
32 One word of warning: the class is not at all optimized for big files and thus
33 it will load the file entirely into memory when opened. Of course, you should
c6cf894a
FM
34 not work in this way with large files (as an estimation, anything over 1 Megabyte
35 is surely too big for this class). On the other hand, it is not a serious
23324ae1
FM
36 limitation for small files like configuration files or program sources
37 which are well handled by wxTextFile.
7c913512 38
23324ae1 39 The typical things you may do with wxTextFile in order are:
7c913512 40
c6cf894a
FM
41 - Create and open it: this is done with either wxTextFile::Create or wxTextFile::Open
42 function which opens the file (name may be specified either as the argument to
43 these functions or in the constructor), reads its contents in memory (in the
59b9603a 44 case of wxTextFile::Open()) and closes it.
c6cf894a
FM
45 - Work with the lines in the file: this may be done either with "direct
46 access" functions like wxTextFile::GetLineCount and wxTextFile::GetLine
47 (@e operator[] does exactly the same but looks more like array addressing)
48 or with "sequential access" functions which include wxTextFile::GetFirstLine,
49 wxTextFile::GetNextLine and also wxTextFile::GetLastLine, wxTextFile::GetPrevLine.
50 For the sequential access functions the current line number is maintained: it is
51 returned by wxTextFile::GetCurrentLine and may be changed with wxTextFile::GoToLine.
52 - Add/remove lines to the file: wxTextFile::AddLine and wxTextFile::InsertLine
53 add new lines while wxTextFile::RemoveLine deletes the existing ones.
54 wxTextFile::Clear resets the file to empty.
55 - Save your changes: notice that the changes you make to the file will @b not be
56 saved automatically; calling wxTextFile::Close or doing nothing discards them!
57 To save the changes you must explicitly callwxTextFile::Write - here, you may
58 also change the line termination type if you wish.
7c913512
FM
59
60
23324ae1
FM
61 @library{wxbase}
62 @category{file}
7c913512 63
e54c96f1 64 @see wxFile
23324ae1 65*/
7c913512 66class wxTextFile
23324ae1
FM
67{
68public:
c6cf894a
FM
69 /**
70 Default constructor, use Create() or Open() with a file name parameter to
71 initialize the object.
72 */
73 wxTextFile();
74
23324ae1
FM
75 /**
76 Constructor does not load the file into memory, use Open() to do it.
77 */
adaaa686 78 wxTextFile(const wxString& strFile);
23324ae1
FM
79
80 /**
81 Destructor does nothing.
82 */
adaaa686 83 virtual ~wxTextFile();
23324ae1
FM
84
85 /**
86 Adds a line to the end of file.
87 */
88 void AddLine(const wxString& str,
43c48e1e 89 wxTextFileType type = wxTextBuffer::typeDefault);
23324ae1
FM
90
91 /**
92 Delete all lines from the file, set current line number to 0.
93 */
0004982c 94 void Clear();
23324ae1
FM
95
96 /**
c6cf894a
FM
97 Closes the file and frees memory, @b "losing all changes".
98 Use Write() if you want to save them.
23324ae1 99 */
0004982c 100 bool Close();
23324ae1 101
23324ae1 102 /**
e2c4ccaf
FM
103 Creates the file with the name which was given in the
104 wxTextFile(const wxString&) constructor.
105 The array of file lines is initially empty.
c6cf894a
FM
106
107 It will fail if the file already exists, Open() should be used in this case.
23324ae1 108 */
328f5751 109 bool Create() const;
e2c4ccaf
FM
110
111 /**
112 Creates the file with the given name.
113 The array of file lines is initially empty.
114
115 It will fail if the file already exists, Open() should be used in this case.
116 */
c6cf894a 117 bool Create(const wxString& strFile) const;
23324ae1
FM
118
119 /**
120 Returns @true if the current line is the last one.
121 */
328f5751 122 bool Eof() const;
23324ae1
FM
123
124 /**
125 Return @true if file exists - the name of the file should have been specified
126 in the constructor before calling Exists().
127 */
328f5751 128 bool Exists() const;
23324ae1
FM
129
130 /**
131 Returns the current line: it has meaning only when you're using
132 GetFirstLine()/GetNextLine() functions, it doesn't get updated when
c6cf894a
FM
133 you're using "direct access" functions like GetLine().
134 GetFirstLine() and GetLastLine() also change the value of the current line,
135 as well as GoToLine().
23324ae1 136 */
328f5751 137 size_t GetCurrentLine() const;
23324ae1
FM
138
139 /**
c6cf894a
FM
140 Get the line termination string corresponding to given constant.
141
142 @e typeDefault is the value defined during the compilation and corresponds
143 to the native format of the platform, i.e. it will be @c wxTextFileType_Dos
144 under Windows, @c wxTextFileType_Unix under Unix (including Mac OS X when
145 compiling with the Apple Developer Tools) and @c wxTextFileType_Mac under
146 Mac OS (including Mac OS X when compiling with CodeWarrior).
23324ae1 147 */
328f5751 148 static const char* GetEOL(wxTextFileType type = typeDefault) const;
23324ae1
FM
149
150 /**
c6cf894a
FM
151 This method together with GetNextLine() allows more "iterator-like"
152 traversal of the list of lines, i.e. you may write something like:
153
154 @code
155 wxTextFile file;
156 ...
157 for ( str = file.GetFirstLine(); !file.Eof(); str = file.GetNextLine() )
158 {
159 // do something with the current line in str
160 }
161 // do something with the last line in str
162 @endcode
23324ae1 163 */
43c48e1e 164 wxString& GetFirstLine();
23324ae1
FM
165
166 /**
c6cf894a
FM
167 Gets the last line of the file.
168
169 Together with GetPrevLine() it allows to enumerate the lines
23324ae1 170 in the file from the end to the beginning like this:
c6cf894a
FM
171
172 @code
173 wxTextFile file;
174 ...
175 for ( str = file.GetLastLine();
176 file.GetCurrentLine() > 0;
177 str = file.GetPrevLine() )
178 {
179 // do something with the current line in str
180 }
181 // do something with the first line in str
182 @endcode
23324ae1 183 */
43c48e1e 184 wxString& GetLastLine();
23324ae1
FM
185
186 /**
c6cf894a
FM
187 Retrieves the line number @a n from the file.
188
189 The returned line may be modified but you shouldn't add line terminator
190 at the end - this will be done by wxTextFile.
23324ae1 191 */
43c48e1e 192 wxString& GetLine(size_t n) const;
23324ae1
FM
193
194 /**
195 Get the number of lines in the file.
196 */
328f5751 197 size_t GetLineCount() const;
23324ae1
FM
198
199 /**
c6cf894a 200 Get the type of the line (see also wxTextFile::GetEOL).
23324ae1 201 */
328f5751 202 wxTextFileType GetLineType(size_t n) const;
23324ae1
FM
203
204 /**
205 Get the name of the file.
206 */
43c48e1e 207 const wxString& GetName() const;
23324ae1
FM
208
209 /**
c6cf894a 210 Gets the next line (see GetFirstLine() for the example).
23324ae1 211 */
43c48e1e 212 wxString& GetNextLine();
23324ae1
FM
213
214 /**
215 Gets the previous line in the file.
216 */
43c48e1e 217 wxString& GetPrevLine();
23324ae1
FM
218
219 /**
c6cf894a
FM
220 Changes the value returned by GetCurrentLine() and used by GetFirstLine()
221 and GetNextLine().
23324ae1 222 */
0004982c 223 void GoToLine(size_t n);
23324ae1
FM
224
225 /**
c6cf894a
FM
226 Guess the type of file (which is supposed to be opened).
227
228 If sufficiently many lines of the file are in DOS/Unix/Mac format,
229 the corresponding value will be returned.
230 If the detection mechanism fails @c wxTextFileType_None is returned.
23324ae1 231 */
328f5751 232 wxTextFileType GuessType() const;
23324ae1
FM
233
234 /**
c6cf894a 235 Insert a line before the line number @a n.
23324ae1
FM
236 */
237 void InsertLine(const wxString& str, size_t n,
43c48e1e 238 wxTextFileType type = wxTextBuffer::typeDefault);
23324ae1
FM
239
240 /**
241 Returns @true if the file is currently opened.
242 */
328f5751 243 bool IsOpened() const;
23324ae1
FM
244
245 //@{
246 /**
23324ae1 247 Open() opens the file with the given name or the name which was given in the
e2c4ccaf 248 wxTextFile(const wxString&) constructor and also loads file in memory on success.
c6cf894a
FM
249
250 It will fail if the file does not exist, Create() should be used in this case.
251
252 The @a conv argument is only meaningful in Unicode build of wxWidgets when
23324ae1
FM
253 it is used to convert the file to wide character representation.
254 */
c6cf894a
FM
255 bool Open(const wxMBConv& conv = wxConvAuto()) const;
256 bool Open(const wxString& strFile, const wxMBConv& conv = wxConvAuto()) const;
23324ae1
FM
257 //@}
258
259 /**
4cc4bfaf 260 Delete line number @a n from the file.
23324ae1 261 */
0004982c 262 void RemoveLine(size_t n);
23324ae1
FM
263
264 /**
c6cf894a
FM
265 Change the file on disk.
266
267 The @a typeNew parameter allows you to change the file format
268 (default argument means "don't change type") and may be used to convert,
269 for example, DOS files to Unix.
270
271 The @a conv argument is only meaningful in Unicode build of wxWidgets when
4876436a 272 it is used to convert all lines to multibyte representation before writing
23324ae1 273 them to physical file.
c6cf894a
FM
274
275 @return
276 @true if operation succeeded, @false if it failed.
23324ae1 277 */
c6cf894a 278 bool Write(wxTextFileType typeNew = wxTextFileType_None,
fadc2df6 279 const wxMBConv& conv = wxConvAuto());
23324ae1
FM
280
281 /**
282 The same as GetLine().
283 */
43c48e1e 284 wxString& operator[](size_t n) const;
23324ae1 285};
e54c96f1 286