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