]> git.saurik.com Git - wxWidgets.git/blobdiff - interface/wx/log.h
Handle underlined and strikethrough attributes in wxGTK native font info.
[wxWidgets.git] / interface / wx / log.h
index 50042f4262e563e195cb6c61bf30f034c336aead..1bf3a66d37741e817e5172ad35c56949541fd19c 100644 (file)
@@ -1,15 +1,15 @@
 /////////////////////////////////////////////////////////////////////////////
 // Name:        log.h
-// Purpose:     interface of wxLogWindow
+// Purpose:     interface of wxLog* classes
 // Author:      wxWidgets team
 // RCS-ID:      $Id$
-// Licence:     wxWindows license
+// Licence:     wxWindows licence
 /////////////////////////////////////////////////////////////////////////////
 
 
 /**
     Different standard log levels (you may also define your own) used with
-    by standard wxLog functions wxLogError(), wxLogWarning(), etc...
+    by standard wxLog functions wxLogGeneric(), wxLogError(), wxLogWarning(), etc...
 */
 enum wxLogLevelValues
 {
@@ -37,8 +37,23 @@ typedef unsigned long wxLogLevel;
 /**
     Information about a log record (unit of the log output).
  */
-struct wxLogRecordInfo
+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;
 
@@ -81,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);
@@ -274,8 +291,8 @@ public:
     to the native behaviour but it doesn't give the user any possibility to
     copy or save the message (except for the recent Windows versions where @c
     Ctrl-C may be pressed in the message box to copy its contents to the
-    clipboard) so you may want to override DoShowSingleMessage() to customize
-    wxLogGui -- the dialogs sample shows how to do this.
+    clipboard) so you may want to override DoShowSingleLogMessage() to
+    customize wxLogGui -- the dialogs sample shows how to do this.
 
     @library{wxcore}
     @category{logging}
@@ -325,51 +342,6 @@ protected:
     void Clear();
 
 
-    /**
-        Method called by Flush() to show a single log message.
-
-        This function can be overridden to show the message in a different way.
-        By default a simple wxMessageBox() call is used.
-
-        @param message
-            The message to show (it can contain multiple lines).
-        @param title
-            The suggested title for the dialog showing the message, see
-            GetTitle().
-        @param style
-            One of @c wxICON_XXX constants, see GetSeverityIcon().
-     */
-    virtual void DoShowSingleLogMessage(const wxString& message,
-                                        const wxString& title,
-                                        int style);
-
-    /**
-        Method called by Flush() to show multiple log messages.
-
-        This function can be overridden to show the messages in a different way.
-        By default a special log dialog showing the most recent message and
-        allowing the user to expand it to view the previously logged ones is
-        used.
-
-        @param messages
-            Array of messages to show; it contains more than one element.
-        @param severities
-            Array of message severities containing @c wxLOG_XXX values.
-        @param times
-            Array of time_t values indicating when each message was logged.
-        @param title
-            The suggested title for the dialog showing the message, see
-            GetTitle().
-        @param style
-            One of @c wxICON_XXX constants, see GetSeverityIcon().
-     */
-    virtual void DoShowMultipleLogMessages(const wxArrayString& messages,
-                                           const wxArrayInt& severities,
-                                           const wxArrayLong& times,
-                                           const wxString& title,
-                                           int style);
-
-
     /**
         All currently accumulated messages.
 
@@ -419,6 +391,51 @@ protected:
         array hasn't been emptied yet.
      */
     bool m_bHasMessages;
