Fix regression with wxHTML table elements background handling.

[wxWidgets.git] / interface / wx / log.h

diff --git a/interface/wx/log.h b/interface/wx/log.h
index db420030f5ea4b76575ec96d26d46db2255be88b..998f0159590acb5c810df9d6aa46163ab92a7c5b 100644 (file)
--- a/interface/wx/log.h
+++ b/interface/wx/log.h
@@ -6,6 +6,7 @@
 // Licence:     wxWindows licence
 /////////////////////////////////////////////////////////////////////////////
 
 // Licence:     wxWindows licence
 /////////////////////////////////////////////////////////////////////////////
 

+#if wxUSE_BASE

 
 /**
     Different standard log levels (you may also define your own) used with
 
 /**
     Different standard log levels (you may also define your own) used with


@@ -69,1120 +70,1124 @@ public:
 };
 
 /**
 };
 
 /**

-    @class wxLogWindow
+    @class wxLogFormatter

 
 

-    This class represents a background log window: to be precise, it collects all
-    log messages in the log frame which it manages but also passes them on to the
-    log target which was active at the moment of its creation. This allows you, for
-    example, to show all the log messages in a frame but still continue to process
-    them normally by showing the standard log dialog.
+    wxLogFormatter class is used to format the log messages. It implements the
+    default formatting and can be derived from to create custom formatters.

 
 

-    @library{wxcore}
+    The default implementation formats the message into a string containing
+    the time stamp, level-dependent prefix and the message itself.
+
+    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
+
+    the log output could be something like:
+
+    @verbatim
+        [7872] d:\testApp\src\testApp.cpp(85) : *** Application started ***
+    @endverbatim
+
+    @library{wxbase}

     @category{logging}
 
     @category{logging}
 

-    @see wxLogTextCtrl
+    @see @ref overview_log
+
+    @since 2.9.4

 */
 */

-class wxLogWindow : public wxLogInterposer
+class wxLogFormatter

 {
 public:
     /**
 {
 public:
     /**

-        Creates the log frame window and starts collecting the messages in it.
-
-        @param pParent
-            The parent window for the log frame, may be @NULL
-        @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.
-            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.
+        The default ctor does nothing.

     */
     */

-    wxLogWindow(wxWindow* pParent, const wxString& szTitle, bool show = true,
-                bool passToOld = true);
+    wxLogFormatter();

 
 

-    /**
-        Returns the associated log frame window. This may be used to position or resize
-        it but use Show() to show or hide it.
-    */
-    wxFrame* GetFrame() const;

 
     /**
 
     /**

-        Called if the user closes the window interactively, will not be
-        called if it is destroyed for another reason (such as when program
-        exits).
+        This function creates the full log message string.

 
 

-        Return @true from here to allow the frame to close, @false to
-        prevent this from happening.
+        Override it to customize the output string format.

 
 

-        @see OnFrameDelete()
-    */
-    virtual bool OnFrameClose(wxFrame* frame);
+        @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.

 
 

-    /**
-        Called immediately after the log frame creation allowing for
-        any extra initializations.
-    */
-    virtual void OnFrameCreate(wxFrame* frame);
+        @return
+            The formated message.

 
 

-    /**
-        Called right before the log frame is going to be deleted: will
-        always be called unlike OnFrameClose().
+        @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 void OnFrameDelete(wxFrame* frame);
+    virtual wxString Format(wxLogLevel level,
+                            const wxString& msg,
+                            const wxLogRecordInfo& info) const;

 
 

+protected:

     /**
     /**

-        Shows or hides the frame.
-    */
-    void Show(bool show = true);
-};
-
-
-
-/**
-    @class wxLogInterposerTemp
+        This function formats the time stamp part of the log message.

 
 

-    A special version of wxLogChain which uses itself as the new log target.
-    It forwards log messages to the previously installed one in addition to
-    processing them itself. Unlike wxLogInterposer, it doesn't delete the old
-    target which means it can be used to temporarily redirect log output.
+        Override this function if you need to customize just the time stamp.

 
 

-    As per wxLogInterposer, this class must be derived from to implement
-    wxLog::DoLog and/or wxLog::DoLogString methods.
+        @param time
+            Time to format.

 
 

-    @library{wxbase}
-    @category{logging}
-*/
-class wxLogInterposerTemp : public wxLogChain
-{
-public:
-    /**
-        The default constructor installs this object as the current active log target.
+        @return
+            The formated time string, may be empty.

     */
     */

-    wxLogInterposerTemp();
+    virtual wxString FormatTime(time_t time) const;

 };
 
 
 };
 
 

-

 /**
 /**

-    @class wxLogChain
-
-    This simple class allows you to chain log sinks, that is to install a new sink but
-    keep passing log messages to the old one instead of replacing it completely as
-    wxLog::SetActiveTarget does.
-
-    It is especially useful when you want to divert the logs somewhere (for
-    example to a file or a log window) but also keep showing the error messages
-    using the standard dialogs as wxLogGui does by default.
+    @class wxLog

 
 

-    Example of usage:
+    wxLog class defines the interface for the <em>log targets</em> used by wxWidgets
+    logging functions as explained in the @ref overview_log.

 
 

-    @code
-    wxLogChain *logChain = new wxLogChain(new wxLogStderr);
+    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.

 
 

-    // all the log messages are sent to stderr and also processed as usually
-    ...
+    Otherwise, it is completely hidden behind the @ref group_funcmacro_log "wxLogXXX() functions"
+    and you may not even know about its existence.

 
 

-    // don't delete logChain directly as this would leave a dangling
-    // pointer as active log target, use SetActiveTarget() instead
-    delete wxLog::SetActiveTarget(...something else or NULL...);
-    @endcode
+    @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}
 
     @library{wxbase}
     @category{logging}

+
+    @see @ref overview_log, @ref group_funcmacro_log "wxLogXXX() functions"

 */
 */

