mac paths updated

[wxWidgets.git] / interface / debugrpt.h

diff --git a/interface/debugrpt.h b/interface/debugrpt.h
index 89e61a5d540c64e439c74196a4e98fc711f5a138..bb40cb19976d016e94b2b3c411a0f305efd828d5 100644 (file)
--- a/interface/debugrpt.h
+++ b/interface/debugrpt.h
@@ -1,6 +1,6 @@
 /////////////////////////////////////////////////////////////////////////////
 // Name:        debugrpt.h
 /////////////////////////////////////////////////////////////////////////////
 // Name:        debugrpt.h

-// Purpose:     documentation for wxDebugReportPreview class
+// Purpose:     interface of wxDebugReport*

 // Author:      wxWidgets team
 // RCS-ID:      $Id$
 // Licence:     wxWindows license
 // Author:      wxWidgets team
 // RCS-ID:      $Id$
 // Licence:     wxWindows license


@@ -10,16 +10,16 @@
     @class wxDebugReportPreview
     @wxheader{debugrpt.h}
 
     @class wxDebugReportPreview
     @wxheader{debugrpt.h}
 

-    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.
+    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
 
     wxDebugReportPreview is an abstract base class, currently the only concrete

-    class deriving from it is
-    wxDebugReportPreviewStd.
+    class deriving from it is wxDebugReportPreviewStd.

 
     @library{wxqa}
     @category{debugging}
 
     @library{wxqa}
     @category{debugging}


@@ -28,32 +28,35 @@ class wxDebugReportPreview
 {
 public:
     /**
 {
 public:
     /**

-        Trivial default constructor.
+        Default constructor.

     */
     wxDebugReportPreview();
 
     /**
     */
     wxDebugReportPreview();
 
     /**

-        dtor is trivial as well but should be virtual for a base class
+        Destructor is trivial as well but should be virtual for a base class.

     */
     */

-    ~wxDebugReportPreview();
+    virtual ~wxDebugReportPreview();

 
     /**
 
     /**

-        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.
+        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.

     */
     */

-    bool Show(wxDebugReport& dbgrpt) const;
+    virtual bool Show(wxDebugReport& dbgrpt) const;

 };
 
 
 };
 
 

+

 /**
     @class wxDebugReportCompress
     @wxheader{debugrpt.h}
 
 /**
     @class wxDebugReportCompress
     @wxheader{debugrpt.h}
 

-    wxDebugReportCompress is a wxDebugReport which
-    compresses all the files in this debug report into a single .ZIP file in its
-    @c @e Process() function.
+    wxDebugReportCompress is a wxDebugReport which compresses all the files in
+    this debug report into a single ZIP file in its wxDebugReport::Process()
+    function.

 
     @library{wxqa}
     @category{debugging}
 
     @library{wxqa}
     @category{debugging}


@@ -67,36 +70,47 @@ public:
     wxDebugReportCompress();
 
     /**
     wxDebugReportCompress();
 
     /**

-        Returns the full path of the compressed file (empty if creation failed).
+        Returns the full path of the compressed file (empty if creation
+        failed).

     */
     const wxString GetCompressedFileName() const;
 };
 
 
     */
     const wxString GetCompressedFileName() const;
 };
 
 

+

 /**
     @class wxDebugReport
     @wxheader{debugrpt.h}
 
 /**
     @class wxDebugReport
     @wxheader{debugrpt.h}
 

-    wxDebugReport is used to generate a debug report, containing information about
-    the program current state. It is usually used from
-    wxApp::OnFatalException as shown in the
-    sample.
+    wxDebugReport is used to generate a debug report, containing information
+    about the program current state. It is usually used from
+    wxApp::OnFatalException() as shown in the @ref page_samples_debugrpt.

 
 

-    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.
+    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
 
     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 wxDebugReportCompress to
-    compress it in a single file) or uploaded to a Web server using
-    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.
+    directory so that the user can email it to the developers (in which case
+    you should still use wxDebugReportCompress to compress it in a single file)
+    or uploaded to a Web server using 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.
+
+    A typical usage example:
+
+    @code
+    wxDebugReport report;
+    wxDebugReportPreviewStd preview;
+
+    report.AddCurrentContext();  // could also use AddAll()
+    report.AddCurrentDump();     // to do both at once
+
+    if ( preview.Show(report) )
+        report.Process();
+    @endcode

 
     @library{wxqa}
     @category{debugging}
 
     @library{wxqa}
     @category{debugging}


@@ -104,25 +118,32 @@ public:
 class wxDebugReport
 {
 public:
 class wxDebugReport
 {
 public:

+    /**
+        This enum is used for functions that report either the current state or
+        the state during the last (fatal) exception.
+    */
+    enum Context {
+        Context_Current,
+        Context_Exception
+    };
+

     /**
         The constructor creates a temporary directory where the files that will
     /**
         The constructor creates a temporary directory where the files that will

-        be included in the report are created. Use
-        IsOk() to check for errors.
+        be included in the report are created. Use IsOk() to check for errors.

     */
     wxDebugReport();
 
     /**
         The destructor normally destroys the temporary directory created in the
     */
     wxDebugReport();
 
     /**
         The destructor normally destroys the temporary directory created in the

-        constructor
-        with all the files it contains. Call Reset() to
-        prevent this from happening.
+        constructor with all the files it contains. Call Reset() to prevent
+        this from happening.

     */
     ~wxDebugReport();
 
     /**
         Adds all available information to the report. Currently this includes a
     */
     ~wxDebugReport();
 
     /**
         Adds all available information to the report. Currently this includes a

-        text (XML) file describing the process context and, under Win32, a minidump
-        file.
+        text (XML) file describing the process context and, under Win32, a
+        minidump file.

     */
     void AddAll(Context context = Context_Exception);
 
     */
     void AddAll(Context context = Context_Exception);
 


