made wxLogGui more flexible and documented it and added example of customizing it to the dialogs sample (now with the docs)

git-svn-id: https://svn.wxwidgets.org/svn/wx/wxWidgets/trunk@55554 c3d73ce0-8a6f-49c7-b76d-6d57e0e08775

interface/wx/log.h

@@ -188,11 +188,50 @@ public:
 /**
     @class wxLogGui
 
-    This is the default log target for the GUI wxWidgets applications. It is passed
+    This is the default log target for the GUI wxWidgets applications.
-    to wxLog::SetActiveTarget at the program
-    startup and is deleted by wxWidgets during the program shut down.
 
-    @library{wxbase}
+    Please see @ref overview_log_customize for explanation of how to change the
+    default log target.
+
+    An object of this class is used by default to show the log messages created
+    by using wxLogMessage(), wxLogError() and other logging functions. It
+    doesn't display the messages logged by them immediately however but
+    accumulates all messages logged during an event handler execution and then
+    shows them all at once when its Flush() method is called during the idle
+    time processing. This has the important advantage of showing only a single
+    dialog to the user even if several messages were logged because of a single
+    error as it often happens (e.g. a low level function could log a message
+    because it failed to open a file resulting in its caller logging another
+    message due to the failure of higher level operation requiring the use of
+    this file). If you need to force the display of all previously logged
+    messages immediately you can use wxLog::FlushActive() to force the dialog
+    display.
+
+    Also notice that if an error message is logged when several informative
+    messages had been already logged before, the informative messages are
+    discarded on the assumption that they are not useful -- and may be
+    confusing and hence harmful -- any more after the error. The warning
+    and error messages are never discarded however and any informational
+    messages logged after the first error one are also kept (as they may
+    contain information about the error recovery). You may override DoLog()
+    method to change this behaviour.
+
+    At any rate, it is possible that that several messages were accumulated
+    before this class Flush() method is called. If this is the case, Flush()
+    uses a custom dialog which shows the last message directly and allows the
+    user to view the previously logged ones by expanding the "Details"
+    wxCollapsiblePane inside it. This custom dialog also provides the buttons
+    for copying the log messages to the clipboard and saving them to a file.
+
+    However if only a single message is present when Flush() is called, just a
+    wxMessageBox() is used to show it. This has the advantage of being closer
+    to the native behaviour but it doesn't give the user any possibility to
+    copy or save the message (except for the recent Windows versions where @c
+    Ctrl-C may be pressed in the message box to copy its contents to the
+    clipboard) so you may want to override DoShowSingleMessage() to customize
+    wxLogGui -- the dialogs sample shows how to do this.
+
+    @library{wxcore}
     @category{logging}
 */
 class wxLogGui : public wxLog
@@ -202,6 +241,138 @@ public:
         Default constructor.
     */
     wxLogGui();