-class wxLogChain : public wxLog
+class wxLog

 {
 public:
     /**
 {
 public:
     /**

-        Sets the specified @c logger (which may be @NULL) as the default log
-        target but the log messages are also passed to the previous log target if any.
+        @name Trace mask functions

     */
     */

-    wxLogChain(wxLog* logger);
+    //@{

 
     /**
 
     /**

-        Destroys the previous log target.
-    */
-    virtual ~wxLogChain();
+        Add the @a mask to the list of allowed masks for wxLogTrace().

 
 

-    /**
-        Detaches the old log target so it won't be destroyed when the wxLogChain object
-        is destroyed.
+        @see RemoveTraceMask(), GetTraceMasks()

     */
     */

-    void DetachOldLog();
+    static void AddTraceMask(const wxString& mask);

 
     /**
 
     /**

-        Returns the pointer to the previously active log target (which may be @NULL).
+        Removes all trace masks previously set with AddTraceMask().
+
+        @see RemoveTraceMask()

     */
     */

-    wxLog* GetOldLog() const;
+    static void ClearTraceMasks();

 
     /**
 
     /**

-        Returns @true if the messages are passed to the previously active log
-        target (default) or @false if PassMessages() had been called.
+        Returns the currently allowed list of string trace masks.
+
+        @see AddTraceMask().

     */
     */

-    bool IsPassingMessages() const;
+    static const wxArrayString& GetTraceMasks();

 
     /**
 
     /**

-        By default, the log messages are passed to the previously active log target.
-        Calling this function with @false parameter disables this behaviour
-        (presumably temporarily, as you shouldn't use wxLogChain at all otherwise) and
-        it can be reenabled by calling it again with @a passMessages set to @true.
+        Returns @true if the @a mask is one of allowed masks for wxLogTrace().
+
+        See also: AddTraceMask(), RemoveTraceMask()

     */
     */

-    void PassMessages(bool passMessages);
+    static bool IsAllowedTraceMask(const wxString& mask);

 
     /**
 
     /**

-        Sets another log target to use (may be @NULL).
+        Remove the @a mask from the list of allowed masks for
+        wxLogTrace().

 
 

-        The log target specified in the wxLogChain(wxLog*) constructor or in a
-        previous call to this function is deleted.
-        This doesn't change the old log target value (the one the messages are
-        forwarded to) which still remains the same as was active when wxLogChain
-        object was created.
+        @see AddTraceMask()

     */
     */

-    void SetLog(wxLog* logger);
-};
-
+    static void RemoveTraceMask(const wxString& mask);

 
 

+    //@}

 
 

-/**
-    @class wxLogGui

 
 

-    This is the default log target for the GUI wxWidgets applications.

 
 

-    Please see @ref overview_log_customize for explanation of how to change the
-    default log target.
+    /**
+        @name Log target functions
+    */
+    //@{

 
 

-    An object of this class is used by default to show the log messages created
-    by using wxLogMessage(), wxLogError() and other logging functions. It
-    doesn't display the messages logged by them immediately however but
-    accumulates all messages logged during an event handler execution and then
-    shows them all at once when its Flush() method is called during the idle
-    time processing. This has the important advantage of showing only a single
-    dialog to the user even if several messages were logged because of a single
-    error as it often happens (e.g. a low level function could log a message
-    because it failed to open a file resulting in its caller logging another
-    message due to the failure of higher level operation requiring the use of
-    this file). If you need to force the display of all previously logged
-    messages immediately you can use wxLog::FlushActive() to force the dialog
-    display.
+    /**
+        Instructs wxLog to not create new log targets on the fly if there is none
+        currently (see GetActiveTarget()).

 
 

-    Also notice that if an error message is logged when several informative
-    messages had been already logged before, the informative messages are
-    discarded on the assumption that they are not useful -- and may be
-    confusing and hence harmful -- any more after the error. The warning
-    and error messages are never discarded however and any informational
-    messages logged after the first error one are also kept (as they may
-    contain information about the error recovery). You may override DoLog()
-    method to change this behaviour.
+        (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).

 
 

-    At any rate, it is possible that that several messages were accumulated
-    before this class Flush() method is called. If this is the case, Flush()
-    uses a custom dialog which shows the last message directly and allows the
-    user to view the previously logged ones by expanding the "Details"
-    wxCollapsiblePane inside it. This custom dialog also provides the buttons
-    for copying the log messages to the clipboard and saving them to a file.
-
-    However if only a single message is present when Flush() is called, just a
-    wxMessageBox() is used to show it. This has the advantage of being closer
-    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 DoShowSingleLogMessage() to
-    customize wxLogGui -- the dialogs sample shows how to do this.
+        Note that this function also calls ClearTraceMasks().
+    */
+    static void DontCreateOnDemand();

 
 

-    @library{wxcore}
-    @category{logging}
-*/
-class wxLogGui : public wxLog
-{
-public:

     /**
     /**

-        Default constructor.
+        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.

     */
     */

-    wxLogGui();
+    static wxLog* GetActiveTarget();

 
     /**
 
     /**

-        Presents the accumulated log messages, if any, to the user.
+        Sets the specified log target as the active one.

 
 

-        This method is called during the idle time and should show any messages
-        accumulated in wxLogGui#m_aMessages field to the user.
-     */
-    virtual void Flush();
+        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);

 
 

-protected:

     /**
     /**

-        Returns the appropriate title for the dialog.
+        Sets a thread-specific log target.

 
 

-        The title is constructed from wxApp::GetAppDisplayName() and the
-        severity string (e.g. "error" or "warning") appropriate for the current
-        wxLogGui#m_bErrors and wxLogGui#m_bWarnings values.
-     */
-    wxString GetTitle() const;
+        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.

 
 

