1 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
3 %% Purpose: wxDebugReport documentation
4 %% Author: Vadim Zeitlin
8 %% Copyright: (c) Vadim Zeitlin 2005
9 %% License: wxWindows license
10 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
12 \section{\class{wxDebugReport
}}\label{wxdebugreport
}
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
}.
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.
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.
33 \wxheading{Example of use
}
37 wxDebugReportPreviewStd preview;
39 report.AddCurrentContext(); // could also use AddAll()
40 report.AddCurrentDump(); // to do both at once
42 if ( preview.Show(
report) )
46 \wxheading{Derived from
}
50 \wxheading{Include files
}
54 \wxheading{Data structures
}
56 This enum used for the functions which may
report either the current state
57 or the state during the last (fatal) exception:
59 enum wxDebugReport::Context
66 \latexignore{\rtfignore{\wxheading{Members
}}}
69 \membersection{wxDebugReport::wxDebugReport
}\label{wxdebugreportwxdebugreport
}
71 \func{}{wxDebugReport
}{\void}
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.
78 \membersection{wxDebugReport::
\destruct{wxDebugReport
}}\label{wxdebugreportdtor
}
80 \func{}{\destruct{wxDebugReport
}}{\void}
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.
87 \membersection{wxDebugReport::AddAll
}\label{wxdebugreportaddall
}
89 \func{void
}{AddAll
}{\param{Context
}{context = Context
\_Exception}}
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
96 \membersection{wxDebugReport::AddContext
}\label{wxdebugreportaddcontext
}
98 \func{bool
}{AddContext
}{\param{Context
}{ctx
}}
100 Add an XML file containing the current or exception context and the
104 \membersection{wxDebugReport::AddCurrentContext
}\label{wxdebugreportaddcurrentcontext
}
106 \func{bool
}{AddCurrentContext
}{\void}
108 Same as
\helpref{AddContext(Context
\_Current)
}{wxdebugreportaddcontext
}.
111 \membersection{wxDebugReport::AddCurrentDump
}\label{wxdebugreportaddcurrentdump
}
113 \func{bool
}{AddCurrentDump
}{\void}
115 Same as
\helpref{AddDump(Context
\_Current)
}{wxdebugreportadddump
}.
118 \membersection{wxDebugReport::AddDump
}\label{wxdebugreportadddump
}
120 \func{bool
}{AddDump
}{\param{Context
}{ctx
}}
122 Adds minidump file to the debug
report.
124 Minidumps are only available under recent Win32 versions (
\texttt{dbghlp32.dll
}
125 can be installed under older systems to make minidumps available).
128 \membersection{wxDebugReport::AddExceptionContext
}\label{wxdebugreportaddexceptioncontext
}
130 \func{bool
}{AddExceptionContext
}{\void}
132 Same as
\helpref{AddContext(Context
\_Exception)
}{wxdebugreportaddcontext
}.
135 \membersection{wxDebugReport::AddExceptionDump
}\label{wxdebugreportaddexceptiondump
}
137 \func{bool
}{AddExceptionDump
}{\void}
139 Same as
\helpref{AddDump(Context
\_Exception)
}{wxdebugreportadddump
}.
142 \membersection{wxDebugReport::AddFile
}\label{wxdebugreportaddfile
}
144 \func{void
}{AddFile
}{\param{const wxString\&
}{name
},
\param{const wxString\&
}{description
}}
146 Add another file to the
report: the file must already exist on disk. Its name
147 is relative to
\helpref{GetDirectory()
}{wxdebugreportgetdirectory
}.
149 \arg{description
} only exists to be shown to the user in the
report summary
150 shown by
\helpref{wxDebugReportPreview
}{wxdebugreportpreview
}.
153 \membersection{wxDebugReport::DoAddCustomContext
}\label{wxdebugreportdoaddcustomcontext
}
155 \func{void
}{DoAddCustomContext
}{\param{wxXmlNode *
}{nodeRoot
}}
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.
162 \membersection{wxDebugReport::DoAddExceptionInfo
}\label{wxdebugreportdoaddexceptioninfo
}
164 \func{bool
}{DoAddExceptionInfo
}{\param{wxXmlNode*
}{nodeContext
}}
166 This function may be overridden to modify the contents of the exception tag in
167 the XML context file.
170 \membersection{wxDebugReport::DoAddLoadedModules
}\label{wxdebugreportdoaddloadedmodules
}
172 \func{bool
}{DoAddLoadedModules
}{\param{wxXmlNode*
}{nodeModules
}}
174 This function may be overridden to modify the contents of the modules tag in
175 the XML context file.
178 \membersection{wxDebugReport::DoAddSystemInfo
}\label{wxdebugreportdoaddsysteminfo
}
180 \func{bool
}{DoAddSystemInfo
}{\param{wxXmlNode*
}{nodeSystemInfo
}}
182 This function may be overridden to modify the contents of the system tag in
183 the XML context file.
186 \membersection{wxDebugReport::GetDirectory
}\label{wxdebugreportgetdirectory
}
188 \constfunc{const wxString\&
}{GetDirectory
}{\void}
190 Return the name of the temporary directory used for the files in this
report.
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
}.
196 \membersection{wxDebugReport::GetFile
}\label{wxdebugreportgetfile
}
198 \constfunc{bool
}{GetFile
}{\param{size
\_t }{n
},
\param{wxString*
}{name
},
\param{wxString*
}{desc
}}
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.
206 \membersection{wxDebugReport::GetFilesCount
}\label{wxdebugreportgetfilescount
}
208 \constfunc{size
\_t}{GetFilesCount
}{\void}
210 Get the current number files in this
report.
213 \membersection{wxDebugReport::GetReportName
}\label{wxdebugreportgetreportname
}
215 \constfunc{wxString
}{GetReportName
}{\void}
217 Get the name used as base name for various files, by default
218 \helpref{wxApp::GetAppName()
}{wxappgetappname
} is used.
221 \membersection{wxDebugReport::IsOk
}\label{wxdebugreportisok
}
223 \constfunc{bool
}{IsOk
}{\void}
225 Return
\true if the object was successfully initialized, if this method returns
226 \false the
report can't be used.
229 \membersection{wxDebugReport::Process
}\label{wxdebugreportprocess
}
231 \func{bool
}{Process
}{\void}
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.
238 \membersection{wxDebugReport::RemoveFile
}\label{wxdebugreportremovefile
}
240 \func{void
}{RemoveFile
}{\param{const wxString\&
}{name
}}
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.
247 \membersection{wxDebugReport::Reset
}\label{wxdebugreportreset
}
249 \func{void
}{Reset
}{\void}
251 Reset the directory name we use, the object can't be used any more after
252 this as it becomes invalid/uninitialized.