]> git.saurik.com Git - wxWidgets.git/blobdiff - interface/wx/log.h
Better document wxAutomationObject::GetDispatchPtr() return value.
[wxWidgets.git] / interface / wx / log.h
index 0648a57f8429841f80dccbede437013039a6a5cc..d8ffb8d27a9746832768d89d68713c422defa7e3 100644 (file)
@@ -1,11 +1,73 @@
 /////////////////////////////////////////////////////////////////////////////
 // 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
+    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 (<code>wxUSE_THREADS == 1</code>).
+
+        @see wxThread::GetCurrentId()
+     */
+    wxThreadIdType threadId;
+};
+
 /**
     @class wxLogWindow
 
@@ -26,17 +88,19 @@ public:
     /**
         Creates the log frame window and starts collecting the messages in it.
 
-        @param parent
+        @param pParent
             The parent window for the log frame, may be @NULL
-        @param title
+        @param szTitle
             The title for the log frame
         @param show
             @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);
@@ -57,19 +121,19 @@ public:
 
         @see OnFrameDelete()
     */
-    virtual bool OnFrameClose(wxFrame frame);
+    virtual bool OnFrameClose(wxFrame* frame);
 
     /**
         Called immediately after the log frame creation allowing for
         any extra initializations.
     */
-    virtual void OnFrameCreate(wxFrame frame);
+    virtual void OnFrameCreate(wxFrame* frame);
 
     /**
         Called right before the log frame is going to be deleted: will
         always be called unlike OnFrameClose().
     */
-    virtual void OnFrameDelete(wxFrame frame);
+    virtual void OnFrameDelete(wxFrame* frame);
 
     /**
         Shows or hides the frame.
@@ -396,7 +460,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);
 };
 
 
@@ -405,8 +469,10 @@ public:
     @class wxLogStderr
 
     This class can be used to redirect the log messages to a C file stream (not to
-    be confused with C++ streams). It is the default log target for the non-GUI
-    wxWidgets applications which send all the output to @c stderr.
+    be confused with C++ streams).
+
+    It is the default log target for the non-GUI wxWidgets applications which
+    send all the output to @c stderr.
 
     @library{wxbase}
     @category{logging}
@@ -443,6 +509,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
@@ -456,7 +527,7 @@ public:
         The buffer can be cleared by Flush() which will also show the current
         contents to the user.
     */
-    const wxString GetBuffer();
+    const wxString& GetBuffer() const;
 };
 
 
@@ -515,153 +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 <em>log targets</em> 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.
-
-    Otherwise, it is completely hidden behind the @e wxLogXXX() functions and
-    you may not even know about its existence.
-
-
-    @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.
-
-    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).
-
-    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 also:
-    @li Flush()
-    @li FlushActive()
-
-
-    @section log_tracemasks Using trace masks
-
-    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 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.
-
-    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
-
-    will log the message if it was preceded by:
-
-    @code
-    wxLog::AddTraceMask( wxTRACE_OleCalls);
-    @endcode
+    needs.
 
-    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
-    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 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()
+    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.
 
     @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().
 
@@ -677,133 +627,232 @@ public:
     static void ClearTraceMasks();
 
     /**
-        Disables time stamping of the log messages.
+        Returns the currently allowed list of string trace masks.
 
-        @since 2.9.0
+        @see AddTraceMask().
     */
-    static void SetTimestamp(const wxString& format);
+    static const wxArrayString& GetTraceMasks();
 
     /**
-        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.
+        Returns @true if the @a mask is one of allowed masks for wxLogTrace().
 
-        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.
+        See also: AddTraceMask(), RemoveTraceMask()
     */
-    virtual void DoLog(wxLogLevel level, const wxString& msg, time_t timestamp);
+    static bool IsAllowedTraceMask(const wxString& mask);
 
     /**
-        Called to log the specified string. The timestamp is already included in the
-        string but still passed to this function.
+        Remove the @a mask from the list of allowed masks for
+        wxLogTrace().
 
-        A simple implementation may just send the string to @c stdout or, better,
-        @c stderr.
+        @see AddTraceMask()
     */
-    virtual void DoLogString(const wxString& msg, time_t timestamp);
+    static void RemoveTraceMask(const wxString& mask);
+    
+    //@}
 
-    /**
-        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.
 
-        Note that this function also calls ClearTraceMasks().
-    */
-    static void DontCreateOnDemand();
 
     /**
-        Shows all the messages currently in buffer and clears it.
-        If the buffer is already empty, nothing happens.
+        @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).
 
-        @see Flush()
+        Note that this function also calls ClearTraceMasks().
     */
-    static void FlushActive();
+    static void DontCreateOnDemand();
 
     /**
         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.
+        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 wxLogLevel GetLogLevel();
+    static wxLog* SetActiveTarget(wxLog* logtarget);
 
     /**
-        Returns whether the repetition counting mode is enabled.
-    */
-    static bool GetRepetitionCounting();
+        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 current timestamp format string.
-    */
-    static const wxString GetTimestamp();
+        Flushes the current log target if any, does nothing if there is none.
 