-    /**
-        Returns wxICON_ERROR, wxICON_WARNING or wxICON_INFORMATION depending on
-        the current maximal severity.
+        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 value is suitable to be used in the style parameter of
-        wxMessageBox() function.
+        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

      */
      */

-    int GetSeverityIcon() const;
+    static wxLog *SetThreadActiveTarget(wxLog *logger);

 
     /**
 
     /**

-        Forgets all the currently stored messages.
+        Flushes the current log target if any, does nothing if there is none.

 
 

-        If you override Flush() (and don't call the base class version), you
-        must call this method to avoid messages being logged over and over
-        again.
-     */
-    void Clear();
+        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();

 
 

+    /**
+        Resumes logging previously suspended by a call to Suspend().
+        All messages logged in the meanwhile will be flushed soon.
+    */
+    static void Resume();

 
     /**
 
     /**

-        All currently accumulated messages.
+        Suspends the logging until Resume() is called.

 
 

-        This array may be empty if no messages were logged.
+        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.

 
 

-        @see m_aSeverity, m_aTimes
-     */
-    wxArrayString m_aMessages;
+        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).

 
 

-    /**
-        The severities of each logged message.
+        @see Resume(), wxLogNull
+    */
+    static void Suspend();

 
 

-        This array is synchronized with wxLogGui#m_aMessages, i.e. the n-th
-        element of this array corresponds to the severity of the n-th message.
-        The possible severity values are @c wxLOG_XXX constants, e.g.
-        wxLOG_Error, wxLOG_Warning, wxLOG_Message etc.
-     */
-    wxArrayInt m_aSeverity;
+    //@}

 
 

-    /**
-        The time stamps of each logged message.

 
 

-        The elements of this array are time_t values corresponding to the time
-        when the message was logged.
-     */
-    wxArrayLong m_aTimes;

 
     /**
 
     /**

-        True if there any error messages.
-     */
-    bool m_bErrors;
+        @name Log level functions
+    */
+    //@{

 
     /**
 
     /**

-        True if there any warning messages.
-
-        If both wxLogGui#m_bErrors and this member are false, there are only
-        informational messages to be shown.
-     */
-    bool m_bWarnings;
+        Returns the current log level limit.

 
 

-    /**
-        True if there any messages to be shown to the user.
+        All messages at levels strictly greater than the value returned by this
+        function are not logged at all.

 
 

-        This variable is used instead of simply checking whether
-        wxLogGui#m_aMessages array is empty to allow blocking further calls to
-        Flush() while a log dialog is already being shown, even if the messages
-        array hasn't been emptied yet.
-     */
-    bool m_bHasMessages;
+        @see SetLogLevel(), IsLevelEnabled()
+    */
+    static wxLogLevel GetLogLevel();

 
 

-private:

     /**
     /**

-        Method called by Flush() to show a single log message.
+        Returns true if logging at this level is enabled for the current thread.

 
 

-        This function can be overridden to show the message in a different way.
-        By default a simple wxMessageBox() call is used.
+        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.

 
 

-        @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().
+        @see IsEnabled(), SetLogLevel(), GetLogLevel(), SetComponentLevel()
+
+        @since 2.9.1

      */
      */

-    virtual void DoShowSingleLogMessage(const wxString& message,
-                                        const wxString& title,
-                                        int style);
+    static bool IsLevelEnabled(wxLogLevel level, wxString component);

 
     /**
 
     /**

-        Method called by Flush() to show multiple log messages.
+        Sets the log level for the given component.

 
 

-        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.
+        For example, to disable all but error messages from wxWidgets network
+        classes you may use
+        @code
+            wxLog::SetComponentLevel("wx/net", wxLOG_Error);
+        @endcode

 
 

-        @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);
-};
+        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);

 
 

-/**
-    @class wxLogStream
+    /**
+        Specifies that log messages with level greater (numerically) than
+        @a logLevel should be ignored and not sent to the active log target.

 
 

-    This class can be used to redirect the log messages to a C++ stream.
+        @see SetComponentLevel()
+    */
+    static void SetLogLevel(wxLogLevel logLevel);
+
+    //@}

 
 

-    Please note that this class is only available if wxWidgets was compiled with
-    the standard iostream library support (@c wxUSE_STD_IOSTREAM must be on).

 
 

-    @library{wxbase}
-    @category{logging}

 
 

-    @see wxLogStderr, wxStreamToTextRedirector
-*/
-class wxLogStream : public wxLog
-{
-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.
+        @name Enable/disable features functions

     */
     */

-    wxLogStream(std::ostream *ostr = NULL);
-};
+    //@{

 
 

+    /**
+        Globally enable or disable logging.

 
 

+        Calling this function with @false argument disables all log messages
+        for the current thread.

 
 

-/**
-    @class wxLogStderr
+        @see wxLogNull, IsEnabled()

 
 

-    This class can be used to redirect the log messages to a C file stream (not to
-    be confused with C++ streams).
+        @return
+            The old state, i.e. @true if logging was previously enabled and
+            @false if it was disabled.
+     */
+    static bool EnableLogging(bool enable = true);

 
 

-    It is the default log target for the non-GUI wxWidgets applications which
-    send all the output to @c stderr.
+    /**
+        Returns true if logging is enabled at all now.

 
 

-    @library{wxbase}
-    @category{logging}
+        @see IsLevelEnabled(), EnableLogging()
+     */
+    static bool IsEnabled();

 
 

