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