Document wxDateTime::GregorianAdoption enum and TimeZone class.

[wxWidgets.git] / interface / wx / log.h

diff --git a/interface/wx/log.h b/interface/wx/log.h
index 10253f9a7113627168d2a4ca1287b4cb0d3c4418..314f82e24f09a376cc4f8124b09f4f5423bf5e63 100644 (file)
--- a/interface/wx/log.h
+++ b/interface/wx/log.h
@@ -9,7 +9,7 @@
 
 /**
     Different standard log levels (you may also define your own) used with
 
 /**
     Different standard log levels (you may also define your own) used with

-    by standard wxLog functions wxLogError(), wxLogWarning(), etc...
+    by standard wxLog functions wxLogGeneric(), wxLogError(), wxLogWarning(), etc...

 */
 enum wxLogLevelValues
 {
 */
 enum wxLogLevelValues
 {


@@ -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
 
 /**
     @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.
 
     @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" 
     @category{logging}
 
     @see @ref overview_log, @ref group_funcmacro_log "wxLogXXX() functions" 


@@ -863,6 +959,9 @@ public:
     
     /**
         Returns the current timestamp format string.
     
     /**
         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();
 
     */
     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.
         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.
 
     */
     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();
         @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);

     
 
     /**
     
 
     /**


@@ -1114,6 +1234,18 @@ const wxChar* wxSysErrorMsg(unsigned long errCode = 0);
 
 //@}
 
 
 //@}
 

+/** @addtogroup group_funcmacro_log */
+//@{
+/**
+    Logs a message with the given wxLogLevel.
+    E.g. using @c wxLOG_Message as first argument, this function behaves like wxLogMessage().
+
+    @header{wx/log.h}
+*/
+void wxLogGeneric(wxLogLevel level, const char* formatString, ... );
+void wxVLogGeneric(wxLogLevel level, const char* formatString, va_list argPtr);
+//@}
+

 /** @addtogroup group_funcmacro_log */
 //@{
 /**
 /** @addtogroup group_funcmacro_log */
 //@{
 /**


@@ -1281,7 +1413,7 @@ void wxVLogStatus(const char* formatString, va_list argPtr);
 /**
     Mostly used by wxWidgets itself, but might be handy for logging errors
     after system call (API function) failure. It logs the specified message
 /**
     Mostly used by wxWidgets itself, but might be handy for logging errors
     after system call (API function) failure. It logs the specified message

-    text as well as the last system error code (@e errno or @e ::GetLastError()
+    text as well as the last system error code (@e errno or @e GetLastError()

     depending on the platform) and the corresponding error message. The second
     form of this function takes the error code explicitly as the first
     argument.
     depending on the platform) and the corresponding error message. The second
     form of this function takes the error code explicitly as the first
     argument.