-    @see wxLogStream
-*/
-class wxLogStderr : public wxLog
-{
-public:

     /**
     /**

-        Constructs a log target which sends all the log messages to the given
-        @c FILE. If it is @NULL, the messages are sent to @c stderr.
+        Returns whether the repetition counting mode is enabled.

     */
     */

-    wxLogStderr(FILE* fp = NULL);
-};
+    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.

 
 

-/**
-    @class wxLogBuffer
+        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();

 
 

-    wxLogBuffer is a very simple implementation of log sink which simply collects
-    all the logged messages in a string (except the debug messages which are output
-    in the usual way immediately as we're presumably not interested in collecting
-    them for later). The messages from different log function calls are separated
-    by the new lines.
+    /**
+        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 specifiers, see @e strftime() manual for details.
+        Passing an empty string to this function disables message time stamping.

 
 

-    All the messages collected so far can be shown to the user (and the current
-    buffer cleared) by calling the overloaded wxLogBuffer::Flush method.
+        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);

 
 

-    @library{wxbase}
-    @category{logging}
-*/
-class wxLogBuffer : public wxLog
-{
-public:

     /**
     /**

-        The default ctor does nothing.
+        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

     */
     */

-    wxLogBuffer();
+    static void DisableTimestamp();

 
     /**
 
     /**

-        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
-        clears the internal buffer.
+        Returns whether the verbose mode is currently active.

     */
     */

-    virtual void Flush();
+    static bool GetVerbose();

 
     /**
 
     /**

-        Returns the current buffer contains. Messages from different log function calls
-        are separated with the new lines in the buffer.
-        The buffer can be cleared by Flush() which will also show the current
-        contents to the user.
+        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

     */
     */

-    const wxString& GetBuffer() const;
-};
+    static void SetVerbose(bool verbose = true);

 
 

+    //@}

 
 
 
 

-/**
-    @class wxLogInterposer
+    /**
+        Sets the specified formatter as the active one.

 
 

-    A special version of wxLogChain which uses itself as the new log target.
-    It forwards log messages to the previously installed one in addition to
-    processing them itself.
+        @param formatter
+            The new formatter. If @NULL, reset to the default formatter.

 
 

-    Unlike wxLogChain which is usually used directly as is, this class must be
-    derived from to implement wxLog::DoLog and/or wxLog::DoLogString methods.
+        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.
+
+        @since 2.9.4
+    */
+    wxLogFormatter *SetFormatter(wxLogFormatter* formatter);

 
 

-    wxLogInterposer destroys the previous log target in its destructor.
-    If you don't want this to happen, use wxLogInterposerTemp instead.

 
 

-    @library{wxbase}
-    @category{logging}
-*/
-class wxLogInterposer : public wxLogChain
-{
-public:

     /**
     /**

-        The default constructor installs this object as the current active log target.
+        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.

     */
     */

-    wxLogInterposer();
-};
+    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().

 
 

-/**
-    @class wxLogTextCtrl
+        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);

 
 

-    Using these target all the log messages can be redirected to a text control.
-    The text control must have been created with @c wxTE_MULTILINE style by the
-    caller previously.
+            // and also send it to the new one
+            if ( m_logNew && m_logNew != this )
+                m_logNew->LogRecord(level, msg, info);
+        }
+        @endcode

 
 

-    @library{wxcore}
-    @category{logging}
+        @since 2.9.1
+     */
+    void LogRecord(wxLogLevel level, const wxString& msg, const wxLogRecordInfo& info);

 
 

-    @see wxTextCtrl, wxStreamToTextRedirector
-*/
-class wxLogTextCtrl : public wxLog
-{
-public:
+protected:

     /**
     /**

-        Constructs a log target which sends all the log messages to the given text
-        control. The @a textctrl parameter cannot be @NULL.
+        @name Logging callbacks.
+
+        The functions which should be overridden by custom log targets.
+
+        When defining a new log target, you have a choice between overriding
+        DoLogRecord(), which provides maximal flexibility, DoLogTextAtLevel()
+        which can be used if you don't intend to change the default log
+        messages formatting but want to handle log messages of different levels
+        differently or, in the simplest case, DoLogText().
+     */
+    //@{
+
+    /**
+        Called to 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().

     */
     */

-    wxLogTextCtrl(wxTextCtrl* pTextCtrl);
-};
+    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);
+
+    //@}
+};

 
 
 
 /**
 
 
 
 /**

-    @class wxLogFormatter
+    @class wxLogChain

 
 

-    wxLogFormatter class is used to format the log messages. It implements the
-    default formatting and can be derived from to create custom formatters.
+    This simple class allows you to chain log sinks, that is to install a new sink but
+    keep passing log messages to the old one instead of replacing it completely as
+    wxLog::SetActiveTarget does.

 
 

-    The default implementation formats the message into a string containing
-    the time stamp, level-dependent prefix and the message itself.
+    It is especially useful when you want to divert the logs somewhere (for
+    example to a file or a log window) but also keep showing the error messages
+    using the standard dialogs as wxLogGui does by default.

 
 

-    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:
+    Example of usage:

 
     @code
 
     @code

-        wxLogMessage(_("*** Application started ***"));
-    @endcode
-
-    the log output could be something like:
+    wxLogChain *logChain = new wxLogChain(new wxLogStderr);

 
 

-    @verbatim
-        [7872] d:\testApp\src\testApp.cpp(85) : *** Application started ***
-    @endverbatim
+    // all the log messages are sent to stderr and also processed as usually
+    ...
+
+    // don't delete logChain directly as this would leave a dangling
+    // pointer as active log target, use SetActiveTarget() instead
+    delete wxLog::SetActiveTarget(...something else or NULL...);
+    @endcode

 
     @library{wxbase}
     @category{logging}
 
     @library{wxbase}
     @category{logging}

-
-    @see @ref overview_log
-
-    @since 2.9.4

 */
 */

