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\& }{filename}, \param{const wxString\& }{description}}
 146
 147 Add another file to the report. If \arg{filename} is an absolute path, it is
 148 copied to a file in the debug report directory with the same name. Otherwise
 149 the file should already exist in this directory
 150
 151 \arg{description} only exists to be displayed to the user in the report summary
 152 shown by \helpref{wxDebugReportPreview}{wxdebugreportpreview}.
 153
 154 \wxheading{See also }
 155
 156 \helpref{GetDirectory()}{wxdebugreportgetdirectory},\\
 157 \helpref{AddText()}{wxdebugreportaddtext}
 158
 159
 160 \membersection{wxDebugReport::AddText}\label{wxdebugreportaddtext}
 161
 162 \func{bool}{AddText}{\param{const wxString\& }{filename}, \param{const wxString\& }{text}, \param{const wxString\& }{description}}
 163
 164 This is a convenient wrapper around \helpref{AddFile}{wxdebugreportaddfile}. It
 165 creates the file with the given \arg{name} and writes \arg{text} to it, then
 166 adds the file to the report. The \arg{filename} shouldn't contain the path.
 167
 168 Returns \true if file could be added successfully, \false if an IO error
 169 occurred.
 170
 171
 172 \membersection{wxDebugReport::DoAddCustomContext}\label{wxdebugreportdoaddcustomcontext}
 173
 174 \func{void}{DoAddCustomContext}{\param{wxXmlNode * }{nodeRoot}}
 175
 176 This function may be overridden to add arbitrary custom context to the XML
 177 context file created by \helpref{AddContext}{wxdebugreportaddcontext}. By
 178 default, it does nothing.
 179
 180
 181 \membersection{wxDebugReport::DoAddExceptionInfo}\label{wxdebugreportdoaddexceptioninfo}
 182
 183 \func{bool}{DoAddExceptionInfo}{\param{wxXmlNode* }{nodeContext}}
 184
 185 This function may be overridden to modify the contents of the exception tag in
 186 the XML context file.
 187
 188
 189 \membersection{wxDebugReport::DoAddLoadedModules}\label{wxdebugreportdoaddloadedmodules}
 190
 191 \func{bool}{DoAddLoadedModules}{\param{wxXmlNode* }{nodeModules}}
 192
 193 This function may be overridden to modify the contents of the modules tag in
 194 the XML context file.
 195
 196
 197 \membersection{wxDebugReport::DoAddSystemInfo}\label{wxdebugreportdoaddsysteminfo}
 198
 199 \func{bool}{DoAddSystemInfo}{\param{wxXmlNode* }{nodeSystemInfo}}
 200
 201 This function may be overridden to modify the contents of the system tag in
 202 the XML context file.
 203
 204
 205 \membersection{wxDebugReport::GetDirectory}\label{wxdebugreportgetdirectory}
 206
 207 \constfunc{const wxString\&}{GetDirectory}{\void}
 208
 209 Returns the name of the temporary directory used for the files in this report.
 210
 211 This method should be used to construct the full name of the files which you
 212 wish to add to the report using \helpref{AddFile}{wxdebugreportaddfile}.
 213
 214
 215 \membersection{wxDebugReport::GetFile}\label{wxdebugreportgetfile}
 216
 217 \constfunc{bool}{GetFile}{\param{size\_t }{n}, \param{wxString* }{name}, \param{wxString* }{desc}}
 218
 219 Retrieves the name (relative to
 220 \helpref{GetDirectory()}{wxdebugreportgetdirectory}) and the description of the
 221 file with the given index. If \arg{n} is greater than or equal to the number of
 222 filse, \false is returned.
 223
 224
 225 \membersection{wxDebugReport::GetFilesCount}\label{wxdebugreportgetfilescount}
 226
 227 \constfunc{size\_t}{GetFilesCount}{\void}
 228
 229 Gets the current number files in this report.
 230
 231
 232 \membersection{wxDebugReport::GetReportName}\label{wxdebugreportgetreportname}
 233
 234 \constfunc{wxString}{GetReportName}{\void}
 235
 236 Gets the name used as a base name for various files, by default
 237 \helpref{wxApp::GetAppName()}{wxappgetappname} is used.
 238
 239
 240 \membersection{wxDebugReport::IsOk}\label{wxdebugreportisok}
 241
 242 \constfunc{bool}{IsOk}{\void}
 243
 244 Returns \true if the object was successfully initialized. If this method returns
 245 \false the report can't be used.
 246
 247
 248 \membersection{wxDebugReport::Process}\label{wxdebugreportprocess}
 249
 250 \func{bool}{Process}{\void}
 251
 252 Processes this report: the base class simply notifies the user that the
 253 report has been generated. This is usually not enough -- instead you
 254 should override this method to do something more useful to you.
 255
 256
 257 \membersection{wxDebugReport::RemoveFile}\label{wxdebugreportremovefile}
 258
 259 \func{void}{RemoveFile}{\param{const wxString\& }{name}}
 260
 261 Removes the file from report: this is used by
 262 \helpref{wxDebugReportPreview}{wxdebugreportpreview} to allow the user to
 263 remove files potentially containing private information from the report.
 264
 265
 266 \membersection{wxDebugReport::Reset}\label{wxdebugreportreset}
 267
 268 \func{void}{Reset}{\void}
 269
 270 Resets the directory name we use. The object can't be used any more after
 271 this as it becomes uninitialized and invalid.
 272