Add wxLogFormatter to allow easier wxLog output customization.

Delegate the log string creation to wxLogFormatter. This allows defining a
custom object of a class derived from it to customize the log output instead
of having to override DoLogRecord() in wxLog itself.

Closes #13792.

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

interface/wx/log.h

@@ -583,6 +583,102 @@ public:
 
 
 
+
+/**
+    @class wxLogFormatter
+
+    wxLogFormatter class is used to format the log messages. It implements the
+    default formatting and can be derived from to create custom formatters.
+
+    The default implementation formats the message into a string containing
+    the time stamp, level-dependent prefix and the message itself.
+
+    To change it, you can derive from it and override its Format() method. For
+    example, to include the thread id in the log messages you can use
+    @code
+        class LogFormatterWithThread : public wxLogFormatter
+        {
+            virtual wxString Format(wxLogLevel level,
+                                    const wxString& msg,
+                                    const wxLogRecordInfo& info) const
+            {
+                return wxString::Format("[%d] %s(%d) : %s",
+                    info.threadId, info.filename, info.line, msg);
+            }
+        };
+    @endcode
+    And then associate it with wxLog instance using its SetFormatter(). Then,
+    if you call:
+
+    @code
+        wxLogMessage(_("*** Application started ***"));
+    @endcode
+
+    the log output could be something like:
+
+    @verbatim
+        [7872] d:\testApp\src\testApp.cpp(85) : *** Application started ***
+    @endverbatim
+
+    @library{wxbase}
+    @category{logging}
+
+    @see @ref overview_log
+
+    @since 2.9.4
+*/
+class wxLogFormatter
+{
+public:
+    /**
+        The default ctor does nothing.
+    */
+    wxLogFormatter();
+
+
+    /**
+        This function creates the full log message string.
+
+        Override it to customize the output string format.
+
+        @param level
+            The level of this log record, e.g. ::wxLOG_Error.
+        @param msg
+            The log message itself.
+        @param info
+            All the other information (such as time, component, location...)
+            associated with this log record.
+
+        @return
+            The formated message.
+
+        @note
+            Time stamping is disabled for Visual C++ users in debug builds by
+            default because otherwise it would be impossible to directly go to the line
+            from which the log message was generated by simply clicking in the debugger
+            window on the corresponding error message. If you wish to enable it, override
+            FormatTime().
+    */
+    virtual wxString Format(wxLogLevel level,
+                            const wxString& msg,
+                            const wxLogRecordInfo& info) const;
+
+protected:
+    /**
+        This function formats the time stamp part of the log message.
+
+        Override this function if you need to customize just the time stamp.
+
+        @param time
+            Time to format.
+
+        @return
+            The formated time string, may be empty.
+    */
+    virtual wxString FormatTime(time_t time) const;
+};
+
+
 /**
     @class wxLog
 
@@ -599,7 +695,7 @@ public:
     @note For console-mode applications, the default target is wxLogStderr, so
           that all @e wxLogXXX() functions print on @c stderr when @c wxUSE_GUI = 0.
 
-    @library{wxcore}
+    @library{wxbase}
     @category{logging}
 
     @see @ref overview_log, @ref group_funcmacro_log "wxLogXXX() functions" 
@@ -863,6 +959,9 @@ public:
     
     /**
         Returns the current timestamp format string.
+
+        Notice that the current time stamp is only used by the default log
+        formatter and custom formatters may ignore this format.
     */
     static const wxString& GetTimestamp();
 
@@ -871,12 +970,20 @@ public:
         messages. The string may contain any normal characters as well as %
         prefixed format specifiers, see @e strftime() manual for details.
         Passing an empty string to this function disables message time stamping.
+
+        Notice that the current time stamp is only used by the default log
+        formatter and custom formatters may ignore this format. You can also
+        define a custom wxLogFormatter to customize the time stamp handling
+        beyond changing its format.
     */
     static void SetTimestamp(const wxString& format);
 
     /**
         Disables time stamping of the log messages.
 
+        Notice that the current time stamp is only used by the default log
+        formatter and custom formatters may ignore calls to this function.
+
         @since 2.9.0
     */
     static void DisableTimestamp();
@@ -899,6 +1006,19 @@ public:
     
     //@}
     
+
+    /**
+        Sets the specified formatter as the active one.
+
+        @param formatter
+            The new formatter. If @NULL, reset to the default formatter.
+
+        Returns the pointer to the previous formatter. You must delete it
+        if you don't plan to attach it again to a wxLog object later.
+
+        @since 2.9.4
+    */
+    wxLogFormatter *SetFormatter(wxLogFormatter* formatter);
     
 
     /**