-class wxLogFormatter
+class wxLogChain : public wxLog

 {
 public:
     /**
 {
 public:
     /**

-        The default ctor does nothing.
+        Sets the specified @c logger (which may be @NULL) as the default log
+        target but the log messages are also passed to the previous log target if any.

     */
     */

-    wxLogFormatter();
-
+    wxLogChain(wxLog* logger);

 
     /**
 
     /**

-        This function creates the full log message string.
-
-        Override it to customize the output string format.
-
-        @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.
+        Destroys the previous log target.
+    */
+    virtual ~wxLogChain();

 
 

-        @return
-            The formated message.
+    /**
+        Detaches the old log target so it won't be destroyed when the wxLogChain object
+        is destroyed.
+    */
+    void DetachOldLog();

 
 

-        @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().
+    /**
+        Returns the pointer to the previously active log target (which may be @NULL).

     */
     */

-    virtual wxString Format(wxLogLevel level,
-                            const wxString& msg,
-                            const wxLogRecordInfo& info) const;
+    wxLog* GetOldLog() const;

 
 

-protected:

     /**
     /**

-        This function formats the time stamp part of the log message.
+        Returns @true if the messages are passed to the previously active log
+        target (default) or @false if PassMessages() had been called.
+    */
+    bool IsPassingMessages() const;

 
 

-        Override this function if you need to customize just the time stamp.
+    /**
+        By default, the log messages are passed to the previously active log target.
+        Calling this function with @false parameter disables this behaviour
+        (presumably temporarily, as you shouldn't use wxLogChain at all otherwise) and
+        it can be reenabled by calling it again with @a passMessages set to @true.
+    */
+    void PassMessages(bool passMessages);

 
 

-        @param time
-            Time to format.
+    /**
+        Sets another log target to use (may be @NULL).

 
 

-        @return
-            The formated time string, may be empty.
+        The log target specified in the wxLogChain(wxLog*) constructor or in a
+        previous call to this function is deleted.
+        This doesn't change the old log target value (the one the messages are
+        forwarded to) which still remains the same as was active when wxLogChain
+        object was created.

     */
     */

-    virtual wxString FormatTime(time_t time) const;
+    void SetLog(wxLog* logger);

 };
 
 
 };
 
 

+

 /**
 /**

-    @class wxLog
+    @class wxLogInterposer

 
 

-    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.
+    A special version of wxLogChain which uses itself as the new log target.
+    It forwards log messages to the previously installed one in addition to
+    processing them itself.

 
 

-    Otherwise, it is completely hidden behind the @ref group_funcmacro_log "wxLogXXX() functions" 
-    and you may not even know about its existence.
+    Unlike wxLogChain which is usually used directly as is, this class must be
+    derived from to implement wxLog::DoLog and/or wxLog::DoLogString methods.

 
 

-    @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.
+    wxLogInterposer destroys the previous log target in its destructor.
+    If you don't want this to happen, use wxLogInterposerTemp instead.

 
     @library{wxbase}
     @category{logging}
 
     @library{wxbase}
     @category{logging}

-
-    @see @ref overview_log, @ref group_funcmacro_log "wxLogXXX() functions" 

 */
 */