+
+private:
+    /**
+        Method called by Flush() to show a single log message.
+
+        This function can be overridden to show the message in a different way.
+        By default a simple wxMessageBox() call is used.
+
+        @param message
+            The message to show (it can contain multiple lines).
+        @param title
+            The suggested title for the dialog showing the message, see
+            GetTitle().
+        @param style
+            One of @c wxICON_XXX constants, see GetSeverityIcon().
+     */
+    virtual void DoShowSingleLogMessage(const wxString& message,
+                                        const wxString& title,
+                                        int style);
+
+    /**
+        Method called by Flush() to show multiple log messages.
+
+        This function can be overridden to show the messages in a different way.
+        By default a special log dialog showing the most recent message and
+        allowing the user to expand it to view the previously logged ones is
+        used.
+
+        @param messages
+            Array of messages to show; it contains more than one element.
+        @param severities
+            Array of message severities containing @c wxLOG_XXX values.
+        @param times
+            Array of time_t values indicating when each message was logged.
+        @param title
+            The suggested title for the dialog showing the message, see
+            GetTitle().
+        @param style
+            One of @c wxICON_XXX constants, see GetSeverityIcon().
+     */
+    virtual void DoShowMultipleLogMessages(const wxArrayString& messages,
+                                           const wxArrayInt& severities,
+                                           const wxArrayLong& times,
+                                           const wxString& title,
+                                           int style);
 };
 
 
@@ -566,141 +583,131 @@ public:
 
 
 
+
 /**
-    @class wxLog
+    @class wxLogFormatter
 
-    wxLog class defines the interface for the @e log targets used by wxWidgets
-    logging functions as explained in the @ref overview_log.
-    The only situations when you need to directly use this class is when you want
-    to derive your own log target because the existing ones don't satisfy your
-    needs. Another case is if you wish to customize the behaviour of the standard
-    logging classes (all of which respect the wxLog settings): for example, set
-    which trace messages are logged and which are not or change (or even remove
-    completely) the timestamp on the messages.
+    wxLogFormatter class is used to format the log messages. It implements the
+    default formatting and can be derived from to create custom formatters.
 
-    Otherwise, it is completely hidden behind the @e wxLogXXX() functions and
-    you may not even know about its existence.
+    The default implementation formats the message into a string containing
+    the time stamp, level-dependent prefix and the message itself.
 
-    @note For console-mode applications, the default target is wxLogStderr, so
-          that all @e wxLogXXX() functions print on @c stderr when @c wxUSE_GUI = 0.
+    To change it, you can derive from it and override its Format() method. For
+    example, to include the thread id in the log messages you can use
+    @code
+        class LogFormatterWithThread : public wxLogFormatter
+        {
+            virtual wxString Format(wxLogLevel level,
+                                    const wxString& msg,
+                                    const wxLogRecordInfo& info) const
+            {
+                return wxString::Format("[%d] %s(%d) : %s",
+                    info.threadId, info.filename, info.line, msg);
+            }
+        };
+    @endcode
+    And then associate it with wxLog instance using its SetFormatter(). Then,
+    if you call:
 
+    @code
+        wxLogMessage(_("*** Application started ***"));
+    @endcode
 
-    @section log_derivingyours Deriving your own log target
+    the log output could be something like:
 
-    There are two functions which must be implemented by any derived class to
-    actually process the log messages: DoLog() and DoLogString().
-    The second function receives a string which just has to be output in some way
-    and the easiest way to write a new log target is to override just this function
-    in the derived class.
+    @verbatim
+        [7872] d:\testApp\src\testApp.cpp(85) : *** Application started ***
+    @endverbatim
 
-    If more control over the output format is needed, then the first function must
-    be overridden which allows to construct custom messages depending on the log level
-    or even do completely different things depending on the message severity
-    (for example, throw away all messages except warnings and errors, show warnings
-    on the screen and forward the error messages to the user's (or programmer's) cell
-    phone - maybe depending on whether the timestamp tells us if it is day or
-    night in the current time zone).
+    @library{wxbase}
+    @category{logging}
 
-    There also functions to support message buffering. Why are they needed?
-    Some of wxLog implementations, most notably the standard wxLogGui class,
-    buffer the messages (for example, to avoid showing the user a zillion of modal
-    message boxes one after another -- which would be really annoying).
+    @see @ref overview_log
 
-    Flush() shows them all and clears the buffer contents.
-    This function doesn't do anything if the buffer is already empty.
+    @since 2.9.4
+*/
+class wxLogFormatter
+{
+public:
+    /**
+        The default ctor does nothing.
+    */
+    wxLogFormatter();
 
-    See also:
-    @li Flush()
-    @li FlushActive()
 
+    /**
+        This function creates the full log message string.
 
-    @section log_tracemasks Using trace masks
+        Override it to customize the output string format.
 
-    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.
+        @param level
+            The level of this log record, e.g. ::wxLOG_Error.
+        @param msg
+            The log message itself.
+        @param info
+            All the other information (such as time, component, location...)
+            associated with this log record.
 
-    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.
+        @return
+            The formated message.
 
-    For example,
-    @code
-    wxLogTrace( wxTRACE_OleCalls, "IFoo::Bar() called" );
-    @endcode
+        @note
+            Time stamping is disabled for Visual C++ users in debug builds by
+            default because otherwise it would be impossible to directly go to the line
+            from which the log message was generated by simply clicking in the debugger
+            window on the corresponding error message. If you wish to enable it, override
+            FormatTime().
+    */
+    virtual wxString Format(wxLogLevel level,
+                            const wxString& msg,
+                            const wxLogRecordInfo& info) const;
+
+protected:
+    /**
+        This function formats the time stamp part of the log message.
 
-    will log the message if it was preceded by:
+        Override this function if you need to customize just the time stamp.
 
-    @code
-    wxLog::AddTraceMask( wxTRACE_OleCalls);
-    @endcode
+        @param time
+            Time to format.
+
+        @return
+            The formated time string, may be empty.
+    */
+    virtual wxString FormatTime(time_t time) const;
+};
 
