X-Git-Url: https://git.saurik.com/wxWidgets.git/blobdiff_plain/435c1bc4d2aa801e805970cbf32fbeab803b527d..89a7e1ff98e58687eef2bf8ec94bf7190208167f:/interface/wx/log.h diff --git a/interface/wx/log.h b/interface/wx/log.h index c9e97e50c9..e810b5ee2a 100644 --- a/interface/wx/log.h +++ b/interface/wx/log.h @@ -6,6 +6,36 @@ // Licence: wxWindows license ///////////////////////////////////////////////////////////////////////////// + +/** + Different standard log levels (you may also define your own) used with + wxLog::OnLog() 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; + + /** @class wxLogWindow @@ -578,24 +608,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 @@ -606,11 +623,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 @@ -728,9 +740,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(); @@ -740,7 +753,7 @@ public: @see AddTraceMask(). */ - static const wxArrayString GetTraceMasks(); + static const wxArrayString& GetTraceMasks(); /** Returns whether the verbose mode is currently active. @@ -758,7 +771,7 @@ public: 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); + static void OnLog(wxLogLevel level, const wxString& msg, time_t t); /** Remove the @a mask from the list of allowed masks for @@ -785,8 +798,8 @@ public: static wxLog* SetActiveTarget(wxLog* logtarget); /** - Specifies that log messages with level logLevel should be ignored - and not sent to the active log target. + Specifies that log messages with level greater (numerically) than + @a logLevel should be ignored and not sent to the active log target. */ static void SetLogLevel(wxLogLevel logLevel); @@ -813,7 +826,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); @@ -839,6 +853,34 @@ public: */ static void Suspend(); + /** + Log the given message. + + 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(). + + Example of use of this class from wxLogChain: + @code + void wxLogChain::DoLog(wxLogLevel level, const wxString& msg, time_t t) + { + // let the previous logger show it + if ( m_logOld && IsPassingMessages() ) + m_logOld->Log(level, msg, t); + + // and also send it to the new one + if ( m_logNew && m_logNew != this ) + m_logNew->Log(level, msg, t); + } + @endcode + + @since 2.9.0 + */ + void Log(wxLogLevel level, const wxString& msg, time_t timestamp); + protected: /** @@ -932,7 +974,7 @@ public: // Global functions/macros // ============================================================================ -/** @ingroup group_funcmacro_log */ +/** @addtogroup group_funcmacro_log */ //@{ /** @@ -978,7 +1020,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 @@ -990,7 +1032,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 @@ -1003,7 +1045,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 @@ -1015,7 +1057,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. @@ -1028,7 +1070,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 @@ -1041,7 +1083,7 @@ void wxLogError(const char* formatString, ... ); void wxVLogError(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 @@ -1049,18 +1091,18 @@ void wxVLogError(const char* formatString, va_list argPtr); 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 @@ -1103,7 +1145,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 @@ -1111,10 +1153,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. @@ -1134,7 +1177,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 @@ -1147,7 +1190,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 @@ -1164,7 +1207,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