/**
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
{
+
+/**
+ @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
@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"
Note that the latter must be called the same number of times as the former
to undo it, i.e. if you call Suspend() twice you must call Resume() twice as well.
- Note that suspending the logging means that the log sink won't be be flushed
+ Note that suspending the logging means that the log sink won't be flushed
periodically, it doesn't have any effect if the current log target does the
logging immediately without waiting for Flush() to be called (the standard
GUI log target only shows the log dialog when it is flushed, so Suspend()
/**
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();
/**
Sets the timestamp format prepended by the default log targets to all
messages. The string may contain any normal characters as well as %
- prefixed format specificators, see @e strftime() manual for details.
+ 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();
//@}
+
+ /**
+ 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);
/**
@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:
/**
//@{
/**
- Called to created log a new record.
+ Called to log a new record.
Any log message created by wxLogXXX() functions is passed to this
method of the active log target. The default implementation prepends
//@}
+/** @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 */
//@{
/**
/**
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.
projects / wxWidgets.git / blobdiff