@@ -133,89 +154,93 @@ public:
     bool AddContext(Context ctx);
 
     /**
     bool AddContext(Context ctx);
 
     /**

-        The same as @ref addcontext() AddContext(Context_Current).
+        The same as calling AddContext(Context_Current).

     */
     bool AddCurrentContext();
 
     /**
     */
     bool AddCurrentContext();
 
     /**

-        The same as @ref adddump() AddDump(Context_Current).
+        The same as calling AddDump(Context_Current).

     */
     bool AddCurrentDump();
 
     /**
         Adds the minidump file to the debug report.
     */
     bool AddCurrentDump();
 
     /**
         Adds the minidump file to the debug report.

-        Minidumps are only available under recent Win32 versions (@c dbghlp32.dll
-        can be installed under older systems to make minidumps available).
+
+        Minidumps are only available under recent Win32 versions
+        (@c dbghlp32.dll can be installed under older systems to make minidumps
+        available).

     */
     bool AddDump(Context ctx);
 
     /**
     */
     bool AddDump(Context ctx);
 
     /**

-        The same as @ref addcontext() AddContext(Context_Exception).
+        The same as calling AddContext(Context_Exception).

     */
     bool AddExceptionContext();
 
     /**
     */
     bool AddExceptionContext();
 
     /**

-        The same as @ref adddump() AddDump(Context_Exception).
+        The same as calling AddDump(Context_Exception).

     */
     bool AddExceptionDump();
 
     /**
     */
     bool AddExceptionDump();
 
     /**

-        Add another file to the report. If @a 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
-        @a description only exists to be displayed to the user in the report summary
-        shown by wxDebugReportPreview.
+        Add another file to the report. If @a 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
+        @a description only exists to be displayed to the user in the report
+        summary shown by wxDebugReportPreview.
+
+        @see GetDirectory(), AddText()

     */
     */

-    void AddFile(const wxString& filename,
-                 const wxString& description);
+    void AddFile(const wxString& filename, const wxString& description);

 
     /**
 
     /**

-        This is a convenient wrapper around AddFile(). It
-        creates the file with the given @e name and writes @a text to it, then
-        adds the file to the report. The @a filename shouldn't contain the path.
-        Returns @true if file could be added successfully, @false if an IO error
-        occurred.
+        This is a convenient wrapper around AddFile(). It creates the file with
+        the given @a name and writes @a text to it, then adds the file to the
+        report. The @a filename shouldn't contain the path.
+
+        @return @true if file could be added successfully, @false if an IO
+                 error occurred.

     */
     bool AddText(const wxString& filename, const wxString& text,
                  const wxString& description);
 
     /**
     */
     bool AddText(const wxString& filename, const wxString& text,
                  const wxString& description);
 
     /**

-        This function may be overridden to add arbitrary custom context to the XML
-        context file created by AddContext(). By
-        default, it does nothing.
+        This function may be overridden to add arbitrary custom context to the
+        XML context file created by AddContext(). By default, it does nothing.

     */
     void DoAddCustomContext(wxXmlNode* nodeRoot);
 
     /**
     */
     void DoAddCustomContext(wxXmlNode* nodeRoot);
 
     /**

-        This function may be overridden to modify the contents of the exception tag in
-        the XML context file.
+        This function may be overridden to modify the contents of the exception
+        tag in the XML context file.

     */
     bool DoAddExceptionInfo(wxXmlNode* nodeContext);
 
     /**
     */
     bool DoAddExceptionInfo(wxXmlNode* nodeContext);
 
     /**

-        This function may be overridden to modify the contents of the modules tag in
-        the XML context file.
+        This function may be overridden to modify the contents of the modules
+        tag in the XML context file.

     */
     bool DoAddLoadedModules(wxXmlNode* nodeModules);
 
     /**
     */
     bool DoAddLoadedModules(wxXmlNode* nodeModules);
 
     /**

-        This function may be overridden to modify the contents of the system tag in
-        the XML context file.
+        This function may be overridden to modify the contents of the system
+        tag in the XML context file.

     */
     bool DoAddSystemInfo(wxXmlNode* nodeSystemInfo);
 
     /**
     */
     bool DoAddSystemInfo(wxXmlNode* nodeSystemInfo);
 
     /**

-        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 AddFile().
+        This method should be used to construct the full name of the files
+        which you wish to add to the report using AddFile().
+
+        @return The name of the temporary directory used for the files in this
+                 report.

     */
     const wxString GetDirectory() const;
 
     /**
     */
     const wxString GetDirectory() const;
 
     /**

-        Retrieves the name (relative to
-        wxDebugReport::GetDirectory) and the description of the
-        file with the given index. If @a n is greater than or equal to the number of
-        filse, @false is returned.
+        Retrieves the name (relative to GetDirectory()) and the description of
+        the file with the given index. If @a n is greater than or equal to the
+        number of filse, @false is returned.

     */
     bool GetFile(size_t n, wxString* name, wxString* desc) const;
 
     */
     bool GetFile(size_t n, wxString* name, wxString* desc) const;
 


