a7af285d1a
git-svn-id: https://svn.wxwidgets.org/svn/wx/wxWidgets/trunk@47777 c3d73ce0-8a6f-49c7-b76d-6d57e0e08775
277 lines
8.8 KiB
TeX
277 lines
8.8 KiB
TeX
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
|
|
%% Name: debugrpt.tex
|
|
%% Purpose: wxDebugReport documentation
|
|
%% Author: Vadim Zeitlin
|
|
%% Modified by:
|
|
%% Created: 2005-03-21
|
|
%% RCS-ID: $Id$
|
|
%% Copyright: (c) Vadim Zeitlin 2005
|
|
%% License: wxWindows license
|
|
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
|
|
|
|
\section{\class{wxDebugReport}}\label{wxdebugreport}
|
|
|
|
wxDebugReport is used to generate a debug report, containing information about
|
|
the program current state. It is usually used from
|
|
\helpref{wxApp::OnFatalException()}{wxapponfatalexception} as shown in the
|
|
\helpref{sample}{sampledebugrpt}.
|
|
|
|
A wxDebugReport object contains one or more files. A few of them can be created by the
|
|
class itself but more can be created from the outside and then added to the
|
|
report. Also note that several virtual functions may be overridden to further
|
|
customize the class behaviour.
|
|
|
|
Once a report is fully assembled, it can simply be left in the temporary
|
|
directory so that the user can email it to the developers (in which case you
|
|
should still use \helpref{wxDebugReportCompress}{wxdebugreportcompress} to
|
|
compress it in a single file) or uploaded to a Web server using
|
|
\helpref{wxDebugReportUpload}{wxdebugreportupload} (setting up the Web server
|
|
to accept uploads is your responsibility, of course). Other handlers, for example for
|
|
automatically emailing the report, can be defined as well but are not currently
|
|
included in wxWidgets.
|
|
|
|
\wxheading{Example of use}
|
|
|
|
\begin{verbatim}
|
|
wxDebugReport report;
|
|
wxDebugReportPreviewStd preview;
|
|
|
|
report.AddCurrentContext(); // could also use AddAll()
|
|
report.AddCurrentDump(); // to do both at once
|
|
|
|
if ( preview.Show(report) )
|
|
report.Process();
|
|
\end{verbatim}
|
|
|
|
\wxheading{Derived from}
|
|
|
|
No base class
|
|
|
|
\wxheading{Include files}
|
|
|
|
<wx/debugrpt.h>
|
|
|
|
\wxheading{Library}
|
|
|
|
\helpref{wxQa}{librarieslist}
|
|
|
|
\wxheading{Data structures}
|
|
|
|
This enum is used for functions that report either the current state
|
|
or the state during the last (fatal) exception:
|
|
|
|
\begin{verbatim}
|
|
enum wxDebugReport::Context
|
|
{
|
|
Context_Current,
|
|
Context_Exception
|
|
};
|
|
\end{verbatim}
|
|
|
|
\latexignore{\rtfignore{\wxheading{Members}}}
|
|
|
|
|
|
\membersection{wxDebugReport::wxDebugReport}\label{wxdebugreportwxdebugreport}
|
|
|
|
\func{}{wxDebugReport}{\void}
|
|
|
|
The constructor creates a temporary directory where the files that will
|
|
be included in the report are created. Use
|
|
\helpref{IsOk()}{wxdebugreportisok} to check for errors.
|
|
|
|
|
|
\membersection{wxDebugReport::\destruct{wxDebugReport}}\label{wxdebugreportdtor}
|
|
|
|
\func{}{\destruct{wxDebugReport}}{\void}
|
|
|
|
The destructor normally destroys the temporary directory created in the constructor
|
|
with all the files it contains. Call \helpref{Reset()}{wxdebugreportreset} to
|
|
prevent this from happening.
|
|
|
|
|
|
\membersection{wxDebugReport::AddAll}\label{wxdebugreportaddall}
|
|
|
|
\func{void}{AddAll}{\param{Context }{context = Context\_Exception}}
|
|
|
|
Adds all available information to the report. Currently this includes a
|
|
text (XML) file describing the process context and, under Win32, a minidump
|
|
file.
|
|
|
|
|
|
\membersection{wxDebugReport::AddContext}\label{wxdebugreportaddcontext}
|
|
|
|
\func{bool}{AddContext}{\param{Context }{ctx}}
|
|
|
|
Add an XML file containing the current or exception context and the
|
|
stack trace.
|
|
|
|
|
|
\membersection{wxDebugReport::AddCurrentContext}\label{wxdebugreportaddcurrentcontext}
|
|
|
|
\func{bool}{AddCurrentContext}{\void}
|
|
|
|
The same as \helpref{AddContext(Context\_Current)}{wxdebugreportaddcontext}.
|
|
|
|
|
|
\membersection{wxDebugReport::AddCurrentDump}\label{wxdebugreportaddcurrentdump}
|
|
|
|
\func{bool}{AddCurrentDump}{\void}
|
|
|
|
The same as \helpref{AddDump(Context\_Current)}{wxdebugreportadddump}.
|
|
|
|
|
|
\membersection{wxDebugReport::AddDump}\label{wxdebugreportadddump}
|
|
|
|
\func{bool}{AddDump}{\param{Context }{ctx}}
|
|
|
|
Adds the minidump file to the debug report.
|
|
|
|
Minidumps are only available under recent Win32 versions (\texttt{dbghlp32.dll}
|
|
can be installed under older systems to make minidumps available).
|
|
|
|
|
|
\membersection{wxDebugReport::AddExceptionContext}\label{wxdebugreportaddexceptioncontext}
|
|
|
|
\func{bool}{AddExceptionContext}{\void}
|
|
|
|
The same as \helpref{AddContext(Context\_Exception)}{wxdebugreportaddcontext}.
|
|
|
|
|
|
\membersection{wxDebugReport::AddExceptionDump}\label{wxdebugreportaddexceptiondump}
|
|
|
|
\func{bool}{AddExceptionDump}{\void}
|
|
|
|
The same as \helpref{AddDump(Context\_Exception)}{wxdebugreportadddump}.
|
|
|
|
|
|
\membersection{wxDebugReport::AddFile}\label{wxdebugreportaddfile}
|
|
|
|
\func{void}{AddFile}{\param{const wxString\& }{filename}, \param{const wxString\& }{description}}
|
|
|
|
Add another file to the report. If \arg{filename} is an absolute path, it is
|
|
copied to a file in the debug report directory with the same name. Otherwise
|
|
the file should already exist in this directory
|
|
|
|
\arg{description} only exists to be displayed to the user in the report summary
|
|
shown by \helpref{wxDebugReportPreview}{wxdebugreportpreview}.
|
|
|
|
\wxheading{See also }
|
|
|
|
\helpref{GetDirectory()}{wxdebugreportgetdirectory},\\
|
|
\helpref{AddText()}{wxdebugreportaddtext}
|
|
|
|
|
|
\membersection{wxDebugReport::AddText}\label{wxdebugreportaddtext}
|
|
|
|
\func{bool}{AddText}{\param{const wxString\& }{filename}, \param{const wxString\& }{text}, \param{const wxString\& }{description}}
|
|
|
|
This is a convenient wrapper around \helpref{AddFile}{wxdebugreportaddfile}. It
|
|
creates the file with the given \arg{name} and writes \arg{text} to it, then
|
|
adds the file to the report. The \arg{filename} shouldn't contain the path.
|
|
|
|
Returns \true if file could be added successfully, \false if an IO error
|
|
occurred.
|
|
|
|
|
|
\membersection{wxDebugReport::DoAddCustomContext}\label{wxdebugreportdoaddcustomcontext}
|
|
|
|
\func{void}{DoAddCustomContext}{\param{wxXmlNode * }{nodeRoot}}
|
|
|
|
This function may be overridden to add arbitrary custom context to the XML
|
|
context file created by \helpref{AddContext}{wxdebugreportaddcontext}. By
|
|
default, it does nothing.
|
|
|
|
|
|
\membersection{wxDebugReport::DoAddExceptionInfo}\label{wxdebugreportdoaddexceptioninfo}
|
|
|
|
\func{bool}{DoAddExceptionInfo}{\param{wxXmlNode* }{nodeContext}}
|
|
|
|
This function may be overridden to modify the contents of the exception tag in
|
|
the XML context file.
|
|
|
|
|
|
\membersection{wxDebugReport::DoAddLoadedModules}\label{wxdebugreportdoaddloadedmodules}
|
|
|
|
\func{bool}{DoAddLoadedModules}{\param{wxXmlNode* }{nodeModules}}
|
|
|
|
This function may be overridden to modify the contents of the modules tag in
|
|
the XML context file.
|
|
|
|
|
|
\membersection{wxDebugReport::DoAddSystemInfo}\label{wxdebugreportdoaddsysteminfo}
|
|
|
|
\func{bool}{DoAddSystemInfo}{\param{wxXmlNode* }{nodeSystemInfo}}
|
|
|
|
This function may be overridden to modify the contents of the system tag in
|
|
the XML context file.
|
|
|
|
|
|
\membersection{wxDebugReport::GetDirectory}\label{wxdebugreportgetdirectory}
|
|
|
|
\constfunc{const wxString\&}{GetDirectory}{\void}
|
|
|
|
Returns the name of the temporary directory used for the files in this report.
|
|
|
|
This method should be used to construct the full name of the files which you
|
|
wish to add to the report using \helpref{AddFile}{wxdebugreportaddfile}.
|
|
|
|
|
|
\membersection{wxDebugReport::GetFile}\label{wxdebugreportgetfile}
|
|
|
|
\constfunc{bool}{GetFile}{\param{size\_t }{n}, \param{wxString* }{name}, \param{wxString* }{desc}}
|
|
|
|
Retrieves the name (relative to
|
|
\helpref{GetDirectory()}{wxdebugreportgetdirectory}) and the description of the
|
|
file with the given index. If \arg{n} is greater than or equal to the number of
|
|
filse, \false is returned.
|
|
|
|
|
|
\membersection{wxDebugReport::GetFilesCount}\label{wxdebugreportgetfilescount}
|
|
|
|
\constfunc{size\_t}{GetFilesCount}{\void}
|
|
|
|
Gets the current number files in this report.
|
|
|
|
|
|
\membersection{wxDebugReport::GetReportName}\label{wxdebugreportgetreportname}
|
|
|
|
\constfunc{wxString}{GetReportName}{\void}
|
|
|
|
Gets the name used as a base name for various files, by default
|
|
\helpref{wxApp::GetAppName()}{wxappgetappname} is used.
|
|
|
|
|
|
\membersection{wxDebugReport::IsOk}\label{wxdebugreportisok}
|
|
|
|
\constfunc{bool}{IsOk}{\void}
|
|
|
|
Returns \true if the object was successfully initialized. If this method returns
|
|
\false the report can't be used.
|
|
|
|
|
|
\membersection{wxDebugReport::Process}\label{wxdebugreportprocess}
|
|
|
|
\func{bool}{Process}{\void}
|
|
|
|
Processes this report: the base class simply notifies the user that the
|
|
report has been generated. This is usually not enough -- instead you
|
|
should override this method to do something more useful to you.
|
|
|
|
|
|
\membersection{wxDebugReport::RemoveFile}\label{wxdebugreportremovefile}
|
|
|
|
\func{void}{RemoveFile}{\param{const wxString\& }{name}}
|
|
|
|
Removes the file from report: this is used by
|
|
\helpref{wxDebugReportPreview}{wxdebugreportpreview} to allow the user to
|
|
remove files potentially containing private information from the report.
|
|
|
|
|
|
\membersection{wxDebugReport::Reset}\label{wxdebugreportreset}
|
|
|
|
\func{void}{Reset}{\void}
|
|
|
|
Resets the directory name we use. The object can't be used any more after
|
|
this as it becomes uninitialized and invalid.
|
|
|