git.saurik.com Git - wxWidgets.git/blame_incremental

... / ...

Commit	Line	Data
	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
	40	\wxheading{Include files}
	41
	42	<wx/file.h>
	43
	44	\wxheading{Library}
	45
	46	\helpref{wxBase}{librarieslist}
	47
	48	\wxheading{See also:}
	49
	50	\helpref{wxFile}{wxfile}\\
	51	\helpref{wxTempFileOutputStream}{wxtempfileoutputstream}
	52
	53	\latexignore{\rtfignore{\wxheading{Members}}}
	54
	55	\membersection{wxTempFile::wxTempFile}\label{wxtempfilewxtempfilector}
	56
	57	\func{}{wxTempFile}{\void}
	58
	59	Default constructor - \helpref{Open}{wxtempfileopen} must be used to open the
	60	file.
	61
	62	\membersection{wxTempFile::wxTempFile}\label{wxtempfilewxtempfile}
	63
	64	\func{}{wxTempFile}{\param{const wxString\& }{strName}}
	65
	66	Associates wxTempFile with the file to be replaced and opens it. You should use
	67	\helpref{IsOpened}{wxtempfileisopened} to verify if the constructor succeeded.
	68
	69	\membersection{wxTempFile::Open}\label{wxtempfileopen}
	70
	71	\func{bool}{Open}{\param{const wxString\& }{strName}}
	72
	73	Open the temporary file, returns {\tt true} on success, {\tt false} if an error
	74	occurred.
	75
	76	{\it strName} is the name of file to be replaced. The temporary file is always
	77	created in the directory where {\it strName} is. In particular, if
	78	{\it strName} doesn't include the path, it is created in the current directory
	79	and the program should have write access to it for the function to succeed.
	80
	81	\membersection{wxTempFile::IsOpened}\label{wxtempfileisopened}
	82
	83	\constfunc{bool}{IsOpened}{\void}
	84
	85	Returns {\tt true} if the file was successfully opened.
	86
	87	\membersection{wxTempFile::Length}\label{wxtempfilelength}
	88
	89	\constfunc{wxFileOffset}{Length}{\void}
	90
	91	Returns the length of the file.
	92
	93	\membersection{wxTempFile::Seek}\label{wxtempfileseek}
	94
	95	\func{wxFileOffset}{Seek}{\param{wxFileOffset }{ofs}, \param{wxSeekMode }{mode = wxFromStart}}
	96
	97	Seeks to the specified position.
	98
	99	\membersection{wxTempFile::Tell}\label{wxtempfiletell}
	100
	101	\constfunc{wxFileOffset}{Tell}{\void}
	102
	103	Returns the current position or wxInvalidOffset if file is not opened or if another
	104	error occurred.
	105
	106	\membersection{wxTempFile::Write}\label{wxtempfilewrite}
	107
	108	\func{bool}{Write}{\param{const void }{*p}, \param{size\_t }{n}}
	109
	110	Write to the file, return {\tt true} on success, {\tt false} on failure.
	111
	112	\membersection{wxTempFile::Write}\label{wxtempfilewrites}
	113
	114	\func{bool}{Write}{\param{const wxString\& }{str}, \param{const wxMBConv\&}{ conv = wxConvUTF8}}
	115
	116	Write to the file, return {\tt true} on success, {\tt false} on failure.
	117
	118	The second argument is only meaningful in Unicode build of wxWidgets when
	119	{\it conv} is used to convert {\it str} to multibyte representation.
	120
	121	\membersection{wxTempFile::Commit}\label{wxtempfilecommit}
	122
	123	\func{bool}{Commit}{\void}
	124
	125	Validate changes: deletes the old file of name m\_strName and renames the new
	126	file to the old name. Returns {\tt true} if both actions succeeded. If {\tt false} is
	127	returned it may unfortunately mean two quite different things: either that
	128	either the old file couldn't be deleted or that the new file couldn't be renamed
	129	to the old name.
	130
	131	\membersection{wxTempFile::Discard}\label{wxtempfilediscard}
	132
	133	\func{void}{Discard}{\void}
	134
	135	Discard changes: the old file contents is not changed, temporary file is
	136	deleted.
	137
	138	\membersection{wxTempFile::\destruct{wxTempFile}}\label{wxtempfiledtor}
	139
	140	\func{}{\destruct{wxTempFile}}{\void}
	141
	142	Destructor calls \helpref{Discard()}{wxtempfilediscard} if temporary file
	143	is still opened.
	144