/**
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
{
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}
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.
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);
};
+
+/**
+ @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 */
//@{
/**
/** @addtogroup group_funcmacro_log */
//@{
/**
- Log a message at wxLOG_Trace log level.
+ Log a message at @c wxLOG_Trace log level (see ::wxLogLevelValues enum).
Notice that the use of trace masks is not recommended any more as setting
the log components (please see @ref overview_log_enable) provides a way to
function is that usually there are a lot of trace messages, so it might
make sense to separate them from other debug messages.
- wxLogTrace(const char*,const char*,...) and can be used instead of
- wxLogDebug() if you would like to be able to separate trace messages into
- different categories which can be enabled or disabled with
- wxLog::AddTraceMask() and wxLog::RemoveTraceMask().
-
- @header{wx/log.h}
-*/
-void wxLogTrace(const char *mask, const char* formatString, ... );
-void wxVLogTrace(const char *mask, const char* formatString, va_list argPtr);
-//@}
-
-/** @addtogroup group_funcmacro_log */
-//@{
-/**
- Like wxLogDebug(), trace functions only do something in debug builds and
- expand to nothing in the release one. The reason for making it a separate
- function is that usually there are a lot of trace messages, so it might
- make sense to separate them from other debug messages.
-
- In this version of wxLogTrace(), trace messages can be separated into
- different categories and calls using this function only log the message if
- the given @a mask is currently enabled in wxLog. This lets you selectively
- trace only some operations and not others by enabling the desired trace
- masks with wxLog::AddTraceMask() or by setting the
+ Trace messages can be separated into different categories; these functions in facts
+ only log the message if the given @a mask is currently enabled in wxLog.
+ This lets you selectively trace only some operations and not others by enabling the
+ desired trace masks with wxLog::AddTraceMask() or by setting the
@ref overview_envvars "@c WXTRACE environment variable".
The predefined string trace masks used by wxWidgets are:
@itemdef{ wxTRACE_OleCalls, Trace OLE method calls (Win32 only) }
@endDefList
- @note Since both the mask and the format string are strings, this might
- lead to function signature confusion in some cases: if you intend to
- call the format string only version of wxLogTrace(), add a "%s"
- format string parameter and then supply a second string parameter for
- that "%s", the string mask version of wxLogTrace() will erroneously
- get called instead, since you are supplying two string parameters to
- the function. In this case you'll unfortunately have to avoid having
- two leading string parameters, e.g. by adding a bogus integer (with
- its "%d" format string).
-
@header{wx/log.h}
*/
void wxLogTrace(const char* mask, const char* formatString, ... );
-void wxVLogTrace(const char* mask,
- const char* formatString,
- va_list argPtr);
+void wxVLogTrace(const char* mask, 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