-class wxLog
+class wxLogInterposer : public wxLogChain

 {
 public:
     /**
 {
 public:
     /**

-        @name Trace mask functions
+        The default constructor installs this object as the current active log target.

     */
     */

-    //@{
-    
-    /**
-        Add the @a mask to the list of allowed masks for wxLogTrace().
+    wxLogInterposer();
+};

 
 

-        @see RemoveTraceMask(), GetTraceMasks()
-    */
-    static void AddTraceMask(const wxString& mask);

 
 

-    /**
-        Removes all trace masks previously set with AddTraceMask().

 
 

-        @see RemoveTraceMask()
-    */
-    static void ClearTraceMasks();
+/**
+    @class wxLogInterposerTemp

 
 

-    /**
-        Returns the currently allowed list of string trace masks.
+    A special version of wxLogChain which uses itself as the new log target.
+    It forwards log messages to the previously installed one in addition to
+    processing them itself. Unlike wxLogInterposer, it doesn't delete the old
+    target which means it can be used to temporarily redirect log output.

 
 

-        @see AddTraceMask().
-    */
-    static const wxArrayString& GetTraceMasks();
+    As per wxLogInterposer, this class must be derived from to implement
+    wxLog::DoLog and/or wxLog::DoLogString methods.

 
 

+    @library{wxbase}
+    @category{logging}
+*/
+class wxLogInterposerTemp : public wxLogChain
+{
+public:

     /**
     /**

-        Returns @true if the @a mask is one of allowed masks for wxLogTrace().
-
-        See also: AddTraceMask(), RemoveTraceMask()
+        The default constructor installs this object as the current active log target.

     */
     */

-    static bool IsAllowedTraceMask(const wxString& mask);
+    wxLogInterposerTemp();
+};

 
 

-    /**
-        Remove the @a mask from the list of allowed masks for
-        wxLogTrace().

 
 

-        @see AddTraceMask()
-    */
-    static void RemoveTraceMask(const wxString& mask);
-    
-    //@}
+/**
+    @class wxLogStream

 
 

+    This class can be used to redirect the log messages to a C++ stream.

 
 

+    Please note that this class is only available if wxWidgets was compiled with
+    the standard iostream library support (@c wxUSE_STD_IOSTREAM must be on).

 
 

-    /**
-        @name Log target functions
-    */
-    //@{
-    
-    /**
-        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).
+    @library{wxbase}
+    @category{logging}

 
 

-        Note that this function also calls ClearTraceMasks().
+    @see wxLogStderr, wxStreamToTextRedirector
+*/
+class wxLogStream : public wxLog
+{
+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.

     */
     */

-    static void DontCreateOnDemand();
+    wxLogStream(std::ostream *ostr = NULL);
+};

 
 

-    /**
-        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();
+/**
+    @class wxLogStderr

 
 

-    /**
-        Sets the specified log target as the active one.
+    This class can be used to redirect the log messages to a C file stream (not to
+    be confused with C++ streams).

 
 

-        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.
+    It is the default log target for the non-GUI wxWidgets applications which
+    send all the output to @c stderr.

 
 

-        @see SetThreadActiveTarget()
-    */
-    static wxLog* SetActiveTarget(wxLog* logtarget);
+    @library{wxbase}
+    @category{logging}

 
 

+    @see wxLogStream
+*/
+class wxLogStderr : public wxLog
+{
+public:

     /**
     /**

-        Sets a thread-specific log target.
+        Constructs a log target which sends all the log messages to the given
+        @c FILE. If it is @NULL, the messages are sent to @c stderr.
+    */
+    wxLogStderr(FILE* fp = NULL);
+};

 
 

-        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.
+/**
+    @class wxLogBuffer

 
 

-        @param logger
-            The new thread-specific log target, possibly @NULL.
-        @return
-            The previous thread-specific log target, initially @NULL.
+    wxLogBuffer is a very simple implementation of log sink which simply collects
+    all the logged messages in a string (except the debug messages which are output
+    in the usual way immediately as we're presumably not interested in collecting
+    them for later). The messages from different log function calls are separated
+    by the new lines.

 
 

-        @since 2.9.1
-     */
-    static wxLog *SetThreadActiveTarget(wxLog *logger);
-    
-    /**
-        Flushes the current log target if any, does nothing if there is none.
+    All the messages collected so far can be shown to the user (and the current
+    buffer cleared) by calling the overloaded wxLogBuffer::Flush method.

 
 

-        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();
-    
+    @library{wxbase}
+    @category{logging}
+*/
+class wxLogBuffer : public wxLog
+{
+public:

     /**
     /**

-        Resumes logging previously suspended by a call to Suspend().
-        All messages logged in the meanwhile will be flushed soon.
+        The default ctor does nothing.

     */
     */

-    static void Resume();
+    wxLogBuffer();

 
     /**
 
     /**

-        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 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
+        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
+        clears the internal buffer.

     */
     */

-    static void Suspend();
-    
-    //@}
-    
-
+    virtual void Flush();

 
     /**
 
     /**

-        @name Log level functions
+        Returns the current buffer contains. Messages from different log function calls
+        are separated with the new lines in the buffer.
+        The buffer can be cleared by Flush() which will also show the current
+        contents to the user.

     */
     */

-    //@{
-    
-    /**
-        Returns the current log level limit.
-
-        All messages at levels strictly greater than the value returned by this
-        function are not logged at all.
+    const wxString& GetBuffer() const;
+};

 
 

-        @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()
+/**
+    @class wxLogNull

 
 

-        @since 2.9.1
-     */
-    static bool IsLevelEnabled(wxLogLevel level, wxString component);
+    This class allows you to temporarily suspend logging. All calls to the log
+    functions during the life time of an object of this class are just ignored.

 
 

-    /**
-        Sets the log level for the given component.
+    In particular, it can be used to suppress the log messages given by wxWidgets
+    itself but it should be noted that it is rarely the best way to cope with this
+    problem as @b all log messages are suppressed, even if they indicate a
+    completely different error than the one the programmer wanted to suppress.

 
 

-        For example, to disable all but error messages from wxWidgets network
-        classes you may use
-        @code
-            wxLog::SetComponentLevel("wx/net", wxLOG_Error);
-        @endcode
+    For instance, the example of the overview:

 
 

-        SetLogLevel() may be used to set the global log level.
+    @code
+      wxFile file;

 
 

-        @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.
+      // wxFile.Open() normally complains if file can't be opened, we don't want it
+      {
+        wxLogNull logNo;
+        if ( !file.Open("bar") )
+          ... process error ourselves ...
+      } // ~wxLogNull called, old log sink restored

 
 

-        @since 2.9.1
-     */
-    static void SetComponentLevel(const wxString& component, wxLogLevel level);
+      wxLogMessage("..."); // ok
+    @endcode

 
 

-    /**
-        Specifies that log messages with level greater (numerically) than
-        @a logLevel should be ignored and not sent to the active log target.
+    would be better written as:

 
 

-        @see SetComponentLevel()
-    */
-    static void SetLogLevel(wxLogLevel logLevel);
-    
-    //@}
+    @code
+      wxFile file;

 
 

+      // don't try to open file if it doesn't exist, we are prepared to deal with
+      // this ourselves - but all other errors are not expected
+      if ( wxFile::Exists("bar") )
+      {
+          // gives an error message if the file couldn't be opened
+          file.Open("bar");
+      }
+      else
+      {
+          ...
+      }
+    @endcode

 
 
 
 

+    @library{wxbase}
+    @category{logging}
+*/
+class wxLogNull
+{
+public:

     /**
     /**

-        @name Enable/disable features functions
+        Suspends logging.

     */
     */

-    //@{
-    
+    wxLogNull();
+

     /**
     /**

-        Globally enable or disable logging.
+        Resumes logging.
+    */
+    ~wxLogNull();
+};

 
 

-        Calling this function with @false argument disables all log messages
-        for the current thread.
+#endif // wxUSE_BASE

 
 

-        @see wxLogNull, IsEnabled()
+#if wxUSE_GUI

 
 

-        @return
-            The old state, i.e. @true if logging was previously enabled and
-            @false if it was disabled.
-     */
-    static bool EnableLogging(bool enable = true);
+/**
+    @class wxLogWindow

 
 

-    /**
-        Returns true if logging is enabled at all now.
+    This class represents a background log window: to be precise, it collects all
+    log messages in the log frame which it manages but also passes them on to the
+    log target which was active at the moment of its creation. This allows you, for
+    example, to show all the log messages in a frame but still continue to process
+    them normally by showing the standard log dialog.

 
 

-        @see IsLevelEnabled(), EnableLogging()
-     */
-    static bool IsEnabled();
-    
-    /**
-        Returns whether the repetition counting mode is enabled.
-    */
-    static bool GetRepetitionCounting();
+    @library{wxcore}
+    @category{logging}

 
 

+    @see wxLogTextCtrl
+*/
+class wxLogWindow : public wxLogInterposer
+{
+public:

     /**
     /**

-        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.
+        Creates the log frame window and starts collecting the messages in it.

 
 

-        Notice that the current time stamp is only used by the default log
-        formatter and custom formatters may ignore this format.
+        @param pParent
+            The parent window for the log frame, may be @NULL
+        @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.
+            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.

     */
     */

-    static const wxString& GetTimestamp();
+    wxLogWindow(wxWindow* pParent, const wxString& szTitle, bool show = true,
+                bool passToOld = true);

 
     /**
 
     /**

-        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 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.
+        Returns the associated log frame window. This may be used to position or resize
+        it but use Show() to show or hide it.

     */
     */

-    static void SetTimestamp(const wxString& format);
+    wxFrame* GetFrame() const;

 
     /**
 
     /**

-        Disables time stamping of the log messages.
+        Called if the user closes the window interactively, will not be
+        called if it is destroyed for another reason (such as when program
+        exits).

 
 

-        Notice that the current time stamp is only used by the default log
-        formatter and custom formatters may ignore calls to this function.
+        Return @true from here to allow the frame to close, @false to
+        prevent this from happening.

 
 

-        @since 2.9.0
+        @see OnFrameDelete()

     */
     */

-    static void DisableTimestamp();
-    
+    virtual bool OnFrameClose(wxFrame* frame);
+

     /**
     /**

-        Returns whether the verbose mode is currently active.
+        Called immediately after the log frame creation allowing for
+        any extra initializations.

     */
     */

-    static bool GetVerbose();
+    virtual void OnFrameCreate(wxFrame* frame);

 
     /**
 
     /**

-        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
+        Called right before the log frame is going to be deleted: will
+        always be called unlike OnFrameClose().

     */
     */

-    static void SetVerbose(bool verbose = true);
-    
-    //@}
-    
+    virtual void OnFrameDelete(wxFrame* frame);

 
     /**
 
     /**

-        Sets the specified formatter as the active one.
+        Shows or hides the frame.
+    */
+    void Show(bool show = true);
+};
+
+
+
+/**
+    @class wxLogGui
+
+    This is the default log target for the GUI wxWidgets applications.
+
+    Please see @ref overview_log_customize for explanation of how to change the
+    default log target.
+
+    An object of this class is used by default to show the log messages created
+    by using wxLogMessage(), wxLogError() and other logging functions. It
+    doesn't display the messages logged by them immediately however but
+    accumulates all messages logged during an event handler execution and then
+    shows them all at once when its Flush() method is called during the idle
+    time processing. This has the important advantage of showing only a single
+    dialog to the user even if several messages were logged because of a single
+    error as it often happens (e.g. a low level function could log a message
+    because it failed to open a file resulting in its caller logging another
+    message due to the failure of higher level operation requiring the use of
+    this file). If you need to force the display of all previously logged
+    messages immediately you can use wxLog::FlushActive() to force the dialog
+    display.
+
+    Also notice that if an error message is logged when several informative
+    messages had been already logged before, the informative messages are
+    discarded on the assumption that they are not useful -- and may be
+    confusing and hence harmful -- any more after the error. The warning
+    and error messages are never discarded however and any informational
+    messages logged after the first error one are also kept (as they may
+    contain information about the error recovery). You may override DoLog()
+    method to change this behaviour.

 
 

-        @param formatter
-            The new formatter. If @NULL, reset to the default formatter.
+    At any rate, it is possible that that several messages were accumulated
+    before this class Flush() method is called. If this is the case, Flush()
+    uses a custom dialog which shows the last message directly and allows the
+    user to view the previously logged ones by expanding the "Details"
+    wxCollapsiblePane inside it. This custom dialog also provides the buttons
+    for copying the log messages to the clipboard and saving them to a file.

 
 

-        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.
+    However if only a single message is present when Flush() is called, just a
+    wxMessageBox() is used to show it. This has the advantage of being closer
+    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 DoShowSingleLogMessage() to
+    customize wxLogGui -- the dialogs sample shows how to do this.

 
 

-        @since 2.9.4
+    @library{wxcore}
+    @category{logging}
+*/
+class wxLogGui : public wxLog
+{
+public:
+    /**
+        Default constructor.

     */
     */

-    wxLogFormatter *SetFormatter(wxLogFormatter* formatter);
-    
+    wxLogGui();

 
     /**
 
     /**

-        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.
+        Presents the accumulated log messages, if any, to the user.

 
 

-        If you override this method in a derived class, call the base class
-        version first, before doing anything else.
-    */
+        This method is called during the idle time and should show any messages
+        accumulated in wxLogGui#m_aMessages field to the user.
+     */

     virtual void Flush();
     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().
+protected:
+    /**
+        Returns the appropriate title for the dialog.

 
 

-        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);
+        The title is constructed from wxApp::GetAppDisplayName() and the
+        severity string (e.g. "error" or "warning") appropriate for the current
+        wxLogGui#m_bErrors and wxLogGui#m_bWarnings values.
+     */
+    wxString GetTitle() const;

 
 

-            // and also send it to the new one
-            if ( m_logNew && m_logNew != this )
-                m_logNew->LogRecord(level, msg, info);
-        }
-        @endcode
+    /**
+        Returns wxICON_ERROR, wxICON_WARNING or wxICON_INFORMATION depending on
+        the current maximal severity.

 
 

-        @since 2.9.1
+        This value is suitable to be used in the style parameter of
+        wxMessageBox() function.

      */
      */

-    void LogRecord(wxLogLevel level, const wxString& msg, const wxLogRecordInfo& info);
+    int GetSeverityIcon() const;

 
 

-protected:

     /**
     /**

-        @name Logging callbacks.
-
-        The functions which should be overridden by custom log targets.
+        Forgets all the currently stored messages.

 
 

-        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().
+        If you override Flush() (and don't call the base class version), you
+        must call this method to avoid messages being logged over and over
+        again.

      */
      */

-    //@{
+    void Clear();
+

 
     /**
 
     /**

-        Called to log a new record.
+        All currently accumulated messages.

 
 

-        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().
+        This array may be empty if no messages were logged.

 
 

-        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).
+        @see m_aSeverity, m_aTimes

      */
      */

-    virtual void DoLogRecord(wxLogLevel level,
-                             const wxString& msg,
-                             const wxLogRecordInfo& info);
+    wxArrayString m_aMessages;

 
     /**
 
     /**

-        Called to log the specified string at given level.
+        The severities of each logged message.

 
 

-        The base class versions logs debug and trace messages on the system
-        default debug output channel and passes all the other messages to
-        DoLogText().
-    */
-    virtual void DoLogTextAtLevel(wxLogLevel level, const wxString& msg);
+        This array is synchronized with wxLogGui#m_aMessages, i.e. the n-th
+        element of this array corresponds to the severity of the n-th message.
+        The possible severity values are @c wxLOG_XXX constants, e.g.
+        wxLOG_Error, wxLOG_Warning, wxLOG_Message etc.
+     */
+    wxArrayInt m_aSeverity;

 
     /**
 
     /**

-        Called to log the specified string.
+        The time stamps of each logged message.

 
 

-        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 elements of this array are time_t values corresponding to the time
+        when the message was logged.
+     */
+    wxArrayLong m_aTimes;

 
 

-        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);
+    /**
+        True if there any error messages.
+     */
+    bool m_bErrors;

 
 

-    //@}
-};
+    /**
+        True if there any warning messages.

 
 

+        If both wxLogGui#m_bErrors and this member are false, there are only
+        informational messages to be shown.
+     */
+    bool m_bWarnings;

 
 