-    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()
 
+/**
+    @class wxLog
 
-    @library{wxcore}
+    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.
+
+    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{wxbase}
     @category{logging}
 
-    @see @ref overview_log
+    @see @ref overview_log, @ref group_funcmacro_log "wxLogXXX() functions" 
 */
 class wxLog
 {
 public:
+    /**
+        @name Trace mask functions
+    */
+    //@{
+    
     /**
         Add the @a mask to the list of allowed masks for wxLogTrace().
 
@@ -716,80 +723,114 @@ public:
     static void ClearTraceMasks();
 
     /**
-        Instructs wxLog to not create new log targets on the fly if there is none
-        currently. (Almost) for internal use only: it is supposed to be called by the
-        application shutdown code.
+        Returns the currently allowed list of string trace masks.
 
-        Note that this function also calls ClearTraceMasks().
+        @see AddTraceMask().
     */
-    static void DontCreateOnDemand();
+    static const wxArrayString& GetTraceMasks();
 
     /**
-        Shows all the messages currently in buffer and clears it.
-        If the buffer is already empty, nothing happens.
+        Returns @true if the @a mask is one of allowed masks for wxLogTrace().
+
+        See also: AddTraceMask(), RemoveTraceMask()
     */
-    virtual void Flush();
+    static bool IsAllowedTraceMask(const wxString& mask);
 
     /**
-        Flushes the current log target if any, does nothing if there is none.
+        Remove the @a mask from the list of allowed masks for
+        wxLogTrace().
 
-        @see Flush()
+        @see AddTraceMask()
     */
-    static void FlushActive();
+    static void RemoveTraceMask(const wxString& mask);
+    
+    //@}
 
-    /**
-        Returns the pointer to the active log target (may be @NULL).
-    */
-    static wxLog* GetActiveTarget();
 
-    /**
-        Returns the current log level limit.
-    */
-    static wxLogLevel GetLogLevel();
 
     /**
-        Returns whether the repetition counting mode is enabled.
+        @name Log target functions
     */
-    static bool GetRepetitionCounting();
-
+    //@{
+    
     /**
-        Returns the current timestamp format string.
-    */
-    static const wxString& GetTimestamp();
+        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).
 
