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