X-Git-Url: https://git.saurik.com/wxWidgets.git/blobdiff_plain/7bfc10389a92d0a47cde6b7e43b3ed12314eb094..c729f16fa54e8484d8600fcb423c0983d71abab2:/interface/wx/log.h diff --git a/interface/wx/log.h b/interface/wx/log.h index 04f57638d4..26f9180ce0 100644 --- a/interface/wx/log.h +++ b/interface/wx/log.h @@ -1,9 +1,9 @@ ///////////////////////////////////////////////////////////////////////////// // Name: log.h -// Purpose: interface of wxLogWindow +// Purpose: interface of wxLog* classes // Author: wxWidgets team // RCS-ID: $Id$ -// Licence: wxWindows license +// Licence: wxWindows licence ///////////////////////////////////////////////////////////////////////////// @@ -96,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); @@ -584,145 +586,32 @@ public: /** @class wxLog - wxLog class defines the interface for the @e log targets used by wxWidgets + 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. 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. + needs. - Otherwise, it is completely hidden behind the @e wxLogXXX() functions and - you may not even know about its existence. + Otherwise, it is completely hidden behind the @ref group_funcmacro_log "wxLogXXX() functions" + and you may not even know about its existence. @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. - - @section log_derivingyours Deriving your own log target - - 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(). - - 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, - buffer the messages (for example, to avoid showing the user a zillion of modal - message boxes one after another -- which would be really annoying). - - Flush() shows them all and clears the buffer contents. - This function doesn't do anything if the buffer is already empty. - - @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). - 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. - - 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. - - For example, - @code - wxLogTrace( wxTRACE_OleCalls, "IFoo::Bar() called" ); - @endcode - - will log the message if it was preceded by: - - @code - wxLog::AddTraceMask( wxTRACE_OleCalls); - @endcode - - 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. - - 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 GetActiveTarget() - @li SetActiveTarget() - @li DontCreateOnDemand() - @li Suspend() - @li Resume() - - @library{wxcore} @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(). @@ -738,48 +627,47 @@ 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(); /** - Globally enable or disable logging. + Returns @true if the @a mask is one of allowed masks for wxLogTrace(). - Calling this function with @false argument disables all log messages - for the current thread. + See also: AddTraceMask(), RemoveTraceMask() + */ + static bool IsAllowedTraceMask(const wxString& mask); - @see wxLogNull, IsEnabled() + /** + Remove the @a mask from the list of allowed masks for + wxLogTrace(). - @return - The old state, i.e. @true if logging was previously enabled and - @false if it was disabled. - */ - static bool EnableLogging(bool enable = true); + @see AddTraceMask() + */ + static void RemoveTraceMask(const wxString& mask); + + //@} - /** - 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. + /** + @name Log target functions */ - virtual void Flush(); - + //@{ + /** - Flushes the current log target if any, does nothing if there is none. + 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). - 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(). + Note that this function also calls ClearTraceMasks(). */ - static void FlushActive(); + static void DontCreateOnDemand(); /** Returns the pointer to the active log target (may be @NULL). @@ -799,57 +687,95 @@ public: static wxLog* GetActiveTarget(); /** - Returns the current log level limit. + Sets the specified log target as the active one. - All messages at levels strictly greater than the value returned by this - function are not logged at all. + 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 SetLogLevel(), IsLevelEnabled() + @see SetThreadActiveTarget() */ - static wxLogLevel GetLogLevel(); + static wxLog* SetActiveTarget(wxLog* logtarget); /** - Returns whether the repetition counting mode is enabled. - */ - static bool GetRepetitionCounting(); + Sets a thread-specific log target. - /** - Returns the current timestamp format string. - */ - static const wxString& GetTimestamp(); + 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. - /** - @deprecated - Returns the current trace mask, see Customization() section for details. - */ - static wxTraceMask GetTraceMask(); + 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(); + + //@} + + /** - Returns true if logging is enabled at all now. + @name Log level functions + */ + //@{ + + /** + Returns the current log level limit. - @see IsLevelEnabled(), EnableLogging() - */ - static bool IsEnabled(); + All messages at levels strictly greater than the value returned by this + function are not logged at all. + @see SetLogLevel(), IsLevelEnabled() + */ + static wxLogLevel GetLogLevel(); + /** Returns true if logging at this level is enabled for the current thread. @@ -863,32 +789,6 @@ public: */ static bool IsLevelEnabled(wxLogLevel level, wxString component); - /** - Remove the @a mask from the list of allowed masks for - wxLogTrace(). - - @see AddTraceMask() - */ - static void RemoveTraceMask(const wxString& mask); - - /** - Resumes logging previously suspended by a call to Suspend(). - All messages logged in the meanwhile will be flushed soon. - */ - static void Resume(); - - /** - 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 wxLog* SetActiveTarget(wxLog* logtarget); - /** Sets the log level for the given component. @@ -918,44 +818,58 @@ public: @see SetComponentLevel() */ static void SetLogLevel(wxLogLevel logLevel); + + //@} + + /** - Enables logging mode in which a log message is logged once, and in case exactly - the same message successively repeats one or more times, only the number of - repetitions is logged. + @name Enable/disable features functions */ - 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. + Globally enable or disable logging. - Notice that unlike for SetActiveTarget(), wxWidgets does not destroy - the thread-specific log targets when the thread terminates so doing - this is your responsibility. + Calling this function with @false argument disables all log messages + for the current thread. - This method is only available if @c wxUSE_THREADS is 1, i.e. wxWidgets - was compiled with threads support. + @see wxLogNull, IsEnabled() - @param logger - The new thread-specific log target, possibly @NULL. @return - The previous thread-specific log target, initially @NULL. + The old state, i.e. @true if logging was previously enabled and + @false if it was disabled. + */ + static bool EnableLogging(bool enable = true); - @since 2.9.1 + /** + Returns true if logging is enabled at all now. + + @see IsLevelEnabled(), EnableLogging() */ - static wxLog *SetThreadActiveTarget(wxLog *logger); + 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 + the same message successively repeats one or more times, only the number of + repetitions is logged. + */ + static void SetRepetitionCounting(bool repetCounting = true); + + /** + Returns the current timestamp format string. + */ + 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. */ static void SetTimestamp(const wxString& format); @@ -966,35 +880,39 @@ public: @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. - - 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 - 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). + 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. - @see Resume(), wxLogNull + If you override this method in a derived class, call the base class + version first, before doing anything else. */ - static void Suspend(); - + virtual void Flush(); + /** Log the given record. @@ -1041,7 +959,7 @@ 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 @@ -1262,7 +1180,7 @@ void wxVLogError(const char* formatString, va_list argPtr); /** @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 @@ -1274,30 +1192,10 @@ 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. - 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: @@ -1310,22 +1208,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 */ @@ -1415,7 +1301,7 @@ void wxVLogSysError(const char* formatString, va_list argPtr); @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(). + build when not using wxIMPLEMENT_APP(). @see wxDISABLE_DEBUG_SUPPORT(), wxDISABLE_ASSERTS_IN_RELEASE_BUILD(),