-    /**
-        @deprecated
-        Returns the current trace mask, see Customization() section for details.
+        Note that this function also calls ClearTraceMasks().
     */
-    static wxTraceMask GetTraceMask();
+    static void DontCreateOnDemand();
 
     /**
-        Returns the currently allowed list of string trace masks.
+        Returns the pointer to the active log target (may be @NULL).
 
-        @see AddTraceMask().
+        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 const wxArrayString& GetTraceMasks();
+    static wxLog* GetActiveTarget();
 
     /**
-        Returns whether the verbose mode is currently active.
+        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 bool GetVerbose();
+    static wxLog* SetActiveTarget(wxLog* logtarget);
 
     /**
-        Returns @true if the @a mask is one of allowed masks for wxLogTrace().
+        Sets a thread-specific log target.
 
-        See also: AddTraceMask(), RemoveTraceMask()
-    */
-    static bool IsAllowedTraceMask(const wxString& mask);
+        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);
+    
     /**
-        Remove the @a mask from the list of allowed masks for
-        wxLogTrace().
+        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 void RemoveTraceMask(const wxString& mask);
-
+    static void FlushActive();
+    
     /**
         Resumes logging previously suspended by a call to Suspend().
         All messages logged in the meanwhile will be flushed soon.
@@ -797,20 +838,117 @@ public:
     static void Resume();
 
     /**
-        Sets the specified log target as the active one.
+        Suspends the logging until Resume() is called.
 
-        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.
+        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 wxLog* SetActiveTarget(wxLog* logtarget);
+    static void Suspend();
+    
+    //@}
+    
+
+
+    /**
+        @name Log level functions
+    */
+    //@{
+    
+    /**
+        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();
+    
+    /**
+        Returns true if logging at this level is enabled for the current thread.
+
+        This function only returns @true if logging is globally enabled and if
+        @a level is less than or equal to the maximal log level enabled for the
+        given @a component.
+
+        @see IsEnabled(), SetLogLevel(), GetLogLevel(), SetComponentLevel()
+
+        @since 2.9.1
+     */
+    static bool IsLevelEnabled(wxLogLevel level, wxString component);
+
+    /**
+        Sets the 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);
+    
+    //@}
+
+
+
+    /**
+        @name Enable/disable features functions
+    */
+    //@{
+    
+    /**
+        Globally enable or disable logging.
+
+        Calling this function with @false argument disables all log messages
+        for the current thread.
+
+        @see wxLogNull, IsEnabled()
+
+        @return
+            The old state, i.e. @true if logging was previously enabled and
+            @false if it was disabled.
+     */
+    static bool EnableLogging(bool enable = true);
+
+    /**
+        Returns true if logging is enabled at all now.
+
+        @see IsLevelEnabled(), EnableLogging()
+     */
+    static bool IsEnabled();
+    
+    /**
+        Returns whether the repetition counting mode is enabled.
+    */
+    static bool GetRepetitionCounting();
 
     /**
         Enables logging mode in which a log message is logged once, and in case exactly
@@ -818,50 +956,83 @@ public:
         repetitions is logged.
     */
     static void SetRepetitionCounting(bool repetCounting = true);
+    
+    /**
+        Returns the current timestamp format string.
+
+        Notice that the current time stamp is only used by the default log
+        formatter and custom formatters may ignore this format.
+    */
+    static const wxString& GetTimestamp();
 
     /**
         Sets the timestamp format prepended by the default log targets to all
         messages. The string may contain any normal characters as well as %
-        prefixed format specificators, see @e strftime() manual for details.
+        prefixed format specifiers, see @e strftime() manual for details.
         Passing an empty string to this function disables message time stamping.
+
+        Notice that the current time stamp is only used by the default log
+        formatter and custom formatters may ignore this format. You can also
+        define a custom wxLogFormatter to customize the time stamp handling
+        beyond changing its format.
     */
     static void SetTimestamp(const wxString& format);
 
     /**
         Disables time stamping of the log messages.
 
+        Notice that the current time stamp is only used by the default log
+        formatter and custom formatters may ignore calls to this function.
+
         @since 2.9.0
     */
     static void DisableTimestamp();