+        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 current trace mask, see Customization() section for details.
+        Resumes logging previously suspended by a call to Suspend().
+        All messages logged in the meanwhile will be flushed soon.
     */
-    static wxTraceMask GetTraceMask();
+    static void Resume();
 
     /**
-        Returns the currently allowed list of string trace masks.
+        Suspends the logging until Resume() is called.
 
-        @see AddTraceMask().
+        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).
+
+        @see Resume(), wxLogNull
     */
-    static const wxArrayString GetTraceMasks();
+    static void Suspend();
+    
+    //@}
+    
+
 
     /**
-        Returns whether the verbose mode is currently active.
+        @name Log level functions
     */
-    static bool GetVerbose();
-
+    //@{
+    
     /**
-        Returns @true if the @a mask is one of allowed masks for wxLogTrace().
+        Returns the current log level limit.
 
-        See also: AddTraceMask(), RemoveTraceMask()
+        All messages at levels strictly greater than the value returned by this
+        function are not logged at all.
+
+        @see SetLogLevel(), IsLevelEnabled()
     */
-    static bool IsAllowedTraceMask(const wxString& mask);
+    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);
 
     /**
-        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);
+        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);
 
     /**
-        Remove the @a mask from the list of allowed masks for
-        wxLogTrace().
+        Specifies that log messages with level greater (numerically) than
+        @a logLevel should be ignored and not sent to the active log target.
 
-        @see AddTraceMask()
+        @see SetComponentLevel()
     */
-    static void RemoveTraceMask(const wxString& mask);
+    static void SetLogLevel(wxLogLevel logLevel);
+    
+    //@}
+
+
 
     /**
-        Resumes logging previously suspended by a call to Suspend().
-        All messages logged in the meanwhile will be flushed soon.
+        @name Enable/disable features functions
     */
-    static void Resume();
-
+    //@{
+    
     /**
-        Sets the specified log target as the active one.
+        Globally enable or disable logging.
 
-        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);
+        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();
+    
     /**
-        Specifies that log messages with level  logLevel should be ignored
-        and not sent to the active log target.
+        Returns whether the repetition counting mode is enabled.
     */
-    static void SetLogLevel(wxLogLevel logLevel);
+    static bool GetRepetitionCounting();
 
     /**
         Enables logging mode in which a log message is logged once, and in case exactly
@@ -811,6 +860,11 @@ public:
         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
@@ -821,31 +875,127 @@ public:
     static void SetTimestamp(const wxString& format);
 
     /**
-        Sets the trace mask, see @ref log_derivingyours section for details.
+        Disables time stamping of the log messages.
+
+        @since 2.9.0
     */
-    static void SetTraceMask(wxTraceMask mask);
+    static void DisableTimestamp();
+    
+    /**
+        Returns whether the verbose mode is currently active.
+    */
+    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.
+        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.
 
-        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.
+        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 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);
 
-        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).
+protected:
+    /**
+        @name Logging callbacks.
 
-        @see Resume(), wxLogNull
+        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 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().
+
+        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().
     */
-    static void Suspend();
+    virtual void DoLogTextAtLevel(wxLogLevel level, const wxString& msg);
+
+    /**
+        Called to log the specified string.
+
+        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 DoLogText(const wxString& msg);
+
+    //@}
 };
 
 
@@ -898,7 +1048,7 @@ public:
     @library{wxbase}
     @category{logging}
 */
-class wxLogNull : public wxLog
+class wxLogNull
 {
 public:
     /**
@@ -918,7 +1068,7 @@ public:
 // Global functions/macros
 // ============================================================================
 
-/** @ingroup group_funcmacro_log */
+/** @addtogroup group_funcmacro_log */
 //@{
 
 /**
@@ -964,7 +1114,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
@@ -976,7 +1126,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
@@ -989,7 +1139,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
@@ -1001,7 +1151,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.
@@ -1014,7 +1164,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
@@ -1027,38 +1177,25 @@ 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
-    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.
+    Log a message at @c wxLOG_Trace log level (see ::wxLogLevelValues enum).
 
-    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.
+    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.
 
-    @header{wx/log.h}
-*/
-void wxLogTrace(const char* formatString, ... );
-void wxVLogTrace(const char* formatString, va_list argPtr);
-//@}
-
-/** @ingroup 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:
@@ -1071,25 +1208,13 @@ void wxVLogTrace(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);
 //@}
 
-/** @ingroup group_funcmacro_log */
+/** @addtogroup group_funcmacro_log */
 //@{
 /**
     Like wxLogDebug(), trace functions only do something in debug builds and
@@ -1097,10 +1222,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.
 
@@ -1120,7 +1246,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
@@ -1133,7 +1259,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
@@ -1150,7 +1276,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
@@ -1168,3 +1294,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()
+
+//@}
+