+    /**
+        True if there any messages to be shown to the user.

 
 

-/**
-    @class wxLogNull
+        This variable is used instead of simply checking whether
+        wxLogGui#m_aMessages array is empty to allow blocking further calls to
+        Flush() while a log dialog is already being shown, even if the messages
+        array hasn't been emptied yet.
+     */
+    bool m_bHasMessages;

 
 

-    This class allows you to temporarily suspend logging. All calls to the log
-    functions during the life time of an object of this class are just ignored.
+private:
+    /**
+        Method called by Flush() to show a single log message.

 
 

-    In particular, it can be used to suppress the log messages given by wxWidgets
-    itself but it should be noted that it is rarely the best way to cope with this
-    problem as @b all log messages are suppressed, even if they indicate a
-    completely different error than the one the programmer wanted to suppress.
+        This function can be overridden to show the message in a different way.
+        By default a simple wxMessageBox() call is used.

 
 

-    For instance, the example of the overview:
+        @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);

 
 

-    @code
-      wxFile file;
+    /**
+        Method called by Flush() to show multiple log messages.

 
 

-      // wxFile.Open() normally complains if file can't be opened, we don't want it
-      {
-        wxLogNull logNo;
-        if ( !file.Open("bar") )
-          ... process error ourselves ...
-      } // ~wxLogNull called, old log sink restored
+        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.

 
 

-      wxLogMessage("..."); // ok
-    @endcode
+        @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);
+};

 
 

-    would be better written as:

 
 

-    @code
-      wxFile file;

 
 

-      // don't try to open file if it doesn't exist, we are prepared to deal with
-      // this ourselves - but all other errors are not expected
-      if ( wxFile::Exists("bar") )
-      {
-          // gives an error message if the file couldn't be opened
-          file.Open("bar");
-      }
-      else
-      {
-          ...
-      }
-    @endcode
+/**
+    @class wxLogTextCtrl

 
 

+    Using these target all the log messages can be redirected to a text control.
+    The text control must have been created with @c wxTE_MULTILINE style by the
+    caller previously.

 
 

-    @library{wxbase}
+    @library{wxcore}

     @category{logging}
     @category{logging}

+
+    @see wxTextCtrl, wxStreamToTextRedirector

 */
 */

-class wxLogNull
+class wxLogTextCtrl : public wxLog

 {
 public:
     /**
 {
 public:
     /**

-        Suspends logging.
-    */
-    wxLogNull();
-
-    /**
-        Resumes logging.
+        Constructs a log target which sends all the log messages to the given text
+        control. The @a textctrl parameter cannot be @NULL.

     */
     */

-    ~wxLogNull();
+    wxLogTextCtrl(wxTextCtrl* pTextCtrl);

 };
 
 
 };
 
 

+#endif // wxUSE_GUI
+
+#if wxUSE_BASE
+

 
 // ============================================================================
 // Global functions/macros
 
 // ============================================================================
 // Global functions/macros


@@ -1447,3 +1452,4 @@ void wxVLogSysError(const char* formatString, va_list argPtr);
 
 //@}
 
 
 //@}
 

+#endif // wxUSE_BASE