-
+    
     /**
-        @deprecated
-        Sets the trace mask, see @ref log_tracemasks section for details.
+        Returns whether the verbose mode is currently active.
     */
-    static void SetTraceMask(wxTraceMask mask);
+    static bool GetVerbose();
 
     /**
         Activates or deactivates verbose mode in which the verbose messages are
         logged as the normal ones instead of being silently dropped.
+        
+        The verbose messages are the trace messages which are not disabled in the
+        release mode and are generated by wxLogVerbose().
+        
+        @see @ref overview_log
     */
     static void SetVerbose(bool verbose = true);
+    
+    //@}
+    
 
     /**
-        Suspends the logging until Resume() is called.
+        Sets the specified formatter as the active one.
 
-        Note that the latter must be called the same number of times as the former
-        to undo it, i.e. if you call Suspend() twice you must call Resume() twice as well.
+        @param formatter
+            The new formatter. If @NULL, reset to the default formatter.
 
-        Note that suspending the logging means that the log sink won't be be flushed
-        periodically, it doesn't have any effect if the current log target does the
-        logging immediately without waiting for Flush() to be called (the standard
-        GUI log target only shows the log dialog when it is flushed, so Suspend()
-        works as expected with it).
+        Returns the pointer to the previous formatter. You must delete it
+        if you don't plan to attach it again to a wxLog object later.
 
-        @see Resume(), wxLogNull
+        @since 2.9.4
     */
-    static void Suspend();
+    wxLogFormatter *SetFormatter(wxLogFormatter* formatter);
+    
 
+    /**
+        Some of wxLog implementations, most notably the standard wxLogGui class,
+        buffer the messages (for example, to avoid showing the user a zillion of modal
+        message boxes one after another -- which would be really annoying).
+        This function shows them all and clears the buffer contents.
+        If the buffer is already empty, nothing happens.
+
+        If you override this method in a derived class, call the base class
+        version first, before doing anything else.
+    */
+    virtual void Flush();
+    
     /**
         Log the given record.
 
@@ -891,7 +1062,7 @@ public:
 
         @since 2.9.1
      */
-    void LogRecord(wxLogLevel level, const wxString& msg, time_t timestamp);
+    void LogRecord(wxLogLevel level, const wxString& msg, const wxLogRecordInfo& info);
 
 protected:
     /**
@@ -908,7 +1079,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
@@ -1063,6 +1234,18 @@ const wxChar* wxSysErrorMsg(unsigned long errCode = 0);
 
 //@}
 
+/** @addtogroup group_funcmacro_log */
+//@{
+/**
+    Logs a message with the given wxLogLevel.
+    E.g. using @c wxLOG_Message as first argument, this function behaves like wxLogMessage().
+
+    @header{wx/log.h}
+*/
+void wxLogGeneric(wxLogLevel level, const char* formatString, ... );
+void wxVLogGeneric(wxLogLevel level, const char* formatString, va_list argPtr);
+//@}
+
 /** @addtogroup group_funcmacro_log */
 //@{
 /**
@@ -1129,35 +1312,22 @@ void wxVLogError(const char* formatString, va_list argPtr);
 /** @addtogroup group_funcmacro_log */
 //@{
 /**
-    Like wxLogDebug(), trace functions only do something in debug builds and
-    expand to nothing in the release one. The reason for making it a separate
-    function is that usually there are a lot of trace messages, so it might
-    make sense to separate them from other debug messages.
-
-    wxLogTrace(const char*,const char*,...) and can be used instead of
-    wxLogDebug() if you would like to be able to separate trace messages into
-    different categories which can be enabled or disabled with
-    wxLog::AddTraceMask() and wxLog::RemoveTraceMask().
+    Log a message at @c wxLOG_Trace log level (see ::wxLogLevelValues enum).
 
-    @header{wx/log.h}
-*/
-void wxLogTrace(const char *mask, const char* formatString, ... );
-void wxVLogTrace(const char *mask, const char* formatString, va_list argPtr);
-//@}
+    Notice that the use of trace masks is not recommended any more as setting
+    the log components (please see @ref overview_log_enable) provides a way to
+    do the same thing for log messages of any level, and not just the tracing
+    ones.
 
