]> git.saurik.com Git - wxWidgets.git/blame_incremental - docs/latex/wx/textfile.tex
Documented wxStopWatch and wxToolBar::AddControl().
[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 \helpref{Open}{wxtextfileopen}
21function which opens the file (name may be specified either as Open argument or
22in the constructor), reads its contents in memory and closes it. If all of these
23operations are successful, Open() will return TRUE and FALSE on error.
24\item Work with the lines in the file: this may be done either with "direct
25access" functions like \helpref{GetLineCount}{wxtextfilegetlinecount} and
26\helpref{GetLine}{wxtextfilegetline} ({\it operator[]} does exactly the same
27but looks more like array addressing) or with "sequential access" functions
28which include \helpref{GetFirstLine}{wxtextfilegetfirstline}/
29\helpref{GetNextLine}{wxtextfilegetnextline} and also
30\helpref{GetLastLine}{wxtextfilegetlastline}/\helpref{GetPrevLine}{wxtextfilegetprevline}.
31For the sequential access functions the current line number is maintained: it is
32returned by \helpref{GetCurrentLine}{wxtextfilegetcurrentline} and may be
33changed with \helpref{GoToLine}{wxtextfilegotoline}.
34\item Add/remove lines to the file: \helpref{AddLine}{wxtextfileaddline} and
35\helpref{InsertLine}{wxtextfileinsertline} add new lines while
36\helpref{RemoveLine}{wxtextfileremoveline} deletes the existing ones.
37\item Save your changes: notice that the changes you make to the file will {\bf
38not} be saved automatically; calling \helpref{Close}{wxtextfileclose} or doing
39nothing discards them! To save the changes you must explicitly call
40\helpref{Write}{wxtextfilewrite} - here, you may also change the line
41termination type if you wish.
42\end{itemize}
43
44\wxheading{Derived from}
45
46No base class
47
48\wxheading{Include files}
49
50<wx/textfile.h>
51
52\wxheading{Data structures}
53
54The following constants identify the line termination type:
55\begin{verbatim}
56enum wxTextFileType
57{
58 wxTextFileType_None, // incomplete (the last line of the file only)
59 wxTextFileType_Unix, // line is terminated with 'LF' = 0xA = 10 = '\n'
60 wxTextFileType_Dos, // 'CR' 'LF'
61 wxTextFileType_Mac // 'CR' = 0xD = 13 = '\r'
62};
63\end{verbatim}
64
65\wxheading{See also}
66
67\helpref{wxFile}{wxfile}
68
69\latexignore{\rtfignore{\wxheading{Members}}}
70
71\membersection{wxTextFile::wxTextFile}\label{wxtextfilectordef}
72
73\constfunc{}{wxTextFile}{\void}
74
75Default constructor, use Open(string) to initialize the object.
76
77\membersection{wxTextFile::wxTextFile}\label{wxtextfilector}
78
79\constfunc{}{wxTextFile}{\param{const wxString\& }{strFile}}
80
81Constructor does not load the file into memory, use Open() to do it.
82
83\membersection{wxTextFile::Exists}\label{wxtextfileexists}
84
85\constfunc{bool}{Exists}{\void}
86
87Return TRUE if file exists - the name of the file should have been specified
88in the constructor before calling Exists().
89
90\membersection{wxTextFile::Open}\label{wxtextfileopen}
91
92\constfunc{bool}{Open}{\void}
93
94Open() opens the file with the name which was given in the \helpref{constructor}{wxtextfilector}
95and also loads file in memory on success.
96
97\membersection{wxTextFile::Open}\label{wxtextfileopenname}
98
99\constfunc{bool}{Open}{\param{const wxString\& }{strFile}}
100
101Same as \helpref{Open()}{wxtextfileopen} but allows to specify the file name
102(must be used if the default constructor was used to create the object).
103
104\membersection{wxTextFile::Close}\label{wxtextfileclose}
105
106\constfunc{bool}{Close}{\void}
107
108Closes the file and frees memory, {\bf losing all changes}. Use \helpref{Write()}{wxtextfilewrite}
109if you want to save them.
110
111\membersection{wxTextFile::IsOpened}\label{wxtextfileisopened}
112
113\constfunc{bool}{IsOpened}{\void}
114
115Returns TRUE if the file is currently opened.
116
117\membersection{wxTextFile::GetLineCount}\label{wxtextfilegetlinecount}
118
119\constfunc{size\_t}{GetLineCount}{\void}
120
121Get the number of lines in the file.
122
123\membersection{wxTextFile::GetLine}\label{wxtextfilegetline}
124
125\constfunc{wxString\&}{GetLine}{\param{size\_t }{n}}
126
127Retrieves the line number {\it n} from the file. The returned line may be
128modified but you shouldn't add line terminator at the end - this will be done
129by wxTextFile.
130
131\membersection{wxTextFile::operator[]}\label{wxtextfileoperatorarray}
132
133\constfunc{wxString\&}{operator[]}{\param{size\_t }{n}}
134
135The same as \helpref{GetLine}{wxtextfilegetline}.
136
137\membersection{wxTextFile::GetCurrentLine}\label{wxtextfilegetcurrentline}
138
139\constfunc{size\_t}{GetCurrentLine}{\void}
140
141Returns the current line: it has meaning only when you're using
142GetFirstLine()/GetNextLine() functions, it doesn't get updated when
143you're using "direct access" functions like GetLine(). GetFirstLine() and
144GetLastLine() also change the value of the current line, as well as
145GoToLine().
146
147\membersection{wxTextFile::GoToLine}\label{wxtextfilegotoline}
148
149\constfunc{void}{GoToLine}{\param{size\_t }{n}}
150
151Changes the value returned by \helpref{GetCurrentLine}{wxtextfilegetcurrentline}
152and used by \helpref{GetFirstLine()}{wxtextfilegetfirstline}/\helpref{GetNextLine()}{wxtextfilegetnextline}.
153
154\membersection{wxTextFile::Eof}\label{wxtextfileeof}
155
156\constfunc{bool}{Eof}{\void}
157
158Returns TRUE if the current line is the last one.
159
160\membersection{wxTextFile::GetFirstLine}\label{wxtextfilegetfirstline}
161
162\constfunc{wxString\&}{GetFirstLine}{\void}
163
164This method together with \helpref{GetNextLine()}{wxtextfilegetnextline}
165allows more "iterator-like" traversal of the list of lines, i.e. you may
166write something like:
167
168\begin{verbatim}
169for ( str = GetFirstLine(); !Eof(); str = GetNextLine() )
170{
171 // do something with the current line in str
172}
173\end{verbatim}
174
175\membersection{wxTextFile::GetNextLine}\label{wxtextfilegetnextline}
176
177\func{wxString\&}{GetNextLine}{\void}
178
179Gets the next line (see \helpref{GetFirstLine}{wxtextfilegetfirstline} for
180the example).
181
182\membersection{wxTextFile::GetPrevLine}\label{wxtextfilegetprevline}
183
184\func{wxString\&}{GetPrevLine}{\void}
185
186Gets the previous line in the file.
187
188\membersection{wxTextFile::GetLastLine}\label{wxtextfilegetlastline}
189
190\func{wxString\&}{GetLastLine}{\void}
191
192Gets the last line of the file.
193
194\membersection{wxTextFile::GetLineType}\label{wxtextfilegetlinetype}
195
196\constfunc{wxTextFileType}{GetLineType}{\param{size\_t }{n}}
197
198Get the type of the line (see also \helpref{GetEOL}{wxtextfilegeteol})
199
200\membersection{wxTextFile::GuessType}\label{wxtextfileguesstype}
201
202\constfunc{wxTextFileType}{GuessType}{\void}
203
204Guess the type of file (which is supposed to be opened). If sufficiently
205many lines of the file are in DOS/Unix/Mac format, the corresponding value will
206be returned. If the detection mechanism fails wxTextFileType\_None is returned.
207
208\membersection{wxTextFile::GetName}\label{wxtextfilegetname}
209
210\constfunc{const char*}{GetName}{\void}
211
212Get the name of the file.
213
214\membersection{wxTextFile::AddLine}\label{wxtextfileaddline}
215
216\constfunc{void}{AddLine}{\param{const wxString\& }{str}, \param{wxTextFileType }{type = typeDefault}}
217
218Adds a line to the end of file.
219
220\membersection{wxTextFile::InsertLine}\label{wxtextfileinsertline}
221
222\constfunc{void}{InsertLine}{\param{const wxString\& }{str}, \param{size\_t }{n}, \param{wxTextFileType }{type = typeDefault}}
223
224Insert a line before the line number {\it n}.
225
226\membersection{wxTextFile::RemoveLine}\label{wxtextfileremoveline}
227
228\constfunc{void}{RemoveLine}{\param{size\_t }{n}}
229
230Delete line number {\it n} from the file.
231
232\membersection{wxTextFile::Write}\label{wxtextfilewrite}
233
234\constfunc{bool}{Write}{\param{wxTextFileType }{typeNew = wxTextFileType\_None}}
235
236Change the file on disk. The {\it typeNew} parameter allows you to change the
237file format (default argument means "don't change type") and may be used to
238convert, for example, DOS files to Unix.
239
240Returns TRUE if operation succeeded, FALSE if it failed.
241
242\membersection{wxTextFile::GetEOL}\label{wxtextfilegeteol}
243
244\constfunc{static const char*}{GetEOL}{\param{wxTextFileType }{type = typeDefault}}
245
246Get the line termination string corresponding to given constant. {\it typeDefault} is
247the value defined during the compilation and corresponds to the native format of the
248platform, i.e. it will be wxTextFileType\_Dos under Windows, wxTextFileType\_Unix under
249Unix and wxTextFileType\_Mac under Mac.
250
251\membersection{wxTextFile::\destruct{wxTextFile}}\label{wxtextfiledtor}
252
253\constfunc{}{\destruct{wxTextFile}}{\void}
254
255Destructor does nothing.
256