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