X-Git-Url: https://git.saurik.com/wxWidgets.git/blobdiff_plain/86381d4297f0225448823369a0df73ba67664078..82b30473f935d7ffe21a165aa8ef63e16599c3fc:/interface/wx/log.h diff --git a/interface/wx/log.h b/interface/wx/log.h index 10253f9a71..314f82e24f 100644 --- 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 - by standard wxLog functions wxLogError(), wxLogWarning(), etc... + by standard wxLog functions wxLogGeneric(), wxLogError(), wxLogWarning(), etc... */ 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 @@ -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); /** @@ -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 */ //@{ /** @@ -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 - 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.