docs/latex/wx/debugrpt.tex

   1 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
   2 %% Name:        debugrpt.tex
   3 %% Purpose:     wxDebugReport documentation
   4 %% Author:      Vadim Zeitlin
   5 %% Modified by:
   6 %% Created:     2005-03-21
   7 %% RCS-ID:      $Id$
   8 %% Copyright:   (c) Vadim Zeitlin 2005
   9 %% License:     wxWindows license
  10 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
  11
  12 \section{\class{wxDebugReport}}\label{wxdebugreport}
  13
  14 wxDebugReport is used to generate a debug report, containing information about
  15 the program current state. It is usually used from
  16 \helpref{wxApp::OnFatalException()}{wxapponfatalexception} as shown in the
  17 \helpref{sample}{sampledebugrpt}.
  18
  19 A wxDebugReport object contains one or more files. A few of them can be created by the
  20 class itself but more can be created from the outside and then added to the
  21 report. Also note that several virtual functions may be overridden to further
  22 customize the class behaviour.
  23
  24 Once a report is fully assembled, it can simply be left in the temporary
  25 directory so that the user can email it to the developers (in which case you
  26 should still use \helpref{wxDebugReportCompress}{wxdebugreportcompress} to
  27 compress it in a single file) or uploaded to a Web server using
  28 \helpref{wxDebugReportUpload}{wxdebugreportupload} (setting up the Web server
  29 to accept uploads is your responsibility, of course). Other handlers, for example for
  30 automatically emailing the report, can be defined as well but are not currently
  31 included in wxWidgets.
  32
  33 \wxheading{Example of use}
  34
  35 \begin{verbatim}
  36     wxDebugReport report;
  37     wxDebugReportPreviewStd preview;
  38
  39     report.AddCurrentContext();  // could also use AddAll()
  40     report.AddCurrentDump();     // to do both at once
  41
  42     if ( preview.Show(report) )
  43         report.Process();
  44 \end{verbatim}
  45
  46 \wxheading{Derived from}
  47
  48 No base class
  49
  50 \wxheading{Include files}
  51
  52 <wx/debugrpt.h>
  53
  54 \wxheading{Data structures}
  55
  56 This enum is used for functions that report either the current state
  57 or the state during the last (fatal) exception:
  58
  59 \begin{verbatim}
  60 enum wxDebugReport::Context
  61 {
  62     Context_Current,
  63     Context_Exception
  64 };
  65 \end{verbatim}
  66
  67 \latexignore{\rtfignore{\wxheading{Members}}}
  68
  69
  70 \membersection{wxDebugReport::wxDebugReport}\label{wxdebugreportwxdebugreport}
  71
  72 \func{}{wxDebugReport}{\void}
  73
  74 The constructor creates a temporary directory where the files that will
  75 be included in the report are created. Use
  76 \helpref{IsOk()}{wxdebugreportisok} to check for errors.
  77
  78
  79 \membersection{wxDebugReport::\destruct{wxDebugReport}}\label{wxdebugreportdtor}
  80
  81 \func{}{\destruct{wxDebugReport}}{\void}
  82
  83 The destructor normally destroys the temporary directory created in the constructor
  84 with all the files it contains. Call \helpref{Reset()}{wxdebugreportreset} to
  85 prevent this from happening.
  86
  87
  88 \membersection{wxDebugReport::AddAll}\label{wxdebugreportaddall}
  89
  90 \func{void}{AddAll}{\param{Context }{context = Context\_Exception}}
  91
  92 Adds all available information to the report. Currently this includes a
  93 text (XML) file describing the process context and, under Win32, a minidump
  94 file.
  95
  96
  97 \membersection{wxDebugReport::AddContext}\label{wxdebugreportaddcontext}
  98
  99 \func{bool}{AddContext}{\param{Context }{ctx}}
 100
 101 Add an XML file containing the current or exception context and the
 102 stack trace.
 103
 104
 105 \membersection{wxDebugReport::AddCurrentContext}\label{wxdebugreportaddcurrentcontext}
 106
 107 \func{bool}{AddCurrentContext}{\void}
 108
 109 The same as \helpref{AddContext(Context\_Current)}{wxdebugreportaddcontext}.
 110
 111
 112 \membersection{wxDebugReport::AddCurrentDump}\label{wxdebugreportaddcurrentdump}
 113
 114 \func{bool}{AddCurrentDump}{\void}
 115
 116 The same as \helpref{AddDump(Context\_Current)}{wxdebugreportadddump}.
 117
 118
 119 \membersection{wxDebugReport::AddDump}\label{wxdebugreportadddump}
 120
 121 \func{bool}{AddDump}{\param{Context }{ctx}}
 122
 123 Adds the minidump file to the debug report.
 124
 125 Minidumps are only available under recent Win32 versions (\texttt{dbghlp32.dll}
 126 can be installed under older systems to make minidumps available).
 127
 128
 129 \membersection{wxDebugReport::AddExceptionContext}\label{wxdebugreportaddexceptioncontext}
 130
 131 \func{bool}{AddExceptionContext}{\void}
 132
 133 The same as \helpref{AddContext(Context\_Exception)}{wxdebugreportaddcontext}.
 134
 135
 136 \membersection{wxDebugReport::AddExceptionDump}\label{wxdebugreportaddexceptiondump}
 137
 138 \func{bool}{AddExceptionDump}{\void}
 139
 140 The same as \helpref{AddDump(Context\_Exception)}{wxdebugreportadddump}.
 141
 142
 143 \membersection{wxDebugReport::AddFile}\label{wxdebugreportaddfile}
 144
 145 \func{void}{AddFile}{\param{const wxString\& }{name}, \param{const wxString\& }{description}}
 146
 147 Add another file to the report: the file must already exist on disk. Its name
 148 is relative to \helpref{GetDirectory()}{wxdebugreportgetdirectory}.
 149
 150 \arg{description} only exists to be shown to the user in the report summary
 151 shown by \helpref{wxDebugReportPreview}{wxdebugreportpreview}.
 152
 153
 154 \membersection{wxDebugReport::AddText}\label{wxdebugreportaddtext}
 155
 156 \func{bool}{AddText}{\param{const wxString\& }{name}, \param{const wxString\& }{text}, \param{const wxString\& }{description}}
 157
 158 This is a convenient wrapper around \helpref{AddFile}{wxdebugreportaddfile}. It
 159 creates the file with the given \arg{name} and writes \arg{text} to it, then
 160 adds the file to the report.
 161
 162 Returns \true if file could be added successfully, \false if an IO error
 163 occured.
 164
 165
 166 \membersection{wxDebugReport::DoAddCustomContext}\label{wxdebugreportdoaddcustomcontext}
 167
 168 \func{void}{DoAddCustomContext}{\param{wxXmlNode * }{nodeRoot}}
 169
 170 This function may be overridden to add arbitrary custom context to the XML
 171 context file created by \helpref{AddContext}{wxdebugreportaddcontext}. By
 172 default, it does nothing.
 173
 174
 175 \membersection{wxDebugReport::DoAddExceptionInfo}\label{wxdebugreportdoaddexceptioninfo}
 176
 177 \func{bool}{DoAddExceptionInfo}{\param{wxXmlNode* }{nodeContext}}
 178
 179 This function may be overridden to modify the contents of the exception tag in
 180 the XML context file.
 181
 182
 183 \membersection{wxDebugReport::DoAddLoadedModules}\label{wxdebugreportdoaddloadedmodules}
 184
 185 \func{bool}{DoAddLoadedModules}{\param{wxXmlNode* }{nodeModules}}
 186
 187 This function may be overridden to modify the contents of the modules tag in
 188 the XML context file.
 189
 190
 191 \membersection{wxDebugReport::DoAddSystemInfo}\label{wxdebugreportdoaddsysteminfo}
 192
 193 \func{bool}{DoAddSystemInfo}{\param{wxXmlNode* }{nodeSystemInfo}}
 194
 195 This function may be overridden to modify the contents of the system tag in
 196 the XML context file.
 197
 198
 199 \membersection{wxDebugReport::GetDirectory}\label{wxdebugreportgetdirectory}
 200
 201 \constfunc{const wxString\&}{GetDirectory}{\void}
 202
 203 Returns the name of the temporary directory used for the files in this report.
 204
 205 This method should be used to construct the full name of the files which you
 206 wish to add to the report using \helpref{AddFile}{wxdebugreportaddfile}.
 207
 208
 209 \membersection{wxDebugReport::GetFile}\label{wxdebugreportgetfile}
 210
 211 \constfunc{bool}{GetFile}{\param{size\_t }{n}, \param{wxString* }{name}, \param{wxString* }{desc}}
 212
 213 Retrieves the name (relative to
 214 \helpref{GetDirectory()}{wxdebugreportgetdirectory}) and the description of the
 215 file with the given index. If \arg{n} is greater than or equal to the number of
 216 filse, \false is returned.
 217
 218
 219 \membersection{wxDebugReport::GetFilesCount}\label{wxdebugreportgetfilescount}
 220
 221 \constfunc{size\_t}{GetFilesCount}{\void}
 222
 223 Gets the current number files in this report.
 224
 225
 226 \membersection{wxDebugReport::GetReportName}\label{wxdebugreportgetreportname}
 227
 228 \constfunc{wxString}{GetReportName}{\void}
 229
 230 Gets the name used as a base name for various files, by default
 231 \helpref{wxApp::GetAppName()}{wxappgetappname} is used.
 232
 233
 234 \membersection{wxDebugReport::IsOk}\label{wxdebugreportisok}
 235
 236 \constfunc{bool}{IsOk}{\void}
 237
 238 Returns \true if the object was successfully initialized. If this method returns
 239 \false the report can't be used.
 240
 241
 242 \membersection{wxDebugReport::Process}\label{wxdebugreportprocess}
 243
 244 \func{bool}{Process}{\void}
 245
 246 Processes this report: the base class simply notifies the user that the
 247 report has been generated. This is usually not enough -- instead you
 248 should override this method to do something more useful to you.
 249
 250
 251 \membersection{wxDebugReport::RemoveFile}\label{wxdebugreportremovefile}
 252
 253 \func{void}{RemoveFile}{\param{const wxString\& }{name}}
 254
 255 Removes the file from report: this is used by
 256 \helpref{wxDebugReportPreview}{wxdebugreportpreview} to allow the user to
 257 remove files potentially containing private information from the report.
 258
 259
 260 \membersection{wxDebugReport::Reset}\label{wxdebugreportreset}
 261
 262 \func{void}{Reset}{\void}
 263
 264 Resets the directory name we use. The object can't be used any more after
 265 this as it becomes uninitialized and invalid.
 266