X-Git-Url: https://git.saurik.com/wxWidgets.git/blobdiff_plain/d13b34d3f2be575d59747a5926000be7b28a45dc..7344108e8a129a3f9b4df5ab0f98a1713db03b89:/interface/wx/log.h diff --git a/interface/wx/log.h b/interface/wx/log.h index 26f9180ce0..1bf3a66d37 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 { @@ -291,8 +291,8 @@ public: 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. + clipboard) so you may want to override DoShowSingleLogMessage() to + customize wxLogGui -- the dialogs sample shows how to do this. @library{wxcore} @category{logging} @@ -342,51 +342,6 @@ protected: 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. @@ -436,6 +391,51 @@ protected: array hasn't been emptied yet. */ bool m_bHasMessages; + +private: + /** + 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); }; @@ -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); /** @@ -942,7 +1062,7 @@ public: @since 2.9.1 */ - void LogRecord(wxLogLevel level, const wxString& msg, time_t timestamp); + void LogRecord(wxLogLevel level, const wxString& msg, const wxLogRecordInfo& info); protected: /** @@ -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.