1. reset default item in ~wxWindow (better to be safe)

[wxWidgets.git] / docs / latex / wx / file.tex

diff --git a/docs/latex/wx/file.tex b/docs/latex/wx/file.tex
index 655f48fcd4ccb9757423c2f3f2bf0e737dbca587..fa8a9c8bdf216f404da2aaadf2acf95772d6bc3e 100644 (file)
--- a/docs/latex/wx/file.tex
+++ b/docs/latex/wx/file.tex
@@ -3,7 +3,10 @@
 A wxFile performs raw file I/O. This is a very small class designed to
 minimize the overhead of using it - in fact, there is hardly any overhead at
 all, but using it brings you automatic error checking and hides differences
 A wxFile performs raw file I/O. This is a very small class designed to
 minimize the overhead of using it - in fact, there is hardly any overhead at
 all, but using it brings you automatic error checking and hides differences

-between platforms and compilers.
+between platforms and compilers. wxFile also automatically closes the file in
+its destructor making it unnecessary to worry about forgetting to do it.
+wxFile is a wrapper around {\tt file descriptor.} - see also 
+\helpref{wxFFile}{wxffile} for a wrapper around {\tt FILE} structure.

 
 \wxheading{Derived from}
 
 
 \wxheading{Derived from}
 


@@ -17,7 +20,6 @@ None.
 
 wx/file.h defines the following constants:
 
 
 wx/file.h defines the following constants:
 

-{\small

 \begin{verbatim}
 #define wxS_IRUSR 00400
 #define wxS_IWUSR 00200
 \begin{verbatim}
 #define wxS_IRUSR 00400
 #define wxS_IWUSR 00200


@@ -34,13 +36,12 @@ wx/file.h defines the following constants:
 // default mode for the new files: corresponds to umask 022
 #define wxS_DEFAULT  (wxS_IRUSR | wxS_IWUSR | wxS_IRGRP | wxS_IWGRP | wxS_IROTH | wxS_IWOTH)
 \end{verbatim}
 // default mode for the new files: corresponds to umask 022
 #define wxS_DEFAULT  (wxS_IRUSR | wxS_IWUSR | wxS_IRGRP | wxS_IWGRP | wxS_IROTH | wxS_IWOTH)
 \end{verbatim}

-}

 
 These constants define the file access rights and are used with 
 \helpref{wxFile::Create}{wxfilecreate} and \helpref{wxFile::Open}{wxfileopen}.
 
 The {\it OpenMode} enumeration defines the different modes for opening a file,
 
 These constants define the file access rights and are used with 
 \helpref{wxFile::Create}{wxfilecreate} and \helpref{wxFile::Open}{wxfileopen}.
 
 The {\it OpenMode} enumeration defines the different modes for opening a file,

-it's defined inside wxFile class so its members should be specified with {\it wxFile::} scope
+it is defined inside wxFile class so its members should be specified with {\it wxFile::} scope

 resolution prefix. It is also used with \helpref{wxFile::Access}{wxfileaccess} function.
 
 \twocolwidtha{7cm}
 resolution prefix. It is also used with \helpref{wxFile::Access}{wxfileaccess} function.
 
 \twocolwidtha{7cm}


