From: Vadim Zeitlin <vadim@wxwidgets.org>
Date: Tue, 12 Jan 1999 23:10:02 +0000 (+0000)
Subject: more files I forgot to commit (wxFile/wxTempFile/wxTextFile docs)
X-Git-Url: https://git.saurik.com/wxWidgets.git/commitdiff_plain/7f5611433880457cb704eb6c66129f0aeac86ac5?ds=inline

more files I forgot to commit (wxFile/wxTempFile/wxTextFile docs)


git-svn-id: https://svn.wxwidgets.org/svn/wx/wxWidgets/trunk@1381 c3d73ce0-8a6f-49c7-b76d-6d57e0e08775
---

diff --git a/docs/latex/wx/tempfile.tex b/docs/latex/wx/tempfile.tex
new file mode 100644
index 0000000000..2a196c6432
--- /dev/null
+++ b/docs/latex/wx/tempfile.tex
@@ -0,0 +1,99 @@
+% automatically generated by HelpGen from tempfile.tex at 10/Jan/99 19:24:44
+\section{\class{wxTempFile}}\label{wxtempfile}
+
+wxTempFile provides a relatively safe way to replace the contents of the
+existing file. The name is explained by the fact that it may be also used as
+just a temporary file if you don't replace the old file contents.
+
+Usually, when a program replaces the contents of some file it first opens it for
+writing, thus losing all of the old data and then starts recreating it. This
+approach is not very safe because during the regeneration of the file bad things
+may happen: the program may find that there is an internal error preventing it
+from completing file generation, the user may interrupt it (especially if file
+generation takes long time) and, finally, any other external interrupts (power
+supply failure or a disk error) will leave you without either the original file
+or the new one.
+
+wxTempFile addresses this problem by creating a temporary file which is meant to
+replace the original file - but only after it is fully written. So, if the user
+interrupts the program during the file generation, the old file won't be lost.
+Also, if the program discovers itself that it doesn't want to replace the old
+file there is no problem - in fact, wxTempFile will {\bf not} replace the old
+file by default, you should explicitly call \helpref{Commit}{wxtempfilecommit} 
+to do it. Calling \helpref{Discard}{wxtempfilediscard} explicitly discards any
+modifications: it closes and deletes the temporary file and leaves the original
+file unchanged. If you don't call neither of Commit() and Discard(), the
+destructor will call Discard() automatically.
+
+To summarize: if you want to replace another file, create an instance of
+wxTempFile passing the name of the file to be replaced to the constructor (you
+may also use default constructor and pass the file name to 
+\helpref{Open}{wxtempfileopen}). Then you can \helpref{write}{wxtempfilewrite} 
+to wxTempFile using \helpref{wxFile}{wxfile}-like functions and later call
+Commit() to replace the old file (and close this one) or call Discard() to cancel
+the modifications.
+
+\wxheading{Derived from}
+
+No base class
+
+\wxheading{See also:}
+
+\helpref{wxFile}{wxfile}
+
+\latexignore{\rtfignore{\wxheading{Members}}}
+
+\membersection{wxTempFile::wxTempFile}\label{wxtempfilewxtempfilector}
+\func{}{wxTempFile}{\void}
+
+Default constructor - \helpref{Open}{wxtempfileopen} must be used to open the
+file.
+
+\membersection{wxTempFile::wxTempFile}\label{wxtempfilewxtempfile}
+\func{}{wxTempFile}{\param{const wxString\& }{strName}}
+
+Associates wxTempFile with the file to be replaced and opens it. You should use
+\helpref{IsOpened}{wxtempfileisopened} to verify if the constructor succeeded.
+
+\membersection{wxTempFile::Open}\label{wxtempfileopen}
+\func{bool}{Open}{\param{const wxString\& }{strName}}
+
+Open the temporary file (strName is the name of file to be replaced), returns
+TRUE on success, FALSE if an error occured.
+
+\membersection{wxTempFile::IsOpened}\label{wxtempfileisopened}
+\constfunc{bool}{IsOpened}{\void}
+
+Returns TRUE if the file was successfully opened.
+
+\membersection{wxTempFile::Write}\label{wxtempfilewrite}
+\func{bool}{Write}{\param{const void }{*p}, \param{size\_t }{n}}
+
+Write to the file, return TRUE on success, FALSE on failure.
+
+\membersection{wxTempFile::Write}\label{wxtempfilewrites}
+\func{bool}{Write}{\param{const wxString\& }{str}}
+
+Write to the file, return TRUE on success, FALSE on failure.
+
+\membersection{wxTempFile::Commit}\label{wxtempfilecommit}
+\func{bool}{Commit}{\void}
+
+Validate changes: deletes the old file of name m\_strName and renames the new
+file to the old name. Returns TRUE if both actions succeeded. If FALSE is
+returned it may unfortunately mean two quite different things: either that
+either the old file couldn't be deleted or that the new file couldn't be renamed
+to the old name.
+
+\membersection{wxTempFile::Discard}\label{wxtempfilediscard}
+\func{void}{Discard}{\void}
+
+Discard changes: the old file contents is not changed, temporary file is
+deleted.
+
+\membersection{wxTempFile::\destruct{wxTempFile}}\label{wxtempfiledtor}
+\func{}{\destruct{wxTempFile}}{\void}
+
+Destructor calls \helpref{Discard()}{wxtempfilediscard} if temporary file
+is still opened.
+
diff --git a/docs/latex/wx/textfile.tex b/docs/latex/wx/textfile.tex
new file mode 100644
index 0000000000..5c281ba660
--- /dev/null
+++ b/docs/latex/wx/textfile.tex
@@ -0,0 +1,223 @@
+% automatically generated by HelpGen from textfile.tex at 10/Jan/99 18:47:37
+\section{\class{wxTextFile}}\label{wxtextfile}
+
+The wxTextFile is a simple class which allows to work with text files on line by
+line basis. It also understands the differences in line termination characters
+under different platforms and will not do anything bad to files with "non
+native" line termination sequences - in fact, it can be also used to modify the
+text files and chaneg the line termination characters from one type (say DOS) to
+another (say Unix).
+
+One word of warning: the class is not at all optimized for big files and so it
+will load the file entirely into memory when opened. Of course, you should not
+work in this way with large files (as an estimation, anything over 1 Megabyte is
+surely too big for this class). On the other hand, it is not a serious
+limitation for the small files like configuration files or programs sources
+which are well handled by wxTextFile.
+
+The typical things you may do with wxTextFile in order are:
+\begin{itemize}\itemsep=0pt
+\item Create and open it: this is done with \helpref{Open}{wxtextfileopen} 
+function which opens the file (name may be specified either as Open argument or
+in the constructor), reads its contents in memory and closes it. If all of these
+operations are successful, Open() will return TRUE and FALSE on error.
+\item Work with the lines in the file: this may be done either with "direct
+access" functions like \helpref{GetLineCount}{wxtextfilegetlinecount} and
+\helpref{GetLine}{wxtextfilegetline} ({\it operator[]} does exactly the same
+but looks more like array addressing) or with "sequential access" functions
+which include \helpref{GetFirstLine}{wxtextfilegetfirstline}/
+\helpref{GetNextLine}{wxtextfilegetnextline} and also 
+\helpref{GetLastLine}{getlastline}/\helpref{GetPrevLine}{wxtextfilegetprevline}.
+For the sequential access functions the current line number is maintained: it is
+returned by \helpref{GetCurrentLine}{wxtextfilegetcurrentline} and may be
+changed with \helpref{GoToLine}{wxtextfilegotoline}.
+\item Add/remove lines to the file: \helpref{AddLine}{wxtextfileaddline} and 
+\helpref{InsertLine}{wxtextfileinsertline} add new lines while 
+\helpref{RemoveLine}{wxtextfileremoveline} deletes the existing ones.
+\item Save your changes: notice that the changes you do to the file will {\bf
+not} be saved automatically, calling \helpref{Close}{wxtextfileclose} or doing
+nothing discards them! To save the chanegs you must explicitly call 
+\helpref{Write}{wxtextfilewrite} - here, you may also change the line
+termination type if you wish.
+\end{itemize}
+
+\wxheading{See also:}
+
+\helpref{wxFile}{wxfile}
+
+\wxheading{Derived from}
+
+No base class
+
+\wxheading{Data structures}
+
+The following constants identify the line termination type:
+\begin{verbatim}
+enum wxTextFileType
+{
+    wxTextFileType_None,  // incomplete (the last line of the file only)
+    wxTextFileType_Unix,  // line is terminated with 'LF' = 0xA = 10 = '\n'
+    wxTextFileType_Dos,   //                         'CR' 'LF'
+    wxTextFileType_Mac    //                         'CR' = 0xD = 13 = '\r'
+}
+\end{verbatim}
+
+\latexignore{\rtfignore{\wxheading{Members}}}
+
+\membersection{wxTextFile::wxTextFile}\label{wxtextfilectordef}
+\constfunc{}{wxTextFile}{\void}
+
+Default constructor, use Open(string) to initialize the object.
+
+\membersection{wxTextFile::wxTextFile}\label{wxtextfilector}
+\constfunc{}{wxTextFile}{\param{const wxString\& }{strFile}}
+
+Constructor does not load the file into memory, use Open() to do it. 
+
+\membersection{wxTextFile::Exists}\label{wxtextfileexists}
+\constfunc{bool}{Exists}{\void}
+
+Return TRUE if file exists - the name of the file should have been specified
+in the constructor before calling Exists().
+
+\membersection{wxTextFile::Open}\label{wxtextfileopen}
+\constfunc{bool}{Open}{\void}
+
+Open() opens the file with the name which was given in the \helpref{constructor}{wxtextfilector} 
+and also loads file in memory on success.
+
+\membersection{wxTextFile::Open}\label{wxtextfileopenname}
+\constfunc{bool}{Open}{\param{const wxString\& }{strFile}}
+
+Same as \helpref{Open()}{wxtextfileopen} but allows to specify the file name
+(must be used if the default constructor was used to create the object).
+
+\membersection{wxTextFile::Close}\label{wxtextfileclose}
+\constfunc{bool}{Close}{\void}
+
+Closes the file and frees memory, {\bf losing all changes}. Use \helpref{Write()}{wxtextfilewrite} 
+if you want to save them.
+
+\membersection{wxTextFile::IsOpened}\label{wxtextfileisopened}
+\constfunc{bool}{IsOpened}{\void}
+
+Returns TRUE if the file is currently opened.
+
+\membersection{wxTextFile::GetLineCount}\label{wxtextfilegetlinecount}
+\constfunc{size\_t}{GetLineCount}{\void}
+
+Get the number of lines in the file.
+
+\membersection{wxTextFile::GetLine}\label{wxtextfilegetline}
+\constfunc{wxString\&}{GetLine}{\param{size\_t }{n}}
+
+Retrieves the line number {\it n} from the file. The returned line may be
+modified but you shouldn't add line terminator at the end - this will be done
+by wxTextFile.
+
+\membersection{wxTextFile::operator[]}\label{wxtextfileoperator[]}
+\constfunc{wxString\&}{operator[]}{\param{size\_t }{n}}
+
+The same as \helpref{GetLine}{wxtextfilegetline}.
+
+\membersection{wxTextFile::GetCurrentLine}\label{wxtextfilegetcurrentline}
+\constfunc{size\_t}{GetCurrentLine}{\void}
+
+Returns the current line: it has meaning only when you're using
+GetFirstLine()/GetNextLine() functions, it doesn't get updated when
+you're using "direct access" functions like GetLine(). GetFirstLine() and
+GetLastLine() also change the value of the current line, as well as
+GoToLine().
+
+\membersection{wxTextFile::GoToLine}\label{wxtextfilegotoline}
+\constfunc{void}{GoToLine}{\param{size\_t }{n}}
+
+Changes the value returned by \helpref{GetCurrentLine}{wxtextfilegetcurrentline} 
+and used by \helpref{GetFirstLine()}{wxtextfilegetfirstline}()/\helpref{GetNextLine()}{wxtextfilegetnextline}.
+
+\membersection{wxTextFile::Eof}\label{wxtextfileeof}
+\constfunc{bool}{Eof}{\void}
+
+Returns TRUE if the current line is the last one.
+
+\membersection{wxTextFile::GetFirstLine}\label{wxtextfilegetfirstline}
+\constfunc{wxString\&}{GetFirstLine}{\void}
+
+This method together with \helpref{GetNextLine()}{wxtextfilegetnextline} 
+allows more "iterator-like" traversal of the list of lines, i.e. you may
+write something like:
+
+\begin{verbatim}
+for ( str = GetFirstLine(); !Eof(); str = GetNextLine() )
+{
+    // do something with the current line in str
+}
+\end{verbatim}
+
+\membersection{wxTextFile::GetNextLine}\label{wxtextfilegetnextline}
+\func{wxString\&}{GetNextLine}{\void}
+
+Gets the next line (see \helpref{GetFirstLine}{wxtextfilegetfirstline} for 
+the example).
+
+\membersection{wxTextFile::GetPrevLine}\label{wxtextfilegetprevline}
+\func{wxString\&}{GetPrevLine}{\void}
+
+Gets the previous line in the file.
+
+\membersection{wxTextFile::GetLastLine}\label{wxtextfilegetlastline}
+\func{wxString\&}{GetLastLine}{\void}
+
+Gets the last line of the file.
+
+\membersection{wxTextFile::GetLineType}\label{wxtextfilegetlinetype}
+\constfunc{wxTextFileType}{GetLineType}{\param{size\_t }{n}}
+
+Get the type of the line (see also \helpref{GetEOL}{wxtextfilegeteol})
+
+\membersection{wxTextFile::GuessType}\label{wxtextfileguesstype}
+\constfunc{wxTextFileType}{GuessType}{\void}
+
+Guess the type of file (which is supposed to be opened). If sufficiently
+many lines of the file are in DOS/Unix/Mac format, the corresponding value will
+be returned. If the detection mechanism fails wxTextFileType\_None is returned.
+
+\membersection{wxTextFile::GetName}\label{wxtextfilegetname}
+\constfunc{const char*}{GetName}{\void}
+
+Get the name of the file.
+
+\membersection{wxTextFile::AddLine}\label{wxtextfileaddline}
+\constfunc{void}{AddLine}{\param{const wxString\& }{str}, \param{wxTextFileType }{type = typeDefault}}
+
+Adds a line to the end of file.
+
+\membersection{wxTextFile::InsertLine}\label{wxtextfileinsertline}
+\constfunc{void}{InsertLine}{\param{const wxString\& }{str}, \param{size\_t }{n}, \param{wxTextFileType }{type = typeDefault}}
+
+Insert a line before the line number {\it n}.
+
+\membersection{wxTextFile::RemoveLine}\label{wxtextfileremoveline}
+\constfunc{void}{RemoveLine}{\param{size\_t }{n}}
+
+Delete one line from the file.
+
+\membersection{wxTextFile::Write}\label{wxtextfilewrite}
+\constfunc{bool}{Write}{\param{wxTextFileType }{typeNew = wxTextFileType\_None}}
+
+Change the file on disk. The {\it typeNew} parameter allows to change the
+file format (default argument means "don't change type") and may be used to
+convert, for example, DOS files to Unix.
+
+\membersection{wxTextFile::GetEOL}\label{wxtextfilegeteol}
+\constfunc{static const char*}{GetEOL}{\param{wxTextFileType }{type = typeDefault}}
+
+Get the line termination string corresponding to given constant. {\it typeDefault} is
+the value defined during the compilation and corresponds to the native format of the
+platform, i.e. it will be wxTextFileType\_Dos under Windows, wxTextFileType\_Unix under
+Unix and wxTextFileType\_Mac under Mac.
+
+\membersection{wxTextFile::\destruct{wxTextFile}}\label{wxtextfiledtor}
+\constfunc{}{\destruct{wxTextFile}}{\void}
+
+Destructor does nothing.
diff --git a/docs/latex/wx/tfile.tex b/docs/latex/wx/tfile.tex
new file mode 100644
index 0000000000..44b5028aa7
--- /dev/null
+++ b/docs/latex/wx/tfile.tex
@@ -0,0 +1,27 @@
+\section{File classes and functions overview}\label{wxfileoverview}
+
+Classes: \helpref{wxFile}{wxfile}\\
+\helpref{wxTempFile}{wxtempfile}\\
+\helpref{wxTextFile}{wxtextfile}
+
+Functions: see \helpref{file functions}{filefunctions}.
+
+wxWindows provides some functions and classes to facilitate working with files.
+As usual, the accent is put on cross-platform features which explains, for
+example, the \helpref{wxTextFile}{wxtextfile} class which may be used to convert
+between different types of text files (DOS/Unix/Mac).
+
+wxFile may be used for low-level IO. It contains all usual functions to work
+with files (opening/closing, reading/writing, seeking...) but, compared to
+using standard C functions, brings error checking (in case of an error a message
+is logged using \helpref{wxLog}{wxlog} facilities) and closes the file
+automatically in destructor which may be quite convenient.
+
+wxTempFile is a very small file designed to make replacing the files contents
+safer - see its \helpref{documentation}{wxtempfile} for more details.
+
+wxTextFile is a general purpose class for working with small text files on line
+by line basis. It is especially well suited for working with configuration files
+and program source files. It can be also used to work with files with "non
+native" line termination characters and write them as "native" files if needed
+(in fact, the files may be written in any format).