+
+    /**
+        Presents the accumulated log messages, if any, to the user.
+
+        This method is called during the idle time and should show any messages
+        accumulated in wxLogGui#m_aMessages field to the user.
+     */
+    virtual void Flush();
+
+protected:
+    /**
+        Returns the appropriate title for the dialog.
+
+        The title is constructed from wxApp::GetAppDisplayName() and the
+        severity string (e.g. "error" or "warning") appropriate for the current
+        wxLogGui#m_bErrors and wxLogGui#m_bWarnings values.
+     */
+    wxString GetTitle() const;
+
+    /**
+        Returns wxICON_ERROR, wxICON_WARNING or wxICON_INFORMATION depending on
+        the current maximal severity.
+
+        This value is suitable to be used in the style parameter of
+        wxMessageBox() function.
+     */
+    int GetSeverityIcon() const;
+
+    /**
+        Forgets all the currently stored messages.
+
+        If you override Flush() (and don't call the base class version), you
+        must call this method to avoid messages being logged over and over
+        again.
+     */
+    void Clear();
+
+
+    /**
+        Method called by Flush() to show a single log message.
+
+        This function can be overridden to show the message in a different way.
+        By default a simple wxMessageBox() call is used.
+
+        @param message
+            The message to show (it can contain multiple lines).
+        @param title
+            The suggested title for the dialog showing the message, see
+            GetTitle().
+        @param style
+            One of @c wxICON_XXX constants, see GetSeverityIcon().
+     */
+    virtual void DoShowSingleLogMessage(const wxString& message,
+                                        const wxString& title,
+                                        int style);
+
+    /**
+        Method called by Flush() to show multiple log messages.
+
+        This function can be overridden to show the messages in a different way.
+        By default a special log dialog showing the most recent message and
+        allowing the user to expand it to view the previously logged ones is
+        used.
+
+        @param messages
+            Array of messages to show; it contains more than one element.
+        @param severities
+            Array of message severities containing @c wxLOG_XXX values.
+        @param times
+            Array of time_t values indicating when each message was logged.
+        @param title
+            The suggested title for the dialog showing the message, see
+            GetTitle().
+        @param style
+            One of @c wxICON_XXX constants, see GetSeverityIcon().
+     */
+    virtual void DoShowMultipleLogMessages(const wxArrayString& messages,
+                                           const wxArrayInt& severities,
+                                           const wxArrayLong& times,
+                                           const wxString& title,
+                                           int style);
+
+
+    /**
+        All currently accumulated messages.
+
+        This array may be empty if no messages were logged.
+
+        @see m_aSeverity, m_aTimes
+     */
+    wxArrayString m_aMessages;
+
+    /**
+        The severities of each logged message.
+
+        This array is synchronized with wxLogGui#m_aMessages, i.e. the n-th
+        element of this array corresponds to the severity of the n-th message.
+        The possible severity values are @c wxLOG_XXX constants, e.g.
+        wxLOG_Error, wxLOG_Warning, wxLOG_Message etc.
+     */
+    wxArrayInt m_aSeverity;
+
+    /**
+        The time stamps of each logged message.
+
+        The elements of this array are time_t values corresponding to the time
+        when the message was logged.
+     */
+    wxArrayLong m_aTimes;
+
+    /**
+        True if there any error messages.
+     */
+    bool m_bErrors;
+
+    /**
+        True if there any warning messages.
+
+        If both wxLogGui#m_bErrors and this member are false, there are only
+        informational messages to be shown.
+     */
+    bool m_bWarnings;
+
+    /**
+        True if there any messages to be shown to the user.
+
+        This variable is used instead of simply checking whether
+        wxLogGui#m_aMessages array is empty to allow blocking further calls to
+        Flush() while a log dialog is already being shown, even if the messages
+        array hasn't been emptied yet.
+     */
+    bool m_bHasMessages;
 };
 
 
@@ -494,9 +665,6 @@ public:
     */
     static void ClearTraceMasks();
 
-    */
-
-
     /**
         Disables time stamping of the log messages.
         This function is new since wxWidgets version 2.9
@@ -629,17 +797,18 @@ public:
     static void RemoveTraceMask(const wxString& mask);
 
     /**
-        Resumes logging previously suspended by a call to
+        Resumes logging previously suspended by a call to Suspend().
-        Suspend(). All messages logged in the meanwhile will be
+        All messages logged in the meanwhile will be flushed soon.
-        flushed soon.
     */
     static void Resume();
 
     /**
-        Sets the specified log target as the active one. Returns the pointer to the
+        Sets the specified log target as the active one.
-        previous active log target (may be @NULL).  To suppress logging use a new
+
-        instance of wxLogNull not @NULL.  If the active log target is set to @NULL a
+        Returns the pointer to the previous active log target (may be @NULL).
-        new default log target will be created when logging occurs.
+        To suppress logging use a new instance of wxLogNull not @NULL.  If the
+        active log target is set to @NULL a new default log target will be
+        created when logging occurs.
     */
     static wxLog* SetActiveTarget(wxLog* logtarget);