@@ -51,7 +52,8 @@ or test if it can be opened for writing with Access()}
 \twocolitem{{\bf wxFile::read\_write}}{Open file for reading and writing; can not be used with Access()}
 \twocolitem{{\bf wxFile::write\_append}}{Open file for appending: the file is opened for writing, but the old
 contents of the file is not erased and the file pointer is initially placed at the end of the file;
 \twocolitem{{\bf wxFile::read\_write}}{Open file for reading and writing; can not be used with Access()}
 \twocolitem{{\bf wxFile::write\_append}}{Open file for appending: the file is opened for writing, but the old
 contents of the file is not erased and the file pointer is initially placed at the end of the file;

-can not be used with Access()}
+can not be used with Access(). This is the same as {\bf wxFile::write} if the
+file doesn't exist.}

 \end{twocollist}
 
 Other constants defined elsewhere but used by wxFile functions are wxInvalidOffset which represents an
 \end{twocollist}
 
 Other constants defined elsewhere but used by wxFile functions are wxInvalidOffset which represents an


@@ -82,7 +84,7 @@ fail.
 
 \func{}{wxFile}{\param{int}{ fd}}
 
 
 \func{}{wxFile}{\param{int}{ fd}}
 

-Opens a file with the given file descriptor, which has already been opened.
+Associates the file with the given file descriptor, which has already been opened.

 
 \wxheading{Parameters}
 
 
 \wxheading{Parameters}
 


@@ -98,7 +100,7 @@ Opens a file with the given file descriptor, which has already been opened.
 
 Destructor will close the file.
 
 
 Destructor will close the file.
 

-NB: it is not virtual so you should {\it not} derive from wxFile!
+NB: it is not virtual so you should use wxFile polymorphically.

 
 \membersection{wxFile::Access}\label{wxfileaccess}
 
 
 \membersection{wxFile::Access}\label{wxfileaccess}
 


@@ -113,7 +115,7 @@ values of wxFile::read or wxFile::write really make sense here.
 
 Attaches an existing file descriptor to the wxFile object. Example of predefined
 file descriptors are 0, 1 and 2 which correspond to stdin, stdout and stderr (and
 
 Attaches an existing file descriptor to the wxFile object. Example of predefined
 file descriptors are 0, 1 and 2 which correspond to stdin, stdout and stderr (and

-have symbolic names of wxFile::fd\_stdin, wxFile::fd\_stdout and wxFile::fd\_stderr).
+have symbolic names of {\bf wxFile::fd\_stdin}, {\bf wxFile::fd\_stdout} and {\bf wxFile::fd\_stderr}).

 
 The descriptor should be already opened and it will be closed by wxFile
 object.
 
 The descriptor should be already opened and it will be closed by wxFile
 object.


@@ -148,18 +150,28 @@ Returns the file descriptor associated with the file.
 
 \constfunc{bool}{Eof}{\void}
 
 
 \constfunc{bool}{Eof}{\void}
 

-Returns TRUE if the end of the file has been reached (the last byte has been read).
+Returns TRUE if the end of the file has been reached.

 
 

-Note that the behaviour of the file pointer based class
-\helpref{wxFFile}{wxffile} is different as \helpref{wxFFile::Eof}{wxffileeof}
-will return TRUE here only if an attempt has been made to read
-{\it past} the last byte of the file.
+Note that the behaviour of the file pointer based class 
+\helpref{wxFFile}{wxffile} is different as \helpref{wxFFile::Eof}{wxffileeof} 
+will return TRUE here only if an attempt has been made to read 
+{\it past} the last byte of the file, while wxFile::Eof() will return TRUE
+even before such attempt is made if the file pointer is at the last position
+in the file.
+
+Note also that this function doesn't work on unseekable file descriptors
+(examples include pipes, terminals and sockets under Unix) and an attempt to
+use it will result in an error message in such case. So, to read the entire
+file into memory, you should write a loop which uses 
+\helpref{Read}{wxfileread} repeatedly and tests its return condition instead
+of using Eof() as this will not work for special files under Unix.

 
 \membersection{wxFile::Exists}\label{wxfileexists}
 
 \func{static bool}{Exists}{\param{const char*}{ filename}}
 
 
 \membersection{wxFile::Exists}\label{wxfileexists}
 
 \func{static bool}{Exists}{\param{const char*}{ filename}}
 

-Returns TRUE if the given name specifies an existing regular file.
+Returns TRUE if the given name specifies an existing regular file (not a
+directory or a link)

 
 \membersection{wxFile::Flush}\label{wxfileflush}
 
 
 \membersection{wxFile::Flush}\label{wxfileflush}
 


@@ -246,11 +258,11 @@ The actual offset position achieved, or wxInvalidOffset on failure.
 \constfunc{off\_t}{Tell}{\void}
 
 Returns the current position or wxInvalidOffset if file is not opened or if another
 \constfunc{off\_t}{Tell}{\void}
 
 Returns the current position or wxInvalidOffset if file is not opened or if another

-error occured.
+error occurred.

 
 \membersection{wxFile::Write}\label{wxfilewrite}
 
 
 \membersection{wxFile::Write}\label{wxfilewrite}
 

-\func{bool}{Write}{\param{const void*}{ buffer}, \param{off\_t}{ count}}
+\func{size\_t}{Write}{\param{const void*}{ buffer}, \param{off\_t}{ count}}

 
 Writes the specified number of bytes from a buffer.
 
 
 Writes the specified number of bytes from a buffer.
 


@@ -262,20 +274,24 @@ Writes the specified number of bytes from a buffer.
 
 \wxheading{Return value}
 
 
 \wxheading{Return value}
 

-TRUE if the operation was successful.
+the number of bytes actually written

 
 \membersection{wxFile::Write}\label{wxfilewrites}
 
 
 \membersection{wxFile::Write}\label{wxfilewrites}
 

-\func{bool}{Write}{\param{const wxString\& }{s}}
+\func{bool}{Write}{\param{const wxString\& }{s}, \param{wxMBConv&}{ conv = wxConvLibc}}

 
 Writes the contents of the string to the file, returns TRUE on success.
 
 
 Writes the contents of the string to the file, returns TRUE on success.
 

+The second argument is only meaningful in Unicode build of wxWindows when
+{\it conv} is used to convert {\it s} to multibyte representation.
+

 \section{\class{wxFFile}}\label{wxffile}
 
 \section{\class{wxFFile}}\label{wxffile}
 

-A wxFFile performs raw file I/O. This is a very small class designed to
+wxFFile implements buffered file I/O. This is a very small class designed to

 minimize the overhead of using it - in fact, there is hardly any overhead at
 all, but using it brings you automatic error checking and hides differences
 minimize the overhead of using it - in fact, there is hardly any overhead at
 all, but using it brings you automatic error checking and hides differences

-between platforms and compilers.
+between platforms and compilers. It wraps inside it a {\tt FILE *} handle used
+by standard C IO library (also known as {\tt stdio}).

 
 \wxheading{Derived from}
 
 
 \wxheading{Derived from}
 


@@ -315,7 +331,10 @@ Opens a file with the given file pointer, which has already been opened.
 
 \docparam{filename}{The filename.}
 
 
 \docparam{filename}{The filename.}
 

-\docparam{mode}{The mode in which to open the file using standard C strings.}
+\docparam{mode}{The mode in which to open the file using standard C strings.
+Note that you should use {\tt "b"} flag if you use binary files under Windows
+or the results might be unexpected due to automatic newline conversion done
+for the text files.}

 
 \docparam{fp}{An existing file descriptor, such as stderr.}
 
 
 \docparam{fp}{An existing file descriptor, such as stderr.}
 


@@ -444,7 +463,7 @@ Returns the current position.
 
 \membersection{wxFFile::Write}\label{wxffilewrite}
 
 
 \membersection{wxFFile::Write}\label{wxffilewrite}
 

-\func{size_t}{Write}{\param{const void*}{ buffer}, \param{size\_t}{ count}}
+\func{size\_t}{Write}{\param{const void*}{ buffer}, \param{size\_t}{ count}}

 
 Writes the specified number of bytes from a buffer.
 
 
 Writes the specified number of bytes from a buffer.
 


@@ -460,7 +479,9 @@ Number of bytes written.
 
 \membersection{wxFFile::Write}\label{wxffilewrites}
 
 
 \membersection{wxFFile::Write}\label{wxffilewrites}
 

-\func{bool}{Write}{\param{const wxString\& }{s}}
+\func{bool}{Write}{\param{const wxString\& }{s}, \param{wxMBConv&}{ conv = wxConvLibc}}

 
 Writes the contents of the string to the file, returns TRUE on success.
 
 
 Writes the contents of the string to the file, returns TRUE on success.
 

+The second argument is only meaningful in Unicode build of wxWindows when
+{\it conv} is used to convert {\it s} to multibyte representation.