some doc updates

[wxWidgets.git] / docs / latex / wx / debugrpt.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{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.