X-Git-Url: https://git.saurik.com/wxWidgets.git/blobdiff_plain/34085a0d4ffc1b83543427fb30d1e6227afe6662..7344108e8a129a3f9b4df5ab0f98a1713db03b89:/interface/wx/log.h diff --git a/interface/wx/log.h b/interface/wx/log.h index e810b5ee2a..1bf3a66d37 100644 --- a/interface/wx/log.h +++ b/interface/wx/log.h @@ -1,16 +1,15 @@ ///////////////////////////////////////////////////////////////////////////// // Name: log.h -// Purpose: interface of wxLogWindow +// Purpose: interface of wxLog* classes // Author: wxWidgets team // RCS-ID: $Id$ -// Licence: wxWindows license +// Licence: wxWindows licence ///////////////////////////////////////////////////////////////////////////// /** Different standard log levels (you may also define your own) used with - wxLog::OnLog() by standard wxLog functions wxLogError(), wxLogWarning(), - etc... + by standard wxLog functions wxLogGeneric(), wxLogError(), wxLogWarning(), etc... */ enum wxLogLevelValues { @@ -35,6 +34,39 @@ enum wxLogLevelValues */ typedef unsigned long wxLogLevel; +/** + Information about a log record (unit of the log output). + */ +class wxLogRecordInfo +{ +public: + /// The name of the file where this log message was generated. + const char *filename; + + /// The line number at which this log message was generated. + int line; + + /** + The name of the function where the log record was generated. + + This field may be @NULL if the compiler doesn't support @c __FUNCTION__ + (but most modern compilers do). + */ + const char *func; + + /// Time when the log message was generated. + time_t timestamp; + + /** + Id of the thread in which the message was generated. + + This field is only available if wxWidgets was built with threads + support (wxUSE_THREADS == 1). + + @see wxThread::GetCurrentId() + */ + wxThreadIdType threadId; +}; /** @class wxLogWindow @@ -64,9 +96,11 @@ public: @true to show the frame initially (default), otherwise Show() must be called later. @param passToOld - @true to process the log messages normally in addition to - logging them in the log frame (default), @false to only log them in the - log frame. + @true to process the log messages normally in addition to logging them + in the log frame (default), @false to only log them in the log frame. + Note that if no targets were set using wxLog::SetActiveTarget() then + wxLogWindow simply becomes the active one and messages won't be passed + to other targets. */ wxLogWindow(wxWindow* pParent, const wxString& szTitle, bool show = true, bool passToOld = true); @@ -257,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} @@ -308,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. @@ -402,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); }; @@ -549,143 +583,131 @@ public: + /** - @class wxLog + @class wxLogFormatter - wxLog class defines the interface for the @e log targets used by wxWidgets - logging functions as explained in the @ref overview_log. - The only situations when you need to directly use this class is when you want - to derive your own log target because the existing ones don't satisfy your - needs. Another case is if you wish to customize the behaviour of the standard - logging classes (all of which respect the wxLog settings): for example, set - which trace messages are logged and which are not or change (or even remove - completely) the timestamp on the messages. + wxLogFormatter class is used to format the log messages. It implements the + default formatting and can be derived from to create custom formatters. - Otherwise, it is completely hidden behind the @e wxLogXXX() functions and - you may not even know about its existence. + The default implementation formats the message into a string containing + the time stamp, level-dependent prefix and the message itself. - @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. + 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 - @section log_derivingyours Deriving your own log target + the log output could be something like: - There are two functions which must be implemented by any derived class to - actually process the log messages: DoLog() and DoLogString(). - The second function receives a string which just has to be output in some way - and the easiest way to write a new log target is to override just this function - in the derived class. + @verbatim + [7872] d:\testApp\src\testApp.cpp(85) : *** Application started *** + @endverbatim - If more control over the output format is needed, then the first function must - be overridden which allows to construct custom messages depending on the log level - or even do completely different things depending on the message severity - (for example, throw away all messages except warnings and errors, show warnings - on the screen and forward the error messages to the user's (or programmer's) cell - phone - maybe depending on whether the timestamp tells us if it is day or - night in the current time zone). + @library{wxbase} + @category{logging} - There also functions to support message buffering. Why are they needed? - Some of wxLog implementations, most notably the standard wxLogGui class, - buffer the messages (for example, to avoid showing the user a zillion of modal - message boxes one after another -- which would be really annoying). + @see @ref overview_log - Flush() shows them all and clears the buffer contents. - This function doesn't do anything if the buffer is already empty. + @since 2.9.4 +*/ +class wxLogFormatter +{ +public: + /** + The default ctor does nothing. + */ + wxLogFormatter(); - See also: - @li Flush() - @li FlushActive() + /** + 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; - @section log_tracemasks Using trace masks +protected: + /** + This function formats the time stamp part of the log message. - The functions below allow some limited customization of wxLog behaviour - without writing a new log target class (which, aside from being a matter of - several minutes, allows you to do anything you want). - The verbose messages are the trace messages which are not disabled in the - release mode and are generated by wxLogVerbose(). - They are not normally shown to the user because they present little interest, - but may be activated, for example, in order to help the user find some program - problem. + Override this function if you need to customize just the time stamp. - As for the (real) trace messages, their handling depends on the currently - enabled trace masks: if AddTraceMask() was called for the mask of the given - message, it will be logged, otherwise nothing happens. + @param time + Time to format. - For example, - @code - wxLogTrace( wxTRACE_OleCalls, "IFoo::Bar() called" ); - @endcode + @return + The formated time string, may be empty. + */ + virtual wxString FormatTime(time_t time) const; +}; - will log the message if it was preceded by: - @code - wxLog::AddTraceMask( wxTRACE_OleCalls); - @endcode +/** + @class wxLog - The standard trace masks are given in wxLogTrace() documentation. - - Finally, the @e wxLog::DoLog() function automatically prepends a time stamp - to all the messages. The format of the time stamp may be changed: it can be - any string with % specifications fully described in the documentation of the - standard @e strftime() function. For example, the default format is - "[%d/%b/%y %H:%M:%S] " which gives something like "[17/Sep/98 22:10:16] " - (without quotes) for the current date. Setting an empty string as the time - format or calling the shortcut wxLog::DisableTimestamp(), disables timestamping - of the messages completely. - - See also - @li AddTraceMask() - @li RemoveTraceMask() - @li ClearTraceMasks() - @li GetTraceMasks() - @li IsAllowedTraceMask() - @li SetVerbose() - @li GetVerbose() - @li SetTimestamp() - @li GetTimestamp() - @li SetTraceMask() - @li GetTraceMask() - @li SetRepetitionCounting() - @li GetRepetitionCounting() - - @note - Timestamping 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, please - use SetTimestamp() explicitly. - - - @section log_target Manipulating the log target - - The functions in this section work with and manipulate the active log - target. The OnLog() is called by the @e wxLogXXX() functions - and invokes the DoLog() of the active log target if any. - - Get/Set methods are used to install/query the current active target and, - finally, DontCreateOnDemand() disables the automatic creation of a standard - log target if none actually exists. It is only useful when the application - is terminating and shouldn't be used in other situations because it may - easily lead to a loss of messages. - - See also: - @li OnLog() - @li GetActiveTarget() - @li SetActiveTarget() - @li DontCreateOnDemand() - @li Suspend() - @li Resume() + wxLog class defines the interface for the log targets used by wxWidgets + logging functions as explained in the @ref overview_log. + + The only situations when you need to directly use this class is when you want + to derive your own log target because the existing ones don't satisfy your + needs. + Otherwise, it is completely hidden behind the @ref group_funcmacro_log "wxLogXXX() functions" + and you may not even know about its existence. - @library{wxcore} + @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{wxbase} @category{logging} - @see @ref overview_log + @see @ref overview_log, @ref group_funcmacro_log "wxLogXXX() functions" */ class wxLog { public: + /** + @name Trace mask functions + */ + //@{ + /** Add the @a mask to the list of allowed masks for wxLogTrace(). @@ -701,107 +723,232 @@ public: static void ClearTraceMasks(); /** - Instructs wxLog to not create new log targets on the fly if there is none - currently. (Almost) for internal use only: it is supposed to be called by the - application shutdown code. + Returns the currently allowed list of string trace masks. - Note that this function also calls ClearTraceMasks(). + @see AddTraceMask(). */ - static void DontCreateOnDemand(); + static const wxArrayString& GetTraceMasks(); /** - Shows all the messages currently in buffer and clears it. - If the buffer is already empty, nothing happens. + Returns @true if the @a mask is one of allowed masks for wxLogTrace(). + + See also: AddTraceMask(), RemoveTraceMask() */ - virtual void Flush(); + static bool IsAllowedTraceMask(const wxString& mask); /** - Flushes the current log target if any, does nothing if there is none. + Remove the @a mask from the list of allowed masks for + wxLogTrace(). - @see Flush() + @see AddTraceMask() */ - static void FlushActive(); + static void RemoveTraceMask(const wxString& mask); + + //@} + + /** - Returns the pointer to the active log target (may be @NULL). + @name Log target functions */ - static wxLog* GetActiveTarget(); - + //@{ + /** - Returns the current log level limit. + Instructs wxLog to not create new log targets on the fly if there is none + currently (see GetActiveTarget()). + + (Almost) for internal use only: it is supposed to be called by the + application shutdown code (where you don't want the log target to be + automatically created anymore). + + Note that this function also calls ClearTraceMasks(). */ - static wxLogLevel GetLogLevel(); + static void DontCreateOnDemand(); /** - Returns whether the repetition counting mode is enabled. + Returns the pointer to the active log target (may be @NULL). + + Notice that if SetActiveTarget() hadn't been previously explicitly + called, this function will by default try to create a log target by + calling wxAppTraits::CreateLogTarget() which may be overridden in a + user-defined traits class to change the default behaviour. You may also + call DontCreateOnDemand() to disable this behaviour. + + When this function is called from threads other than main one, + auto-creation doesn't happen. But if the thread has a thread-specific + log target previously set by SetThreadActiveTarget(), it is returned + instead of the global one. Otherwise, the global log target is + returned. */ - static bool GetRepetitionCounting(); + static wxLog* GetActiveTarget(); /** - Returns the current timestamp format string. + Sets the specified log target as the active one. + + Returns the pointer to the previous active log target (may be @NULL). + To suppress logging use a new instance of wxLogNull not @NULL. If the + active log target is set to @NULL a new default log target will be + created when logging occurs. + + @see SetThreadActiveTarget() */ - static const wxString& GetTimestamp(); + static wxLog* SetActiveTarget(wxLog* logtarget); /** - @deprecated - Returns the current trace mask, see Customization() section for details. - */ - static wxTraceMask GetTraceMask(); + Sets a thread-specific log target. + + The log target passed to this function will be used for all messages + logged by the current thread using the usual wxLog functions. This + shouldn't be called from the main thread which never uses a thread- + specific log target but can be used for the other threads to handle + thread logging completely separately; instead of buffering thread log + messages in the main thread logger. + + Notice that unlike for SetActiveTarget(), wxWidgets does not destroy + the thread-specific log targets when the thread terminates so doing + this is your responsibility. + This method is only available if @c wxUSE_THREADS is 1, i.e. wxWidgets + was compiled with threads support. + + @param logger + The new thread-specific log target, possibly @NULL. + @return + The previous thread-specific log target, initially @NULL. + + @since 2.9.1 + */ + static wxLog *SetThreadActiveTarget(wxLog *logger); + /** - Returns the currently allowed list of string trace masks. + Flushes the current log target if any, does nothing if there is none. - @see AddTraceMask(). + When this method is called from the main thread context, it also + flushes any previously buffered messages logged by the other threads. + When it is called from the other threads it simply calls Flush() on the + currently active log target, so it mostly makes sense to do this if a + thread has its own logger set with SetThreadActiveTarget(). */ - static const wxArrayString& GetTraceMasks(); - + static void FlushActive(); + /** - Returns whether the verbose mode is currently active. + Resumes logging previously suspended by a call to Suspend(). + All messages logged in the meanwhile will be flushed soon. */ - static bool GetVerbose(); + static void Resume(); /** - Returns @true if the @a mask is one of allowed masks for wxLogTrace(). + Suspends the logging until Resume() is called. - See also: AddTraceMask(), RemoveTraceMask() + 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 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() + works as expected with it). + + @see Resume(), wxLogNull */ - static bool IsAllowedTraceMask(const wxString& mask); + static void Suspend(); + + //@} + + /** - Forwards the message at specified level to the @e DoLog() function of the - active log target if there is any, does nothing otherwise. + @name Log level functions */ - static void OnLog(wxLogLevel level, const wxString& msg, time_t t); - + //@{ + /** - Remove the @a mask from the list of allowed masks for - wxLogTrace(). + Returns the current log level limit. - @see AddTraceMask() - */ - static void RemoveTraceMask(const wxString& mask); + All messages at levels strictly greater than the value returned by this + function are not logged at all. - /** - Resumes logging previously suspended by a call to Suspend(). - All messages logged in the meanwhile will be flushed soon. + @see SetLogLevel(), IsLevelEnabled() */ - static void Resume(); + static wxLogLevel GetLogLevel(); + + /** + Returns true if logging at this level is enabled for the current thread. + + This function only returns @true if logging is globally enabled and if + @a level is less than or equal to the maximal log level enabled for the + given @a component. + + @see IsEnabled(), SetLogLevel(), GetLogLevel(), SetComponentLevel() + + @since 2.9.1 + */ + static bool IsLevelEnabled(wxLogLevel level, wxString component); /** - Sets the specified log target as the active one. + Sets the log level for the given component. - Returns the pointer to the previous active log target (may be @NULL). - To suppress logging use a new instance of wxLogNull not @NULL. If the - active log target is set to @NULL a new default log target will be - created when logging occurs. - */ - static wxLog* SetActiveTarget(wxLog* logtarget); + For example, to disable all but error messages from wxWidgets network + classes you may use + @code + wxLog::SetComponentLevel("wx/net", wxLOG_Error); + @endcode + + SetLogLevel() may be used to set the global log level. + + @param component + Non-empty component name, possibly using slashes (@c /) to separate + it into several parts. + @param level + Maximal level of log messages from this component which will be + handled instead of being simply discarded. + + @since 2.9.1 + */ + static void SetComponentLevel(const wxString& component, wxLogLevel level); /** Specifies that log messages with level greater (numerically) than @a logLevel should be ignored and not sent to the active log target. + + @see SetComponentLevel() */ static void SetLogLevel(wxLogLevel logLevel); + + //@} + + + + /** + @name Enable/disable features functions + */ + //@{ + + /** + Globally enable or disable logging. + + Calling this function with @false argument disables all log messages + for the current thread. + + @see wxLogNull, IsEnabled() + + @return + The old state, i.e. @true if logging was previously enabled and + @false if it was disabled. + */ + static bool EnableLogging(bool enable = true); + + /** + Returns true if logging is enabled at all now. + + @see IsLevelEnabled(), EnableLogging() + */ + static bool IsEnabled(); + + /** + Returns whether the repetition counting mode is enabled. + */ + static bool GetRepetitionCounting(); /** Enables logging mode in which a log message is logged once, and in case exactly @@ -809,99 +956,166 @@ public: repetitions is logged. */ static void SetRepetitionCounting(bool repetCounting = true); + + /** + 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(); - + /** - @deprecated - Sets the trace mask, see @ref log_tracemasks section for details. + Returns whether the verbose mode is currently active. */ - static void SetTraceMask(wxTraceMask mask); + static bool GetVerbose(); /** Activates or deactivates verbose mode in which the verbose messages are logged as the normal ones instead of being silently dropped. + + The verbose messages are the trace messages which are not disabled in the + release mode and are generated by wxLogVerbose(). + + @see @ref overview_log */ static void SetVerbose(bool verbose = true); + + //@} + /** - Suspends the logging until Resume() is called. + Sets the specified formatter as the active one. - 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. + @param formatter + The new formatter. If @NULL, reset to the default formatter. - Note that suspending the logging means that the log sink won't be 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() - works as expected with it). + 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. - @see Resume(), wxLogNull + @since 2.9.4 */ - static void Suspend(); + wxLogFormatter *SetFormatter(wxLogFormatter* formatter); + + + /** + Some of wxLog implementations, most notably the standard wxLogGui class, + buffer the messages (for example, to avoid showing the user a zillion of modal + message boxes one after another -- which would be really annoying). + This function shows them all and clears the buffer contents. + If the buffer is already empty, nothing happens. + If you override this method in a derived class, call the base class + version first, before doing anything else. + */ + virtual void Flush(); + /** - Log the given message. + Log the given record. This function should only be called from the DoLog() implementations in - the derived classes (which can't call wxLog::DoLog() directly as it is - protected), it should not be used for logging new messages which can be - only sent to the currently active logger using OnLog() which also - checks if the logging (for this level) is enabled while this method - just directly calls DoLog(). + the derived classes if they need to call DoLogRecord() on another log + object (they can, of course, just use wxLog::DoLogRecord() call syntax + to call it on the object itself). It should not be used for logging new + messages which can be only sent to the currently active logger using + OnLog() which also checks if the logging (for this level) is enabled + while this method just directly calls DoLog(). Example of use of this class from wxLogChain: @code - void wxLogChain::DoLog(wxLogLevel level, const wxString& msg, time_t t) + void wxLogChain::DoLogRecord(wxLogLevel level, + const wxString& msg, + const wxLogRecordInfo& info) { // let the previous logger show it if ( m_logOld && IsPassingMessages() ) - m_logOld->Log(level, msg, t); + m_logOld->LogRecord(level, msg, info); // and also send it to the new one if ( m_logNew && m_logNew != this ) - m_logNew->Log(level, msg, t); + m_logNew->LogRecord(level, msg, info); } @endcode - @since 2.9.0 + @since 2.9.1 */ - void Log(wxLogLevel level, const wxString& msg, time_t timestamp); + void LogRecord(wxLogLevel level, const wxString& msg, const wxLogRecordInfo& info); protected: + /** + @name Logging callbacks. + + The functions which should be overridden by custom log targets. + + When defining a new log target, you have a choice between overriding + DoLogRecord(), which provides maximal flexibility, DoLogTextAtLevel() + which can be used if you don't intend to change the default log + messages formatting but want to handle log messages of different levels + differently or, in the simplest case, DoLogText(). + */ + //@{ /** - Called to process the message of the specified severity. @a msg is the text - of the message as specified in the call of @e wxLogXXX() function which - generated it and @a timestamp is the moment when the message was generated. + 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 + the timestamp and, for some log levels (e.g. error and warning), the + corresponding prefix to @a msg and passes it to DoLogTextAtLevel(). - The base class version prepends the timestamp to the message, adds a prefix - corresponding to the log level and then calls - DoLogString() with the resulting string. + You may override this method to implement custom formatting of the + log messages or to implement custom filtering of log messages (e.g. you + could discard all log messages coming from the given source file). + */ + virtual void DoLogRecord(wxLogLevel level, + const wxString& msg, + const wxLogRecordInfo& info); + + /** + Called to log the specified string at given level. + + The base class versions logs debug and trace messages on the system + default debug output channel and passes all the other messages to + DoLogText(). */ - virtual void DoLog(wxLogLevel level, const wxString& msg, time_t timestamp); + virtual void DoLogTextAtLevel(wxLogLevel level, const wxString& msg); /** - Called to log the specified string. The timestamp is already included in the - string but still passed to this function. + Called to log the specified string. - A simple implementation may just send the string to @c stdout or, better, - @c stderr. + A simple implementation might just send the string to @c stdout or + @c stderr or save it in a file (of course, the already existing + wxLogStderr can be used for this). + + The base class version of this function asserts so it must be + overridden if you don't override DoLogRecord() or DoLogTextAtLevel(). */ - virtual void DoLogString(const wxString& msg, time_t timestamp); + virtual void DoLogText(const wxString& msg); + + //@} }; @@ -954,7 +1168,7 @@ protected: @library{wxbase} @category{logging} */ -class wxLogNull : public wxLog +class wxLogNull { public: /** @@ -1020,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 */ //@{ /** @@ -1086,35 +1312,22 @@ void wxVLogError(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. - - 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(). + Log a message at @c wxLOG_Trace log level (see ::wxLogLevelValues enum). - @header{wx/log.h} -*/ -void wxLogTrace(const char *mask, const char* formatString, ... ); -void wxVLogTrace(const char *mask, const char* formatString, va_list argPtr); -//@} + 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 + do the same thing for log messages of any level, and not just the tracing + ones. -/** @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: @@ -1127,22 +1340,10 @@ void wxVLogTrace(const char *mask, const char* formatString, va_list argPtr); @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 */ @@ -1212,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. @@ -1225,3 +1426,24 @@ void wxLogSysError(const char* formatString, ... ); void wxVLogSysError(const char* formatString, va_list argPtr); //@} +/** @addtogroup group_funcmacro_debug */ +//@{ + +/** + @def wxDISABLE_DEBUG_LOGGING_IN_RELEASE_BUILD() + + Use this macro to disable logging at debug and trace levels in release + build when not using wxIMPLEMENT_APP(). + + @see wxDISABLE_DEBUG_SUPPORT(), + wxDISABLE_ASSERTS_IN_RELEASE_BUILD(), + @ref overview_debugging + + @since 2.9.1 + + @header{wx/log.h} + */ +#define wxDISABLE_DEBUG_LOGGING_IN_RELEASE_BUILD() + +//@} +