X-Git-Url: https://git.saurik.com/wxWidgets.git/blobdiff_plain/a44f3b5a890fbb2a88ef9adafd94f662e1664889..9e96e16fe0bc7af32d329c965ad110a3e5be5ad8:/interface/wx/log.h?ds=sidebyside diff --git a/interface/wx/log.h b/interface/wx/log.h index ef8b2a9d83..04f57638d4 100644 --- a/interface/wx/log.h +++ b/interface/wx/log.h @@ -6,6 +6,68 @@ // Licence: wxWindows license ///////////////////////////////////////////////////////////////////////////// + +/** + Different standard log levels (you may also define your own) used with + by standard wxLog functions wxLogError(), wxLogWarning(), etc... +*/ +enum wxLogLevelValues +{ + wxLOG_FatalError, //!< program can't continue, abort immediately + wxLOG_Error, //!< a serious error, user must be informed about it + wxLOG_Warning, //!< user is normally informed about it but may be ignored + wxLOG_Message, //!< normal message (i.e. normal output of a non GUI app) + wxLOG_Status, //!< informational: might go to the status line of GUI app + wxLOG_Info, //!< informational message (a.k.a. 'Verbose') + wxLOG_Debug, //!< never shown to the user, disabled in release mode + wxLOG_Trace, //!< trace messages are also only enabled in debug mode + wxLOG_Progress, //!< used for progress indicator (not yet) + wxLOG_User = 100, //!< user defined levels start here + wxLOG_Max = 10000 +}; + +/** + The type used to specify a log level. + + Default values of ::wxLogLevel used by wxWidgets are contained in the + ::wxLogLevelValues enumeration. +*/ +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 @@ -396,7 +458,7 @@ public: Constructs a log target which sends all the log messages to the given output stream. If it is @NULL, the messages are sent to @c cerr. */ - wxLogStream(std::ostream ostr = NULL); + wxLogStream(std::ostream *ostr = NULL); }; @@ -445,6 +507,11 @@ public: class wxLogBuffer : public wxLog { public: + /** + The default ctor does nothing. + */ + wxLogBuffer(); + /** Shows all the messages collected so far to the user (using a message box in the GUI applications or by printing them out to the console in text mode) and @@ -535,19 +602,23 @@ public: @section log_derivingyours Deriving your own log target - 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. + There are several methods which may be overridden in the derived class to + customize log messages handling: DoLogRecord(), DoLogTextAtLevel() and + DoLogText(). + + The last method is the simplest one: you should override it if you simply + want to redirect the log output elsewhere, without taking into account the + level of the message. If you do want to handle messages of different levels + differently, then you should override DoLogTextAtLevel(). - 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). + Finally, if more control over the output format is needed, then the first + function must be overridden as it 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). There also functions to support message buffering. Why are they needed? Some of wxLog implementations, most notably the standard wxLogGui class, @@ -557,13 +628,16 @@ public: Flush() shows them all and clears the buffer contents. This function doesn't do anything if the buffer is already empty. - See also: - @li Flush() - @li FlushActive() + @see FlushActive() @section log_tracemasks Using trace masks + Notice that the use of log trace masks is hardly necessary any longer in + current wxWidgets version as the same effect can be achieved by using + different log components for different log statements of any level. Please + see @ref overview_log_enable for more information about the log components. + 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). @@ -573,24 +647,11 @@ public: but may be activated, for example, in order to help the user find some program problem. - As for the (real) trace messages, their handling depends on the settings of - the (application global) @e trace mask which can either be specified using - SetTraceMask(), GetTraceMask() and wxLogTrace() which takes an integer mask - or using AddTraceMask() for string trace masks. + 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. - The difference between bit-wise and string trace masks is that a message using - integer trace mask will only be logged if all bits of the mask are set in the - current mask while a message using string mask will be logged simply if the - mask had been added before to the list of allowed ones. For example, - - @code - wxLogTrace( wxTraceRefCount|wxTraceOleCalls, "Active object ref count: %d", nRef ); - @endcode - - will do something only if the current trace mask contains both @c wxTraceRefCount - and @c wxTraceOle, but: - @code wxLogTrace( wxTRACE_OleCalls, "IFoo::Bar() called" ); @endcode @@ -601,11 +662,6 @@ public: wxLog::AddTraceMask( wxTRACE_OleCalls); @endcode - Using string masks is simpler and allows you to easily add custom ones, so this - is the preferred way of working with trace messages. The integer trace mask is - kept for compatibility and for additional (but very rarely needed) flexibility - only. - The standard trace masks are given in wxLogTrace() documentation. Finally, the @e wxLog::DoLog() function automatically prepends a time stamp @@ -643,8 +699,7 @@ public: @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. + target. Get/Set methods are used to install/query the current active target and, finally, DontCreateOnDemand() disables the automatic creation of a standard @@ -653,7 +708,6 @@ public: easily lead to a loss of messages. See also: - @li OnLog() @li GetActiveTarget() @li SetActiveTarget() @li DontCreateOnDemand() @@ -692,26 +746,65 @@ public: */ static void DontCreateOnDemand(); + /** + 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); + /** Shows all the messages currently in buffer and clears it. + 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(); /** Flushes the current log target if any, does nothing if there is none. - @see Flush() + 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 void FlushActive(); /** 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 wxLog* GetActiveTarget(); /** Returns the current log level limit. + + All messages at levels strictly greater than the value returned by this + function are not logged at all. + + @see SetLogLevel(), IsLevelEnabled() */ static wxLogLevel GetLogLevel(); @@ -723,9 +816,10 @@ public: /** Returns the current timestamp format string. */ - static const wxString GetTimestamp(); + static const wxString& GetTimestamp(); /** + @deprecated Returns the current trace mask, see Customization() section for details. */ static wxTraceMask GetTraceMask(); @@ -735,7 +829,7 @@ public: @see AddTraceMask(). */ - static const wxArrayString GetTraceMasks(); + static const wxArrayString& GetTraceMasks(); /** Returns whether the verbose mode is currently active. @@ -750,10 +844,24 @@ public: static bool IsAllowedTraceMask(const wxString& mask); /** - Forwards the message at specified level to the @e DoLog() function of the - active log target if there is any, does nothing otherwise. - */ - static void OnLog(wxLogLevel level, const wxString& message); + Returns true if logging is enabled at all now. + + @see IsLevelEnabled(), EnableLogging() + */ + static bool IsEnabled(); + + /** + 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); /** Remove the @a mask from the list of allowed masks for @@ -776,12 +884,38 @@ public: 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 wxLog* SetActiveTarget(wxLog* logtarget); /** - Specifies that log messages with level logLevel should be ignored - and not sent to the active log target. + Sets the log level for the given component. + + 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); @@ -792,6 +926,32 @@ public: */ static void SetRepetitionCounting(bool repetCounting = true); + /** + 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); + /** Sets the timestamp format prepended by the default log targets to all messages. The string may contain any normal characters as well as % @@ -808,7 +968,8 @@ public: static void DisableTimestamp(); /** - Sets the trace mask, see @ref log_derivingyours section for details. + @deprecated + Sets the trace mask, see @ref log_tracemasks section for details. */ static void SetTraceMask(wxTraceMask mask); @@ -834,27 +995,89 @@ public: */ static void Suspend(); + /** + Log the given record. + + This function should only be called from the DoLog() implementations in + 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::DoLogRecord(wxLogLevel level, + const wxString& msg, + const wxLogRecordInfo& info) + { + // let the previous logger show it + if ( m_logOld && IsPassingMessages() ) + m_logOld->LogRecord(level, msg, info); + + // and also send it to the new one + if ( m_logNew && m_logNew != this ) + m_logNew->LogRecord(level, msg, info); + } + @endcode + + @since 2.9.1 + */ + void LogRecord(wxLogLevel level, const wxString& msg, time_t timestamp); + 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 created 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); + + //@} }; @@ -907,7 +1130,7 @@ protected: @library{wxbase} @category{logging} */ -class wxLogNull : public wxLog +class wxLogNull { public: /** @@ -927,7 +1150,7 @@ public: // Global functions/macros // ============================================================================ -/** @ingroup group_funcmacro_log */ +/** @addtogroup group_funcmacro_log */ //@{ /** @@ -973,7 +1196,7 @@ const wxChar* wxSysErrorMsg(unsigned long errCode = 0); //@} -/** @ingroup group_funcmacro_log */ +/** @addtogroup group_funcmacro_log */ //@{ /** For all normal, informational messages. They also appear in a message box @@ -985,7 +1208,7 @@ void wxLogMessage(const char* formatString, ... ); void wxVLogMessage(const char* formatString, va_list argPtr); //@} -/** @ingroup group_funcmacro_log */ +/** @addtogroup group_funcmacro_log */ //@{ /** For verbose output. Normally, it is suppressed, but might be activated if @@ -998,7 +1221,7 @@ void wxLogVerbose(const char* formatString, ... ); void wxVLogVerbose(const char* formatString, va_list argPtr); //@} -/** @ingroup group_funcmacro_log */ +/** @addtogroup group_funcmacro_log */ //@{ /** For warnings - they are also normally shown to the user, but don't @@ -1010,7 +1233,7 @@ void wxLogWarning(const char* formatString, ... ); void wxVLogWarning(const char* formatString, va_list argPtr); //@} -/** @ingroup group_funcmacro_log */ +/** @addtogroup group_funcmacro_log */ //@{ /** Like wxLogError(), but also terminates the program with the exit code 3. @@ -1023,7 +1246,7 @@ void wxLogFatalError(const char* formatString, ... ); void wxVLogFatalError(const char* formatString, va_list argPtr); //@} -/** @ingroup group_funcmacro_log */ +/** @addtogroup group_funcmacro_log */ //@{ /** The functions to use for error messages, i.e. the messages that must be @@ -1036,26 +1259,33 @@ void wxLogError(const char* formatString, ... ); void wxVLogError(const char* formatString, va_list argPtr); //@} -/** @ingroup group_funcmacro_log */ +/** @addtogroup group_funcmacro_log */ //@{ /** + Log a message at wxLOG_Trace log level. + + 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. + 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. - wxLogDebug(const char*,const char*,...) and - wxLogDebug(wxTraceMask,const char*,...) can be used instead if you would - like to be able to separate trace messages into different categories which - can be enabled or disabled with the static functions provided in wxLog. + 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* formatString, ... ); -void wxVLogTrace(const char* formatString, va_list argPtr); +void wxLogTrace(const char *mask, const char* formatString, ... ); +void wxVLogTrace(const char *mask, const char* formatString, va_list argPtr); //@} -/** @ingroup group_funcmacro_log */ +/** @addtogroup group_funcmacro_log */ //@{ /** Like wxLogDebug(), trace functions only do something in debug builds and @@ -1098,7 +1328,7 @@ void wxVLogTrace(const char* mask, va_list argPtr); //@} -/** @ingroup group_funcmacro_log */ +/** @addtogroup group_funcmacro_log */ //@{ /** Like wxLogDebug(), trace functions only do something in debug builds and @@ -1106,10 +1336,11 @@ void wxVLogTrace(const char* mask, function is that usually there are a lot of trace messages, so it might make sense to separate them from other debug messages. + @deprecated This version of wxLogTrace() only logs the message if all the bits corresponding to the @a mask are set in the wxLog trace mask which can be set by calling wxLog::SetTraceMask(). This version is less flexible than - wxLogDebug(const char*,const char*,...) because it doesn't allow defining + wxLogTrace(const char*,const char*,...) because it doesn't allow defining the user trace masks easily. This is why it is deprecated in favour of using string trace masks. @@ -1129,7 +1360,7 @@ void wxLogTrace(wxTraceMask mask, const char* formatString, ... ); void wxVLogTrace(wxTraceMask mask, const char* formatString, va_list argPtr); //@} -/** @ingroup group_funcmacro_log */ +/** @addtogroup group_funcmacro_log */ //@{ /** The right functions for debug output. They only do something in debug mode @@ -1142,7 +1373,7 @@ void wxLogDebug(const char* formatString, ... ); void wxVLogDebug(const char* formatString, va_list argPtr); //@} -/** @ingroup group_funcmacro_log */ +/** @addtogroup group_funcmacro_log */ //@{ /** Messages logged by this function will appear in the statusbar of the @@ -1159,7 +1390,7 @@ void wxLogStatus(const char* formatString, ... ); void wxVLogStatus(const char* formatString, va_list argPtr); //@} -/** @ingroup group_funcmacro_log */ +/** @addtogroup group_funcmacro_log */ //@{ /** Mostly used by wxWidgets itself, but might be handy for logging errors @@ -1177,3 +1408,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 IMPLEMENT_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() + +//@} +