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

% 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{Include files}

<wx/file.h>

\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.
Commit	Line	Data
7f561143 VZ	1	% automatically generated by HelpGen from tempfile.tex at 10/Jan/99 19:24:44
	2	\section{\class{wxTempFile}}\label{wxtempfile}
	3
	4	wxTempFile provides a relatively safe way to replace the contents of the
	5	existing file. The name is explained by the fact that it may be also used as
	6	just a temporary file if you don't replace the old file contents.
	7
	8	Usually, when a program replaces the contents of some file it first opens it for
	9	writing, thus losing all of the old data and then starts recreating it. This
	10	approach is not very safe because during the regeneration of the file bad things
	11	may happen: the program may find that there is an internal error preventing it
	12	from completing file generation, the user may interrupt it (especially if file
	13	generation takes long time) and, finally, any other external interrupts (power
	14	supply failure or a disk error) will leave you without either the original file
	15	or the new one.
	16
	17	wxTempFile addresses this problem by creating a temporary file which is meant to
	18	replace the original file - but only after it is fully written. So, if the user
	19	interrupts the program during the file generation, the old file won't be lost.
	20	Also, if the program discovers itself that it doesn't want to replace the old
	21	file there is no problem - in fact, wxTempFile will {\bf not} replace the old
	22	file by default, you should explicitly call \helpref{Commit}{wxtempfilecommit}
	23	to do it. Calling \helpref{Discard}{wxtempfilediscard} explicitly discards any
	24	modifications: it closes and deletes the temporary file and leaves the original
	25	file unchanged. If you don't call neither of Commit() and Discard(), the
	26	destructor will call Discard() automatically.
	27
	28	To summarize: if you want to replace another file, create an instance of
	29	wxTempFile passing the name of the file to be replaced to the constructor (you
	30	may also use default constructor and pass the file name to
	31	\helpref{Open}{wxtempfileopen}). Then you can \helpref{write}{wxtempfilewrite}
	32	to wxTempFile using \helpref{wxFile}{wxfile}-like functions and later call
	33	Commit() to replace the old file (and close this one) or call Discard() to cancel
	34	the modifications.
	35
	36	\wxheading{Derived from}
	37
	38	No base class
	39
954b8ae6 JS	40	\wxheading{Include files}
	41
	42	<wx/file.h>
	43
7f561143 VZ	44	\wxheading{See also:}
	45
	46	\helpref{wxFile}{wxfile}
	47
	48	\latexignore{\rtfignore{\wxheading{Members}}}
	49
	50	\membersection{wxTempFile::wxTempFile}\label{wxtempfilewxtempfilector}
b2cf617c	51
7f561143 VZ	52	\func{}{wxTempFile}{\void}
	53
	54	Default constructor - \helpref{Open}{wxtempfileopen} must be used to open the
	55	file.
	56
	57	\membersection{wxTempFile::wxTempFile}\label{wxtempfilewxtempfile}
b2cf617c	58
7f561143 VZ	59	\func{}{wxTempFile}{\param{const wxString\& }{strName}}
7f561143 VZ	60
b2cf617c	61	Associates wxTempFile with the file to be replaced and opens it. You should use
7f561143 VZ	62	\helpref{IsOpened}{wxtempfileisopened} to verify if the constructor succeeded.
	63
	64	\membersection{wxTempFile::Open}\label{wxtempfileopen}
b2cf617c	65
7f561143 VZ	66	\func{bool}{Open}{\param{const wxString\& }{strName}}
	67
	68	Open the temporary file (strName is the name of file to be replaced), returns
	69	TRUE on success, FALSE if an error occured.
	70
	71	\membersection{wxTempFile::IsOpened}\label{wxtempfileisopened}
	72	\constfunc{bool}{IsOpened}{\void}
	73
	74	Returns TRUE if the file was successfully opened.
	75
	76	\membersection{wxTempFile::Write}\label{wxtempfilewrite}
b2cf617c	77
7f561143 VZ	78	\func{bool}{Write}{\param{const void }{*p}, \param{size\_t }{n}}
	79
	80	Write to the file, return TRUE on success, FALSE on failure.
	81
	82	\membersection{wxTempFile::Write}\label{wxtempfilewrites}
b2cf617c	83
7f561143 VZ	84	\func{bool}{Write}{\param{const wxString\& }{str}}
	85
	86	Write to the file, return TRUE on success, FALSE on failure.
	87
	88	\membersection{wxTempFile::Commit}\label{wxtempfilecommit}
b2cf617c	89
7f561143 VZ	90	\func{bool}{Commit}{\void}
	91
	92	Validate changes: deletes the old file of name m\_strName and renames the new
	93	file to the old name. Returns TRUE if both actions succeeded. If FALSE is
	94	returned it may unfortunately mean two quite different things: either that
	95	either the old file couldn't be deleted or that the new file couldn't be renamed
	96	to the old name.
	97
	98	\membersection{wxTempFile::Discard}\label{wxtempfilediscard}
b2cf617c	99
7f561143 VZ	100	\func{void}{Discard}{\void}
	101
	102	Discard changes: the old file contents is not changed, temporary file is
	103	deleted.
	104
	105	\membersection{wxTempFile::\destruct{wxTempFile}}\label{wxtempfiledtor}
b2cf617c	106
7f561143 VZ	107	\func{}{\destruct{wxTempFile}}{\void}
	108
	109	Destructor calls \helpref{Discard()}{wxtempfilediscard} if temporary file
	110	is still opened.
	111