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: debugrpt.tex 34436 2005-05-31 09:20:43Z JS $ 8%% Copyright: (c) Vadim Zeitlin 2005 9%% License: wxWindows license 10%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% 11 12\section{\class{wxDebugReport}}\label{wxdebugreport} 13 14wxDebugReport is used to generate a debug report, containing information about 15the program current state. It is usually used from 16\helpref{wxApp::OnFatalException()}{wxapponfatalexception} as shown in the 17\helpref{sample}{sampledebugrpt}. 18 19A wxDebugReport object contains one or more files. A few of them can be created by the 20class itself but more can be created from the outside and then added to the 21report. Also note that several virtual functions may be overridden to further 22customize the class behaviour. 23 24Once a report is fully assembled, it can simply be left in the temporary 25directory so that the user can email it to the developers (in which case you 26should still use \helpref{wxDebugReportCompress}{wxdebugreportcompress} to 27compress it in a single file) or uploaded to a Web server using 28\helpref{wxDebugReportUpload}{wxdebugreportupload} (setting up the Web server 29to accept uploads is your responsibility, of course). Other handlers, for example for 30automatically emailing the report, can be defined as well but are not currently 31included 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 48No base class 49 50\wxheading{Include files} 51 52<wx/debugrpt.h> 53 54\wxheading{Data structures} 55 56This enum is used for functions that report either the current state 57or the state during the last (fatal) exception: 58 59\begin{verbatim} 60enum 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 74The constructor creates a temporary directory where the files that will 75be 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 83The destructor normally destroys the temporary directory created in the constructor 84with all the files it contains. Call \helpref{Reset()}{wxdebugreportreset} to 85prevent this from happening. 86 87 88\membersection{wxDebugReport::AddAll}\label{wxdebugreportaddall} 89 90\func{void}{AddAll}{\param{Context }{context = Context\_Exception}} 91 92Adds all available information to the report. Currently this includes a 93text (XML) file describing the process context and, under Win32, a minidump 94file. 95 96 97\membersection{wxDebugReport::AddContext}\label{wxdebugreportaddcontext} 98 99\func{bool}{AddContext}{\param{Context }{ctx}} 100 101Add an XML file containing the current or exception context and the 102stack trace. 103 104 105\membersection{wxDebugReport::AddCurrentContext}\label{wxdebugreportaddcurrentcontext} 106 107\func{bool}{AddCurrentContext}{\void} 108 109The same as \helpref{AddContext(Context\_Current)}{wxdebugreportaddcontext}. 110 111 112\membersection{wxDebugReport::AddCurrentDump}\label{wxdebugreportaddcurrentdump} 113 114\func{bool}{AddCurrentDump}{\void} 115 116The same as \helpref{AddDump(Context\_Current)}{wxdebugreportadddump}. 117 118 119\membersection{wxDebugReport::AddDump}\label{wxdebugreportadddump} 120 121\func{bool}{AddDump}{\param{Context }{ctx}} 122 123Adds the minidump file to the debug report. 124 125Minidumps are only available under recent Win32 versions (\texttt{dbghlp32.dll} 126can be installed under older systems to make minidumps available). 127 128 129\membersection{wxDebugReport::AddExceptionContext}\label{wxdebugreportaddexceptioncontext} 130 131\func{bool}{AddExceptionContext}{\void} 132 133The same as \helpref{AddContext(Context\_Exception)}{wxdebugreportaddcontext}. 134 135 136\membersection{wxDebugReport::AddExceptionDump}\label{wxdebugreportaddexceptiondump} 137 138\func{bool}{AddExceptionDump}{\void} 139 140The 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 147Add another file to the report. If \arg{filename} is an absolute path, it is 148copied to a file in the debug report directory with the same name. Otherwise 149the file should already exist in this directory 150 151\arg{description} only exists to be displayed to the user in the report summary 152shown 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 164This is a convenient wrapper around \helpref{AddFile}{wxdebugreportaddfile}. It 165creates the file with the given \arg{name} and writes \arg{text} to it, then 166adds the file to the report. The \arg{filename} shouldn't contain the path. 167 168Returns \true if file could be added successfully, \false if an IO error 169occurred. 170 171 172\membersection{wxDebugReport::DoAddCustomContext}\label{wxdebugreportdoaddcustomcontext} 173 174\func{void}{DoAddCustomContext}{\param{wxXmlNode * }{nodeRoot}} 175 176This function may be overridden to add arbitrary custom context to the XML 177context file created by \helpref{AddContext}{wxdebugreportaddcontext}. By 178default, it does nothing. 179 180 181\membersection{wxDebugReport::DoAddExceptionInfo}\label{wxdebugreportdoaddexceptioninfo} 182 183\func{bool}{DoAddExceptionInfo}{\param{wxXmlNode* }{nodeContext}} 184 185This function may be overridden to modify the contents of the exception tag in 186the XML context file. 187 188 189\membersection{wxDebugReport::DoAddLoadedModules}\label{wxdebugreportdoaddloadedmodules} 190 191\func{bool}{DoAddLoadedModules}{\param{wxXmlNode* }{nodeModules}} 192 193This function may be overridden to modify the contents of the modules tag in 194the XML context file. 195 196 197\membersection{wxDebugReport::DoAddSystemInfo}\label{wxdebugreportdoaddsysteminfo} 198 199\func{bool}{DoAddSystemInfo}{\param{wxXmlNode* }{nodeSystemInfo}} 200 201This function may be overridden to modify the contents of the system tag in 202the XML context file. 203 204 205\membersection{wxDebugReport::GetDirectory}\label{wxdebugreportgetdirectory} 206 207\constfunc{const wxString\&}{GetDirectory}{\void} 208 209Returns the name of the temporary directory used for the files in this report. 210 211This method should be used to construct the full name of the files which you 212wish 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 219Retrieves the name (relative to 220\helpref{GetDirectory()}{wxdebugreportgetdirectory}) and the description of the 221file with the given index. If \arg{n} is greater than or equal to the number of 222filse, \false is returned. 223 224 225\membersection{wxDebugReport::GetFilesCount}\label{wxdebugreportgetfilescount} 226 227\constfunc{size\_t}{GetFilesCount}{\void} 228 229Gets the current number files in this report. 230 231 232\membersection{wxDebugReport::GetReportName}\label{wxdebugreportgetreportname} 233 234\constfunc{wxString}{GetReportName}{\void} 235 236Gets 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 244Returns \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 252Processes this report: the base class simply notifies the user that the 253report has been generated. This is usually not enough -- instead you 254should 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 261Removes the file from report: this is used by 262\helpref{wxDebugReportPreview}{wxdebugreportpreview} to allow the user to 263remove files potentially containing private information from the report. 264 265 266\membersection{wxDebugReport::Reset}\label{wxdebugreportreset} 267 268\func{void}{Reset}{\void} 269 270Resets the directory name we use. The object can't be used any more after 271this as it becomes uninitialized and invalid. 272 273