]> git.saurik.com Git - wxWidgets.git/blame_incremental - docs/latex/wx/ffile.tex
Fixed to work with the new wxMacControl system.
[wxWidgets.git] / docs / latex / wx / ffile.tex
... / ...
CommitLineData
1%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
2%% Name: ffile.tex
3%% Purpose: wxFFile documentation
4%% Author: Vadim Zeitlin
5%% Modified by:
6%% Created: 14.01.02 (extracted from file.tex)
7%% RCS-ID: $Id$
8%% Copyright: (c) Vadim Zeitlin
9%% License: wxWidgets license
10%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
11
12\section{\class{wxFFile}}\label{wxffile}
13
14wxFFile implements buffered file I/O. This is a very small class designed to
15minimize the overhead of using it - in fact, there is hardly any overhead at
16all, but using it brings you automatic error checking and hides differences
17between platforms and compilers. It wraps inside it a {\tt FILE *} handle used
18by standard C IO library (also known as {\tt stdio}).
19
20\wxheading{Derived from}
21
22None.
23
24\wxheading{Include files}
25
26<wx/ffile.h>
27
28\twocolwidtha{7cm}
29\begin{twocollist}\itemsep=0pt%
30\twocolitem{{\bf wxFromStart}}{Count offset from the start of the file}
31\twocolitem{{\bf wxFromCurrent}}{Count offset from the current position of the file pointer}
32\twocolitem{{\bf wxFromEnd}}{Count offset from the end of the file (backwards)}
33\end{twocollist}
34
35\latexignore{\rtfignore{\wxheading{Members}}}
36
37
38\membersection{wxFFile::wxFFile}\label{wxffileconstr}
39
40\func{}{wxFFile}{\void}
41
42Default constructor.
43
44\func{}{wxFFile}{\param{const char*}{ filename}, \param{const char*}{ mode = "r"}}
45
46Opens a file with the given mode. As there is no way to return whether the
47operation was successful or not from the constructor you should test the
48return value of \helpref{IsOpened}{wxffileisopened} to check that it didn't
49fail.
50
51\func{}{wxFFile}{\param{FILE*}{ fp}}
52
53Opens a file with the given file pointer, which has already been opened.
54
55\wxheading{Parameters}
56
57\docparam{filename}{The filename.}
58
59\docparam{mode}{The mode in which to open the file using standard C strings.
60Note that you should use {\tt "b"} flag if you use binary files under Windows
61or the results might be unexpected due to automatic newline conversion done
62for the text files.}
63
64\docparam{fp}{An existing file descriptor, such as stderr.}
65
66
67\membersection{wxFFile::\destruct{wxFFile}}
68
69\func{}{\destruct{wxFFile}}{\void}
70
71Destructor will close the file.
72
73NB: it is not virtual so you should {\it not} derive from wxFFile!
74
75
76\membersection{wxFFile::Attach}\label{wxffileattach}
77
78\func{void}{Attach}{\param{FILE*}{ fp}}
79
80Attaches an existing file pointer to the wxFFile object.
81
82The descriptor should be already opened and it will be closed by wxFFile
83object.
84
85
86\membersection{wxFFile::Close}\label{wxffileclose}
87
88\func{bool}{Close}{\void}
89
90Closes the file and returns \true on success.
91
92
93\membersection{wxFFile::Detach}\label{wxffiledetach}
94
95\func{void}{Detach}{\void}
96
97Get back a file pointer from wxFFile object -- the caller is responsible for closing the file if this
98descriptor is opened. \helpref{IsOpened()}{wxffileisopened} will return \false after call to Detach().
99
100
101\membersection{wxFFile::fp}\label{wxffilefp}
102
103\constfunc{FILE *}{fp}{\void}
104
105Returns the file pointer associated with the file.
106
107
108\membersection{wxFFile::Eof}\label{wxffileeof}
109
110\constfunc{bool}{Eof}{\void}
111
112Returns \true if the an attempt has been made to read {\it past}
113the end of the file.
114
115Note that the behaviour of the file descriptor based class
116\helpref{wxFile}{wxfile} is different as \helpref{wxFile::Eof}{wxfileeof}
117will return \true here as soon as the last byte of the file has been
118read.
119
120Also note that this method may only be called for opened files and may crash if
121the file is not opened.
122
123\wxheading{See also}
124
125\helpref{IsOpened}{wxffileisopened}
126
127
128\membersection{wxFFile::Error}\label{wxffileerror}
129
130Returns \true if an error has occured on this file, similar to the standard
131\texttt{ferror()} function.
132
133Please note that this method may only be called for opened files and may crash
134if the file is not opened.
135
136\wxheading{See also}
137
138\helpref{IsOpened}{wxffileisopened}
139
140
141\membersection{wxFFile::Flush}\label{wxffileflush}
142
143\func{bool}{Flush}{\void}
144
145Flushes the file and returns \true on success.
146
147
148\membersection{wxFFile::IsOpened}\label{wxffileisopened}
149
150\constfunc{bool}{IsOpened}{\void}
151
152Returns \true if the file is opened. Most of the methods of this class may only
153be used for an opened file.
154
155
156\membersection{wxFFile::Length}\label{wxffilelength}
157
158\constfunc{size\_t}{Length}{\void}
159
160Returns the length of the file.
161
162
163\membersection{wxFFile::Open}\label{wxffileopen}
164
165\func{bool}{Open}{\param{const char*}{ filename}, \param{const char*}{ mode = "r"}}
166
167Opens the file, returning \true if successful.
168
169\wxheading{Parameters}
170
171\docparam{filename}{The filename.}
172
173\docparam{mode}{The mode in which to open the file.}
174
175
176\membersection{wxFFile::Read}\label{wxffileread}
177
178\func{size\_t}{Read}{\param{void*}{ buffer}, \param{off\_t}{ count}}
179
180Reads the specified number of bytes into a buffer, returning the actual number read.
181
182\wxheading{Parameters}
183
184\docparam{buffer}{A buffer to receive the data.}
185
186\docparam{count}{The number of bytes to read.}
187
188\wxheading{Return value}
189
190The number of bytes read.
191
192
193\membersection{wxFFile::Seek}\label{wxffileseek}
194
195\func{bool}{Seek}{\param{long }{ofs}, \param{wxSeekMode }{mode = wxFromStart}}
196
197Seeks to the specified position and returns \true on success.
198
199\wxheading{Parameters}
200
201\docparam{ofs}{Offset to seek to.}
202
203\docparam{mode}{One of {\bf wxFromStart}, {\bf wxFromEnd}, {\bf wxFromCurrent}.}
204
205
206\membersection{wxFFile::SeekEnd}\label{wxffileseekend}
207
208\func{bool}{SeekEnd}{\param{long }{ofs = 0}}
209
210Moves the file pointer to the specified number of bytes before the end of the file
211and returns \true on success.
212
213\wxheading{Parameters}
214
215\docparam{ofs}{Number of bytes before the end of the file.}
216
217
218\membersection{wxFFile::Tell}\label{wxffiletell}
219
220\constfunc{size\_t}{Tell}{\void}
221
222Returns the current position.
223
224
225\membersection{wxFFile::Write}\label{wxffilewrite}
226
227\func{size\_t}{Write}{\param{const void*}{ buffer}, \param{size\_t}{ count}}
228
229Writes the specified number of bytes from a buffer.
230
231\wxheading{Parameters}
232
233\docparam{buffer}{A buffer containing the data.}
234
235\docparam{count}{The number of bytes to write.}
236
237\wxheading{Return value}
238
239Number of bytes written.
240
241
242\membersection{wxFFile::Write}\label{wxffilewrites}
243
244\func{bool}{Write}{\param{const wxString\& }{s}, \param{wxMBConv\&}{ conv = wxConvUTF8}}
245
246Writes the contents of the string to the file, returns \true on success.
247
248The second argument is only meaningful in Unicode build of wxWidgets when
249{\it conv} is used to convert {\it s} to multibyte representation.
250
251