docs/latex/wx/tempfile.tex

   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