-/** @addtogroup group_funcmacro_log */
-//@{
-/**
     Like wxLogDebug(), trace functions only do something in debug builds and
     expand to nothing in the release one. The reason for making it a separate
     function is that usually there are a lot of trace messages, so it might
     make sense to separate them from other debug messages.
 
-    In this version of wxLogTrace(), trace messages can be separated into
-    different categories and calls using this function only log the message if
-    the given @a mask is currently enabled in wxLog. This lets you selectively
-    trace only some operations and not others by enabling the desired trace
-    masks with wxLog::AddTraceMask() or by setting the
+    Trace messages can be separated into different categories; these functions in facts
+    only log the message if the given @a mask is currently enabled in wxLog. 
+    This lets you selectively trace only some operations and not others by enabling the 
+    desired trace masks with wxLog::AddTraceMask() or by setting the
     @ref overview_envvars "@c WXTRACE environment variable".
 
     The predefined string trace masks used by wxWidgets are:
@@ -1170,22 +1340,10 @@ void wxVLogTrace(const char *mask, const char* formatString, va_list argPtr);
     @itemdef{ wxTRACE_OleCalls, Trace OLE method calls (Win32 only) }
     @endDefList
 
-    @note Since both the mask and the format string are strings, this might
-          lead to function signature confusion in some cases: if you intend to
-          call the format string only version of wxLogTrace(), add a "%s"
-          format string parameter and then supply a second string parameter for
-          that "%s", the string mask version of wxLogTrace() will erroneously
-          get called instead, since you are supplying two string parameters to
-          the function. In this case you'll unfortunately have to avoid having
-          two leading string parameters, e.g. by adding a bogus integer (with
-          its "%d" format string).
-
     @header{wx/log.h}
 */
 void wxLogTrace(const char* mask, const char* formatString, ... );
-void wxVLogTrace(const char* mask,
-                  const char* formatString,
-                  va_list argPtr);
+void wxVLogTrace(const char* mask, const char* formatString, va_list argPtr);
 //@}
 
 /** @addtogroup group_funcmacro_log */
@@ -1255,7 +1413,7 @@ void wxVLogStatus(const char* formatString, va_list argPtr);
 /**
     Mostly used by wxWidgets itself, but might be handy for logging errors
     after system call (API function) failure. It logs the specified message
-    text as well as the last system error code (@e errno or @e ::GetLastError()
+    text as well as the last system error code (@e errno or @e GetLastError()
     depending on the platform) and the corresponding error message. The second
     form of this function takes the error code explicitly as the first
     argument.
@@ -1268,3 +1426,24 @@ void wxLogSysError(const char* formatString, ... );
 void wxVLogSysError(const char* formatString, va_list argPtr);
 //@}
 
+/** @addtogroup group_funcmacro_debug */
+//@{
+
+/**
+    @def wxDISABLE_DEBUG_LOGGING_IN_RELEASE_BUILD()
+
+    Use this macro to disable logging at debug and trace levels in release
+    build when not using wxIMPLEMENT_APP().
+
+    @see wxDISABLE_DEBUG_SUPPORT(),
+         wxDISABLE_ASSERTS_IN_RELEASE_BUILD(),
+         @ref overview_debugging
+
+    @since 2.9.1
+
+    @header{wx/log.h}
+ */
+#define wxDISABLE_DEBUG_LOGGING_IN_RELEASE_BUILD()
+
+//@}
+