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 wxDebugReport 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 report is fully assembled, it can be simply 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, e.g. 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 used for the functions which may report either the current state
  57 or the state during the last (fatal) exception:
  58 \begin{verbatim}
  59 enum wxDebugReport::Context
  60 {
  61     Context_Current,
  62     Context_Exception
  63 };
  64 \end{verbatim}
  65
  66 \latexignore{\rtfignore{\wxheading{Members}}}
  67
  68
  69 \membersection{wxDebugReport::wxDebugReport}\label{wxdebugreportwxdebugreport}
  70
  71 \func{}{wxDebugReport}{\void}
  72
  73 Constructor creates a temporary directory where the files which will
  74 be included in the report are created. Use
  75 \helpref{IsOk()}{wxdebugreportisok} to check for errors.
  76
  77
  78 \membersection{wxDebugReport::\destruct{wxDebugReport}}\label{wxdebugreportdtor}
  79
  80 \func{}{\destruct{wxDebugReport}}{\void}
  81
  82 Destructor normally destroys the temporary directory created in the constructor
  83 with all the files it contains, call \helpref{Reset()}{wxdebugreportreset} to
  84 prevent this from happening.
  85
  86
  87 \membersection{wxDebugReport::AddAll}\label{wxdebugreportaddall}
  88
  89 \func{void}{AddAll}{\param{Context }{context = Context\_Exception}}
  90
  91 Add all available information to the report. Currently this includes a
  92 text (XML) file describing the process context and, under Win32, a minidump
  93 file.
  94
  95
  96 \membersection{wxDebugReport::AddContext}\label{wxdebugreportaddcontext}
  97
  98 \func{bool}{AddContext}{\param{Context }{ctx}}
  99
 100 Add an XML file containing the current or exception context and the
 101 stack trace.
 102
 103
 104 \membersection{wxDebugReport::AddCurrentContext}\label{wxdebugreportaddcurrentcontext}
 105
 106 \func{bool}{AddCurrentContext}{\void}
 107
 108 Same as \helpref{AddContext(Context\_Current)}{wxdebugreportaddcontext}.
 109
 110
 111 \membersection{wxDebugReport::AddCurrentDump}\label{wxdebugreportaddcurrentdump}
 112
 113 \func{bool}{AddCurrentDump}{\void}
 114
 115 Same as \helpref{AddDump(Context\_Current)}{wxdebugreportadddump}.
 116
 117
 118 \membersection{wxDebugReport::AddDump}\label{wxdebugreportadddump}
 119
 120 \func{bool}{AddDump}{\param{Context }{ctx}}
 121
 122 Adds minidump file to the debug report.
 123
 124 Minidumps are only available under recent Win32 versions (\texttt{dbghlp32.dll}
 125 can be installed under older systems to make minidumps available).
 126
 127
 128 \membersection{wxDebugReport::AddExceptionContext}\label{wxdebugreportaddexceptioncontext}
 129
 130 \func{bool}{AddExceptionContext}{\void}
 131
 132 Same as \helpref{AddContext(Context\_Exception)}{wxdebugreportaddcontext}.
 133
 134
 135 \membersection{wxDebugReport::AddExceptionDump}\label{wxdebugreportaddexceptiondump}
 136
 137 \func{bool}{AddExceptionDump}{\void}
 138
 139 Same as \helpref{AddDump(Context\_Exception)}{wxdebugreportadddump}.
 140
 141
 142 \membersection{wxDebugReport::AddFile}\label{wxdebugreportaddfile}
 143
 144 \func{void}{AddFile}{\param{const wxString\& }{name}, \param{const wxString\& }{description}}
 145
 146 Add another file to the report: the file must already exist on disk. Its name
 147 is relative to \helpref{GetDirectory()}{wxdebugreportgetdirectory}.
 148
 149 \arg{description} only exists to be shown to the user in the report summary
 150 shown by \helpref{wxDebugReportPreview}{wxdebugreportpreview}.
 151
 152
 153 \membersection{wxDebugReport::DoAddCustomContext}\label{wxdebugreportdoaddcustomcontext}
 154
 155 \func{void}{DoAddCustomContext}{\param{wxXmlNode * }{nodeRoot}}
 156
 157 This function may be overridden to add arbitrary custom context to the XML
 158 context file created by \helpref{AddContext}{wxdebugreportaddcontext}. By
 159 default, it does nothing.
 160
 161
 162 \membersection{wxDebugReport::DoAddExceptionInfo}\label{wxdebugreportdoaddexceptioninfo}
 163
 164 \func{bool}{DoAddExceptionInfo}{\param{wxXmlNode* }{nodeContext}}
 165
 166 This function may be overridden to modify the contents of the exception tag in
 167 the XML context file.
 168
 169
 170 \membersection{wxDebugReport::DoAddLoadedModules}\label{wxdebugreportdoaddloadedmodules}
 171
 172 \func{bool}{DoAddLoadedModules}{\param{wxXmlNode* }{nodeModules}}
 173
 174 This function may be overridden to modify the contents of the modules tag in
 175 the XML context file.
 176
 177
 178 \membersection{wxDebugReport::DoAddSystemInfo}\label{wxdebugreportdoaddsysteminfo}
 179
 180 \func{bool}{DoAddSystemInfo}{\param{wxXmlNode* }{nodeSystemInfo}}
 181
 182 This function may be overridden to modify the contents of the system tag in
 183 the XML context file.
 184
 185
 186 \membersection{wxDebugReport::GetDirectory}\label{wxdebugreportgetdirectory}
 187
 188 \constfunc{const wxString\&}{GetDirectory}{\void}
 189
 190 Return the name of the temporary directory used for the files in this report.
 191
 192 This method should be used to construct the full name of the files which you
 193 wish to add to the report using \helpref{AddFile}{wxdebugreportaddfile}.
 194
 195
 196 \membersection{wxDebugReport::GetFile}\label{wxdebugreportgetfile}
 197
 198 \constfunc{bool}{GetFile}{\param{size\_t }{n}, \param{wxString* }{name}, \param{wxString* }{desc}}
 199
 200 Retrieve the name (relative to
 201 \helpref{GetDirectory()}{wxdebugreportgetdirectory}) and the description of the
 202 file with the given index. If \arg{n} is greater than or equal to the number of
 203 filse, \false is returned.
 204
 205
 206 \membersection{wxDebugReport::GetFilesCount}\label{wxdebugreportgetfilescount}
 207
 208 \constfunc{size\_t}{GetFilesCount}{\void}
 209
 210 Get the current number files in this report.
 211
 212
 213 \membersection{wxDebugReport::GetReportName}\label{wxdebugreportgetreportname}
 214
 215 \constfunc{wxString}{GetReportName}{\void}
 216
 217 Get the name used as base name for various files, by default
 218 \helpref{wxApp::GetAppName()}{wxappgetappname} is used.
 219
 220
 221 \membersection{wxDebugReport::IsOk}\label{wxdebugreportisok}
 222
 223 \constfunc{bool}{IsOk}{\void}
 224
 225 Return \true if the object was successfully initialized, if this method returns
 226 \false the report can't be used.
 227
 228
 229 \membersection{wxDebugReport::Process}\label{wxdebugreportprocess}
 230
 231 \func{bool}{Process}{\void}
 232
 233 Process this report: the base class simply notifies the user that the
 234 report has been generated, this is usually not enough -- instead you
 235 should override this method to do something more useful to you.
 236
 237
 238 \membersection{wxDebugReport::RemoveFile}\label{wxdebugreportremovefile}
 239
 240 \func{void}{RemoveFile}{\param{const wxString\& }{name}}
 241
 242 Remove the file from report: this is used by
 243 \helpref{wxDebugReportPreview}{wxdebugreportpreview} to allow the user to
 244 remove files potentially containing private information from the report.
 245
 246
 247 \membersection{wxDebugReport::Reset}\label{wxdebugreportreset}
 248
 249 \func{void}{Reset}{\void}
 250
 251 Reset the directory name we use, the object can't be used any more after
 252 this as it becomes invalid/uninitialized.
 253