From 4e0e7d3935aadb591b643a1123b7508b09814193 Mon Sep 17 00:00:00 2001 From: Vadim Zeitlin Date: Mon, 21 Mar 2005 18:28:27 +0000 Subject: [PATCH] documented wxDebugReport and related classes git-svn-id: https://svn.wxwidgets.org/svn/wx/wxWidgets/trunk@32959 c3d73ce0-8a6f-49c7-b76d-6d57e0e08775 --- docs/latex/wx/classes.tex | 5 + docs/latex/wx/debugrpt.tex | 253 +++++++++++++++++++++++++++++++ docs/latex/wx/debugrptpvw.tex | 59 +++++++ docs/latex/wx/debugrptpvwstd.tex | 46 ++++++ docs/latex/wx/debugrptup.tex | 51 +++++++ docs/latex/wx/debugrptz.tex | 40 +++++ 6 files changed, 454 insertions(+) create mode 100644 docs/latex/wx/debugrpt.tex create mode 100644 docs/latex/wx/debugrptpvw.tex create mode 100644 docs/latex/wx/debugrptpvwstd.tex create mode 100644 docs/latex/wx/debugrptup.tex create mode 100644 docs/latex/wx/debugrptz.tex diff --git a/docs/latex/wx/classes.tex b/docs/latex/wx/classes.tex index c06621e332..d9c2cc0483 100644 --- a/docs/latex/wx/classes.tex +++ b/docs/latex/wx/classes.tex @@ -74,6 +74,11 @@ \input ddeconn.tex \input ddeservr.tex \input debugcxt.tex +\input debugrpt.tex +\input debugrptz.tex +\input debugrptpvw.tex +\input debugrptpvwstd.tex +\input debugrptup.tex \input delgrend.tex \input dialog.tex \input dialevt.tex diff --git a/docs/latex/wx/debugrpt.tex b/docs/latex/wx/debugrpt.tex new file mode 100644 index 0000000000..3151951e90 --- /dev/null +++ b/docs/latex/wx/debugrpt.tex @@ -0,0 +1,253 @@ +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +%% 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}. + +wxDebugReport 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 report is fully assembled, it can be simply 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, e.g. 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} + + + +\wxheading{Data structures} + +This enum used for the functions which may report either the current state +or the state during the last (fatal) exception: +\begin{verbatim} +enum wxDebugReport::Context +{ + Context_Curent, + Context_Exception +}; +\end{verbatim} + +\latexignore{\rtfignore{\wxheading{Members}}} + + +\membersection{wxDebugReport::wxDebugReport}\label{wxdebugreportwxdebugreport} + +\func{}{wxDebugReport}{\void} + +Constructor creates a temporary directory where the files which 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} + +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}} + +Add 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} + +Same as \helpref{AddContext(Context\_Current)}{wxdebugreportaddcontext}. + + +\membersection{wxDebugReport::AddCurrentDump}\label{wxdebugreportaddcurrentdump} + +\func{bool}{AddCurrentDump}{\void} + +Same as \helpref{AddDump(Context\_Current)}{wxdebugreportadddump}. + + +\membersection{wxDebugReport::AddDump}\label{wxdebugreportadddump} + +\func{bool}{AddDump}{\param{Context }{ctx}} + +Adds 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} + +Same as \helpref{AddContext(Context\_Exception)}{wxdebugreportaddcontext}. + + +\membersection{wxDebugReport::AddExceptionDump}\label{wxdebugreportaddexceptiondump} + +\func{bool}{AddExceptionDump}{\void} + +Same as \helpref{AddDump(Context\_Exception)}{wxdebugreportadddump}. + + +\membersection{wxDebugReport::AddFile}\label{wxdebugreportaddfile} + +\func{void}{AddFile}{\param{const wxString\& }{name}, \param{const wxString\& }{description}} + +Add another file to the report: the file must already exist on disk. Its name +is relative to \helpref{GetDirectory()}{wxdebugreportgetdirectory}. + +\arg{description} only exists to be shown to the user in the report summary +shown by \helpref{wxDebugReportPreview}{wxdebugreportpreview}. + + +\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} + +Return 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}} + +Retrieve 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} + +Get the current number files in this report. + + +\membersection{wxDebugReport::GetReportName}\label{wxdebugreportgetreportname} + +\constfunc{wxString}{GetReportName}{\void} + +Get the name used as base name for various files, by default +\helpref{wxApp::GetName()}{wxappgetname} is used. + + +\membersection{wxDebugReport::IsOk}\label{wxdebugreportisok} + +\constfunc{bool}{IsOk}{\void} + +Return \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} + +Process 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}} + +Remove 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} + +Reset the directory name we use, the object can't be used any more after +this as it becomes invalid/uninitialized. + diff --git a/docs/latex/wx/debugrptpvw.tex b/docs/latex/wx/debugrptpvw.tex new file mode 100644 index 0000000000..bb2f272f85 --- /dev/null +++ b/docs/latex/wx/debugrptpvw.tex @@ -0,0 +1,59 @@ +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +%% Name: debugrptpvw.tex +%% Purpose: wxDebugReportPreview documentation +%% Author: Vadim Zeitlin +%% Modified by: +%% Created: 2005-03-21 +%% RCS-ID: $Id$ +%% Copyright: (c) Vadim Zeitlin 2005 +%% License: wxWindows license +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% + +\section{\class{wxDebugReportPreview}}\label{wxdebugreportpreview} + +This class presents the debug report to the user and allows him to veto report +entirely or remove some parts of it. Although not mandatory, using this class +is strongly recommended as data included in the debug report might contain +sensitive private information and the user should be notified about it as well +as having a possibility to examine the data which had been gathered to check +whether this is effectively the case and discard the debug report if it is. + +wxDebugReportPreview is an abstract base class, currently the only concrete +class deriving from it is +\helpref{wxDebugReportPreviewStd}{wxdebugreportpreviewstd}. + +\wxheading{Derived from} + +No base class + +\wxheading{Include files} + + + + +\latexignore{\rtfignore{\wxheading{Members}}} + + +\membersection{wxDebugReportPreview::wxDebugReportPreview}\label{wxdebugreportpreviewwxdebugreportpreview} + +\func{}{wxDebugReportPreview}{\void} + +Trivial default constructor. + + +\membersection{wxDebugReportPreview::\destruct{wxDebugReportPreview}}\label{wxdebugreportpreviewdtor} + +\func{}{\destruct{wxDebugReportPreview}}{\void} + +dtor is trivial as well but should be virtual for a base class + + +\membersection{wxDebugReportPreview::Show}\label{wxdebugreportpreviewshow} + +\constfunc{bool}{Show}{\param{wxDebugReport\& }{dbgrpt}} + +Present the report to the user and allow him to modify it by removing some or +all of the files and, potentially, adding some notes. Return \true if the +report should be processed or \false if the user chose to cancel report +generation or removed all files from it. + diff --git a/docs/latex/wx/debugrptpvwstd.tex b/docs/latex/wx/debugrptpvwstd.tex new file mode 100644 index 0000000000..58007f48fa --- /dev/null +++ b/docs/latex/wx/debugrptpvwstd.tex @@ -0,0 +1,46 @@ +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +%% Name: debugrptpvwstd.tex +%% Purpose: wxDebugReportPreviewStd documentation +%% Author: Vadim Zeitlin +%% Modified by: +%% Created: 2005-03-21 +%% RCS-ID: $Id$ +%% Copyright: (c) Vadim Zeitlin 2005 +%% License: wxWindows license +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% + +\section{\class{wxDebugReportPreviewStd}}\label{wxdebugreportpreviewstd} + +wxDebugReportPreviewStd is a standard debug report preview window. It displays +a GUIdialog allowing the user to examine the contents of a debug report, remove +files from and add notes to it. + + +\wxheading{Derived from} + +\helpref{wxDebugReportPreview}{wxdebugreportpreview} + +\wxheading{Include files} + + + + + +\latexignore{\rtfignore{\wxheading{Members}}} + + +\membersection{wxDebugReportPreviewStd::wxDebugReportPreviewStd}\label{wxdebugreportpreviewstdwxdebugreportpreviewstd} + +\func{}{wxDebugReportPreviewStd}{\void} + +Trivial default constructor. + + +\membersection{wxDebugReportPreviewStd::Show}\label{wxdebugreportpreviewstdshow} + +\constfunc{bool}{Show}{\param{wxDebugReport\& }{dbgrpt}} + +Show the dialog, see +\helpref{wxDebugReportPreview::Show()}{wxdebugreportpreviewshow} for more +information. + diff --git a/docs/latex/wx/debugrptup.tex b/docs/latex/wx/debugrptup.tex new file mode 100644 index 0000000000..13dd2248ef --- /dev/null +++ b/docs/latex/wx/debugrptup.tex @@ -0,0 +1,51 @@ +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +%% Name: debugrptup.tex +%% Purpose: wxDebugReportUpload documentation +%% Author: Vadim Zeitlin +%% Modified by: +%% Created: 2005-03-21 +%% RCS-ID: $Id$ +%% Copyright: (c) Vadim Zeitlin 2005 +%% License: wxWindows license +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% + +\section{\class{wxDebugReportUpload}}\label{wxdebugreportupload} + +This class is used to upload a compressed file using HTTP POST request. As this +class derives from wxDebugReportCompress, before upload the report is +compressed in a single .ZIP file. + +\wxheading{Derived from} + +\helpref{wxDebugReportCompress}{wxdebugreportcompress} + +\wxheading{Include files} + + + + +\latexignore{\rtfignore{\wxheading{Members}}} + +\membersection{wxDebugReportUpload::wxDebugReportUpload}\label{wxdebugreportuploadwxdebugreportupload} + +\func{}{wxDebugReportUpload}{\param{const wxString\& }{url}, \param{const wxString\& }{input}, \param{const wxString\& }{action}, \param{const wxString\& }{curl = \_T("curl")}} + +This class will upload the compressed file created by its base class to an HTML +multipart/form-data form at the specified address. The \arg{url} is the upload +page address, \arg{input} is the name of the \texttt{"type=file"} control on +the form used for the file name and \arg{action} is the value of the form +action field. The report is uploaded using \texttt{\textit{curl}} program which +should be available, the \arg{curl} parameter may be used to specify the full +path to it. + + +\membersection{wxDebugReportUpload::OnServerReply}\label{wxdebugreportuploadonserverreply} + +\func{bool}{OnServerReply}{\param{const wxArrayString\& }{WXUNUSED(reply)}} + +This function may be overridden in a derived class to show the output from +curl: this may be an HTML page or anything else that the server returned. +Value returned by this function becomes the return value of +\helpref{wxDebugReport::Process()}{wxdebugreportprocess}. + + diff --git a/docs/latex/wx/debugrptz.tex b/docs/latex/wx/debugrptz.tex new file mode 100644 index 0000000000..b01aca0320 --- /dev/null +++ b/docs/latex/wx/debugrptz.tex @@ -0,0 +1,40 @@ +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +%% Name: debugrptz.tex +%% Purpose: wxDebugReportCompress documentation +%% Author: Vadim Zeitlin +%% Modified by: +%% Created: 2005-03-21 +%% RCS-ID: $Id$ +%% Copyright: (c) Vadim Zeitlin 2005 +%% License: wxWindows license +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% + +\section{\class{wxDebugReportCompress}}\label{wxdebugreportcompress} + +wxDebugReportCompress is a \helpref{wxDebugReport}{wxdebugreport} which +compresses all the files in this debug report into a single .ZIP file in its +\texttt{\textit{Process()}} function. + +\wxheading{Derived from} + +\helpref{wxDebugReport}{wxdebugreport} + +\wxheading{Include files} + + + + +\latexignore{\rtfignore{\wxheading{Members}}} + +\membersection{wxDebugReportCompress::wxDebugReportCompress}\label{wxdebugreportcompresswxdebugreportcompress} + +\func{}{wxDebugReportCompress}{\void} + +Default constructor does nothing special. + +\membersection{wxDebugReportCompress::GetCompressedFileName}\label{wxdebugreportcompressgetcompressedfilename} + +\constfunc{const wxString\&}{GetCompressedFileName}{\void} + +Returns the full path of the compressed file (empty if creation failed). + -- 2.45.2