]> git.saurik.com Git - wxWidgets.git/blame_incremental - docs/latex/wx/file.tex
Set/GetWindowMenu added to MDI parent frame under MSW
[wxWidgets.git] / docs / latex / wx / file.tex
... / ...
CommitLineData
1\section{\class{wxFile}}\label{wxfile}
2
3A wxFile performs raw file I/O. This is a very small class designed to
4minimize the overhead of using it - in fact, there is hardly any overhead at
5all, but using it brings you automatic error checking and hides differences
6between platforms and compilers. wxFile also automatically closes the file in
7its destructor making it unnecessary to worry about forgetting to do it.
8
9\wxheading{Derived from}
10
11None.
12
13\wxheading{Include files}
14
15<wx/file.h>
16
17\wxheading{Constants}
18
19wx/file.h defines the following constants:
20
21{\small
22\begin{verbatim}
23#define wxS_IRUSR 00400
24#define wxS_IWUSR 00200
25#define wxS_IXUSR 00100
26
27#define wxS_IRGRP 00040
28#define wxS_IWGRP 00020
29#define wxS_IXGRP 00010
30
31#define wxS_IROTH 00004
32#define wxS_IWOTH 00002
33#define wxS_IXOTH 00001
34
35// default mode for the new files: corresponds to umask 022
36#define wxS_DEFAULT (wxS_IRUSR | wxS_IWUSR | wxS_IRGRP | wxS_IWGRP | wxS_IROTH | wxS_IWOTH)
37\end{verbatim}
38}
39
40These constants define the file access rights and are used with
41\helpref{wxFile::Create}{wxfilecreate} and \helpref{wxFile::Open}{wxfileopen}.
42
43The {\it OpenMode} enumeration defines the different modes for opening a file,
44it's defined inside wxFile class so its members should be specified with {\it wxFile::} scope
45resolution prefix. It is also used with \helpref{wxFile::Access}{wxfileaccess} function.
46
47\twocolwidtha{7cm}
48\begin{twocollist}\itemsep=0pt%
49\twocolitem{{\bf wxFile::read}}{Open file for reading or test if it can be opened for reading with Access()}
50\twocolitem{{\bf wxFile::write}}{Open file for writing deleting the contents of the file if it already exists
51or test if it can be opened for writing with Access()}
52\twocolitem{{\bf wxFile::read\_write}}{Open file for reading and writing; can not be used with Access()}
53\twocolitem{{\bf wxFile::write\_append}}{Open file for appending: the file is opened for writing, but the old
54contents of the file is not erased and the file pointer is initially placed at the end of the file;
55can not be used with Access()}
56\end{twocollist}
57
58Other constants defined elsewhere but used by wxFile functions are wxInvalidOffset which represents an
59invalid value of type {\it off\_t} and is returned by functions returning {\it off\_t} on error and the seek
60mode constants used with \helpref{Seek()}{wxfileseek}:
61
62\twocolwidtha{7cm}
63\begin{twocollist}\itemsep=0pt%
64\twocolitem{{\bf wxFromStart}}{Count offset from the start of the file}
65\twocolitem{{\bf wxFromCurrent}}{Count offset from the current position of the file pointer}
66\twocolitem{{\bf wxFromEnd}}{Count offset from the end of the file (backwards)}
67\end{twocollist}
68
69\latexignore{\rtfignore{\wxheading{Members}}}
70
71\membersection{wxFile::wxFile}\label{wxfileconstr}
72
73\func{}{wxFile}{\void}
74
75Default constructor.
76
77\func{}{wxFile}{\param{const char*}{ filename}, \param{wxFile::OpenMode}{ mode = wxFile::read}}
78
79Opens a file with the given mode. As there is no way to return whether the
80operation was successful or not from the constructor you should test the
81return value of \helpref{IsOpened}{wxfileisopened} to check that it didn't
82fail.
83
84\func{}{wxFile}{\param{int}{ fd}}
85
86Associates the file with the given file descriptor, which has already been opened.
87
88\wxheading{Parameters}
89
90\docparam{filename}{The filename.}
91
92\docparam{mode}{The mode in which to open the file. May be one of {\bf wxFile::read}, {\bf wxFile::write} and {\bf wxFile::read\_write}.}
93
94\docparam{fd}{An existing file descriptor (see \helpref{Attach()}{wxfileattach} for the list of predefined descriptors)}
95
96\membersection{wxFile::\destruct{wxFile}}
97
98\func{}{\destruct{wxFile}}{\void}
99
100Destructor will close the file.
101
102NB: it is not virtual so you should use wxFile polymorphically.
103
104\membersection{wxFile::Access}\label{wxfileaccess}
105
106\func{static bool}{Access}{\param{const char *}{ name}, \param{OpenMode}{ mode}}
107
108This function verifies if we may access the given file in specified mode. Only
109values of wxFile::read or wxFile::write really make sense here.
110
111\membersection{wxFile::Attach}\label{wxfileattach}
112
113\func{void}{Attach}{\param{int}{ fd}}
114
115Attaches an existing file descriptor to the wxFile object. Example of predefined
116file descriptors are 0, 1 and 2 which correspond to stdin, stdout and stderr (and
117have symbolic names of {\bf wxFile::fd\_stdin}, {\bf wxFile::fd\_stdout} and {\bf wxFile::fd\_stderr}).
118
119The descriptor should be already opened and it will be closed by wxFile
120object.
121
122\membersection{wxFile::Close}\label{wxfileclose}
123
124\func{void}{Close}{\void}
125
126Closes the file.
127
128\membersection{wxFile::Create}\label{wxfilecreate}
129
130\func{bool}{Create}{\param{const char*}{ filename}, \param{bool}{ overwrite = FALSE}, \param{int }{access = wxS\_DEFAULT}}
131
132Creates a file for writing. If the file already exists, setting {\bf overwrite} to TRUE
133will ensure it is overwritten.
134
135\membersection{wxFile::Detach}\label{wxfiledetach}
136
137\func{void}{Detach}{\void}
138
139Get back a file descriptor from wxFile object - the caller is responsible for closing the file if this
140descriptor is opened. \helpref{IsOpened()}{wxfileisopened} will return FALSE after call to Detach().
141
142\membersection{wxFile::fd}\label{wxfilefd}
143
144\constfunc{int}{fd}{\void}
145
146Returns the file descriptor associated with the file.
147
148\membersection{wxFile::Eof}\label{wxfileeof}
149
150\constfunc{bool}{Eof}{\void}
151
152Returns TRUE if the end of the file has been reached.
153
154Note that the behaviour of the file pointer based class
155\helpref{wxFFile}{wxffile} is different as \helpref{wxFFile::Eof}{wxffileeof}
156will return TRUE here only if an attempt has been made to read
157{\it past} the last byte of the file, while wxFile::Eof() will return TRUE
158even before such attempt is made if the file pointer is at the last position
159in the file.
160
161Note also that this function doesn't work on unseekable file descriptors
162(examples include pipes, terminals and sockets under Unix) and an attempt to
163use it will result in an error message in such case.
164
165\membersection{wxFile::Exists}\label{wxfileexists}
166
167\func{static bool}{Exists}{\param{const char*}{ filename}}
168
169Returns TRUE if the given name specifies an existing regular file (not a
170directory or a link)
171
172\membersection{wxFile::Flush}\label{wxfileflush}
173
174\func{bool}{Flush}{\void}
175
176Flushes the file descriptor.
177
178Note that wxFile::Flush is not implemented on some Windows compilers
179due to a missing fsync function, which reduces the usefulness of this function
180(it can still be called but it will do nothing on unsupported compilers).
181
182\membersection{wxFile::IsOpened}\label{wxfileisopened}
183
184\constfunc{bool}{IsOpened}{\void}
185
186Returns TRUE if the file has been opened.
187
188\membersection{wxFile::Length}\label{wxfilelength}
189
190\constfunc{off\_t}{Length}{\void}
191
192Returns the length of the file.
193
194\membersection{wxFile::Open}\label{wxfileopen}
195
196\func{bool}{Open}{\param{const char*}{ filename}, \param{wxFile::OpenMode}{ mode = wxFile::read}}
197
198Opens the file, returning TRUE if successful.
199
200\wxheading{Parameters}
201
202\docparam{filename}{The filename.}
203
204\docparam{mode}{The mode in which to open the file. May be one of {\bf wxFile::read}, {\bf wxFile::write} and {\bf wxFile::read\_write}.}
205
206\membersection{wxFile::Read}\label{wxfileread}
207
208\func{off\_t}{Read}{\param{void*}{ buffer}, \param{off\_t}{ count}}
209
210Reads the specified number of bytes into a buffer, returning the actual number read.
211
212\wxheading{Parameters}
213
214\docparam{buffer}{A buffer to receive the data.}
215
216\docparam{count}{The number of bytes to read.}
217
218\wxheading{Return value}
219
220The number of bytes read, or the symbol {\bf wxInvalidOffset} (-1) if there was an error.
221
222\membersection{wxFile::Seek}\label{wxfileseek}
223
224\func{off\_t}{Seek}{\param{off\_t }{ofs}, \param{wxSeekMode }{mode = wxFromStart}}
225
226Seeks to the specified position.
227
228\wxheading{Parameters}
229
230\docparam{ofs}{Offset to seek to.}
231
232\docparam{mode}{One of {\bf wxFromStart}, {\bf wxFromEnd}, {\bf wxFromCurrent}.}
233
234\wxheading{Return value}
235
236The actual offset position achieved, or wxInvalidOffset on failure.
237
238\membersection{wxFile::SeekEnd}\label{wxfileseekend}
239
240\func{off\_t}{SeekEnd}{\param{off\_t }{ofs = 0}}
241
242Moves the file pointer to the specified number of bytes before the end of the file.
243
244\wxheading{Parameters}
245
246\docparam{ofs}{Number of bytes before the end of the file.}
247
248\wxheading{Return value}
249
250The actual offset position achieved, or wxInvalidOffset on failure.
251
252\membersection{wxFile::Tell}\label{wxfiletell}
253
254\constfunc{off\_t}{Tell}{\void}
255
256Returns the current position or wxInvalidOffset if file is not opened or if another
257error occured.
258
259\membersection{wxFile::Write}\label{wxfilewrite}
260
261\func{bool}{Write}{\param{const void*}{ buffer}, \param{off\_t}{ count}}
262
263Writes the specified number of bytes from a buffer.
264
265\wxheading{Parameters}
266
267\docparam{buffer}{A buffer containing the data.}
268
269\docparam{count}{The number of bytes to write.}
270
271\wxheading{Return value}
272
273TRUE if the operation was successful.
274
275\membersection{wxFile::Write}\label{wxfilewrites}
276
277\func{bool}{Write}{\param{const wxString\& }{s}}
278
279Writes the contents of the string to the file, returns TRUE on success.
280
281\section{\class{wxFFile}}\label{wxffile}
282
283A wxFFile performs raw file I/O. This is a very small class designed to
284minimize the overhead of using it - in fact, there is hardly any overhead at
285all, but using it brings you automatic error checking and hides differences
286between platforms and compilers.
287
288\wxheading{Derived from}
289
290None.
291
292\wxheading{Include files}
293
294<wx/ffile.h>
295
296\twocolwidtha{7cm}
297\begin{twocollist}\itemsep=0pt%
298\twocolitem{{\bf wxFromStart}}{Count offset from the start of the file}
299\twocolitem{{\bf wxFromCurrent}}{Count offset from the current position of the file pointer}
300\twocolitem{{\bf wxFromEnd}}{Count offset from the end of the file (backwards)}
301\end{twocollist}
302
303\latexignore{\rtfignore{\wxheading{Members}}}
304
305\membersection{wxFFile::wxFFile}\label{wxffileconstr}
306
307\func{}{wxFFile}{\void}
308
309Default constructor.
310
311\func{}{wxFFile}{\param{const char*}{ filename}, \param{const char*}{ mode = "r"}}
312
313Opens a file with the given mode. As there is no way to return whether the
314operation was successful or not from the constructor you should test the
315return value of \helpref{IsOpened}{wxffileisopened} to check that it didn't
316fail.
317
318\func{}{wxFFile}{\param{FILE*}{ fp}}
319
320Opens a file with the given file pointer, which has already been opened.
321
322\wxheading{Parameters}
323
324\docparam{filename}{The filename.}
325
326\docparam{mode}{The mode in which to open the file using standard C strings.}
327
328\docparam{fp}{An existing file descriptor, such as stderr.}
329
330\membersection{wxFFile::\destruct{wxFFile}}
331
332\func{}{\destruct{wxFFile}}{\void}
333
334Destructor will close the file.
335
336NB: it is not virtual so you should {\it not} derive from wxFFile!
337
338\membersection{wxFFile::Attach}\label{wxffileattach}
339
340\func{void}{Attach}{\param{FILE*}{ fp}}
341
342Attaches an existing file pointer to the wxFFile object.
343
344The descriptor should be already opened and it will be closed by wxFFile
345object.
346
347\membersection{wxFFile::Close}\label{wxffileclose}
348
349\func{bool}{Close}{\void}
350
351Closes the file and returns TRUE on success.
352
353\membersection{wxFFile::Detach}\label{wxffiledetach}
354
355\func{void}{Detach}{\void}
356
357Get back a file pointer from wxFFile object - the caller is responsible for closing the file if this
358descriptor is opened. \helpref{IsOpened()}{wxffileisopened} will return FALSE after call to Detach().
359
360\membersection{wxFFile::fp}\label{wxffilefp}
361
362\constfunc{FILE *}{fp}{\void}
363
364Returns the file pointer associated with the file.
365
366\membersection{wxFFile::Eof}\label{wxffileeof}
367
368\constfunc{bool}{Eof}{\void}
369
370Returns TRUE if the an attempt has been made to read {\it past}
371the end of the file.
372
373Note that the behaviour of the file descriptor based class
374\helpref{wxFile}{wxfile} is different as \helpref{wxFile::Eof}{wxfileeof}
375will return TRUE here as soon as the last byte of the file has been
376read.
377
378\membersection{wxFFile::Flush}\label{wxffileflush}
379
380\func{bool}{Flush}{\void}
381
382Flushes the file and returns TRUE on success.
383
384\membersection{wxFFile::IsOpened}\label{wxffileisopened}
385
386\constfunc{bool}{IsOpened}{\void}
387
388Returns TRUE if the file has been opened.
389
390\membersection{wxFFile::Length}\label{wxffilelength}
391
392\constfunc{size\_t}{Length}{\void}
393
394Returns the length of the file.
395
396\membersection{wxFFile::Open}\label{wxffileopen}
397
398\func{bool}{Open}{\param{const char*}{ filename}, \param{const char*}{ mode = "r"}}
399
400Opens the file, returning TRUE if successful.
401
402\wxheading{Parameters}
403
404\docparam{filename}{The filename.}
405
406\docparam{mode}{The mode in which to open the file.}
407
408\membersection{wxFFile::Read}\label{wxffileread}
409
410\func{size\_t}{Read}{\param{void*}{ buffer}, \param{off\_t}{ count}}
411
412Reads the specified number of bytes into a buffer, returning the actual number read.
413
414\wxheading{Parameters}
415
416\docparam{buffer}{A buffer to receive the data.}
417
418\docparam{count}{The number of bytes to read.}
419
420\wxheading{Return value}
421
422The number of bytes read.
423
424\membersection{wxFFile::Seek}\label{wxffileseek}
425
426\func{bool}{Seek}{\param{long }{ofs}, \param{wxSeekMode }{mode = wxFromStart}}
427
428Seeks to the specified position and returs TRUE on success.
429
430\wxheading{Parameters}
431
432\docparam{ofs}{Offset to seek to.}
433
434\docparam{mode}{One of {\bf wxFromStart}, {\bf wxFromEnd}, {\bf wxFromCurrent}.}
435
436\membersection{wxFFile::SeekEnd}\label{wxffileseekend}
437
438\func{bool}{SeekEnd}{\param{long }{ofs = 0}}
439
440Moves the file pointer to the specified number of bytes before the end of the file
441and returns TRUE on success.
442
443\wxheading{Parameters}
444
445\docparam{ofs}{Number of bytes before the end of the file.}
446
447\membersection{wxFFile::Tell}\label{wxffiletell}
448
449\constfunc{size\_t}{Tell}{\void}
450
451Returns the current position.
452
453\membersection{wxFFile::Write}\label{wxffilewrite}
454
455\func{size\_t}{Write}{\param{const void*}{ buffer}, \param{size\_t}{ count}}
456
457Writes the specified number of bytes from a buffer.
458
459\wxheading{Parameters}
460
461\docparam{buffer}{A buffer containing the data.}
462
463\docparam{count}{The number of bytes to write.}
464
465\wxheading{Return value}
466
467Number of bytes written.
468
469\membersection{wxFFile::Write}\label{wxffilewrites}
470
471\func{bool}{Write}{\param{const wxString\& }{s}}
472
473Writes the contents of the string to the file, returns TRUE on success.
474