@@ -226,14 +251,13 @@ public:
 
     /**
         Gets the name used as a base name for various files, by default
 
     /**
         Gets the name used as a base name for various files, by default

-        wxApp::GetAppName is used.
+        wxApp::GetAppName() is used.

     */
     wxString GetReportName() const;
 
     /**
     */
     wxString GetReportName() const;
 
     /**

-        Returns @true if the object was successfully initialized. If this method
-        returns
-        @false the report can't be used.
+        Returns @true if the object was successfully initialized. If this
+        method returns @false the report can't be used.

     */
     bool IsOk() const;
 
     */
     bool IsOk() const;
 


@@ -245,27 +269,28 @@ public:
     bool Process();
 
     /**
     bool Process();
 
     /**

-        Removes the file from report: this is used by
-        wxDebugReportPreview to allow the user to
-        remove files potentially containing private information from the report.
+        Removes the file from report: this is used by wxDebugReportPreview to
+        allow the user to remove files potentially containing private
+        information from the report.

     */
     void RemoveFile(const wxString& name);
 
     /**
     */
     void RemoveFile(const wxString& name);
 
     /**

-        Resets the directory name we use. The object can't be used any more after
-        this as it becomes uninitialized and invalid.
+        Resets the directory name we use. The object can't be used any more
+        after this as it becomes uninitialized and invalid.

     */
     void Reset();
 };
 
 
     */
     void Reset();
 };
 
 

+

 /**
     @class wxDebugReportPreviewStd
     @wxheader{debugrpt.h}
 
 /**
     @class wxDebugReportPreviewStd
     @wxheader{debugrpt.h}
 

-    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.
+    wxDebugReportPreviewStd is a standard debug report preview window. It
+    displays a dialog allowing the user to examine the contents of a debug
+    report, remove files from and add notes to it.

 
     @library{wxqa}
     @category{debugging}
 
     @library{wxqa}
     @category{debugging}


@@ -279,21 +304,22 @@ public:
     wxDebugReportPreviewStd();
 
     /**
     wxDebugReportPreviewStd();
 
     /**

-        Show the dialog, see
-        wxDebugReportPreview::Show for more
-        information.
+        Shows the dialog.
+
+        @see wxDebugReportPreview::Show()

     */
     bool Show(wxDebugReport& dbgrpt) const;
 };
 
 
     */
     bool Show(wxDebugReport& dbgrpt) const;
 };
 
 

+

 /**
     @class wxDebugReportUpload
     @wxheader{debugrpt.h}
 
 /**
     @class wxDebugReportUpload
     @wxheader{debugrpt.h}
 

-    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.
+    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.

 
     @library{wxqa}
     @category{debugging}
 
     @library{wxqa}
     @category{debugging}


@@ -302,24 +328,24 @@ class wxDebugReportUpload : public wxDebugReportCompress
 {
 public:
     /**
 {
 public:
     /**

-        )
-        This class will upload the compressed file created by its base class to an HTML
-        multipart/form-data form at the specified address. The @a url is the upload
-        page address, @a input is the name of the @c "type=file" control on
-        the form used for the file name and @a action is the value of the form
-        action field. The report is uploaded using @c @e curl program which
-        should be available, the @e curl parameter may be used to specify the full
-        path to it.
+        This class will upload the compressed file created by its base class to
+        an HTML multipart/form-data form at the specified address. The @a url
+        is the upload page address, @a input is the name of the @c "type=file"
+        control on the form used for the file name and @a action is the value
+        of the form action field. The report is uploaded using the @e curl
+        program which should be available, the @e curl parameter may be used to
+        specify the full path to it.

     */
     wxDebugReportUpload(const wxString& url, const wxString& input,
     */
     wxDebugReportUpload(const wxString& url, const wxString& input,

-                        const wxString& action);
+                        const wxString& action,
+                        const wxString& curl = "curl");

 
     /**
 
     /**

-        )
-        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
-        wxDebugReport::Process.
+        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
+        wxDebugReport::Process().

     */
     */

-    bool OnServerReply();
+    bool OnServerReply(const wxArrayString& reply);

 };
 };

+