Fix typo in wxOwnerDrawnComboBox ctor documentation.

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

diff --git a/interface/wx/log.h b/interface/wx/log.h
index 09bdc618e54bff6801ea89fa1ccc90dec547606a..1bf3a66d37741e817e5172ad35c56949541fd19c 100644 (file)
--- a/interface/wx/log.h
+++ b/interface/wx/log.h
@@ -291,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
     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}
 
     @library{wxcore}
     @category{logging}


@@ -342,51 +342,6 @@ protected:
     void Clear();
 
 
     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.
 
     /**
         All currently accumulated messages.
 


@@ -436,6 +391,51 @@ protected:
         array hasn't been emptied yet.
      */
     bool m_bHasMessages;
         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);

 };
 
 
 };
 
 


@@ -583,6 +583,102 @@ public:
 
 
 
 
 
 

+
+/**
+    @class wxLogFormatter
+
+    wxLogFormatter class is used to format the log messages. It implements the
+    default formatting and can be derived from to create custom formatters.
+
+    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}
+
+    @see @ref overview_log
+
+    @since 2.9.4
+*/
+class wxLogFormatter
+{
+public:
+    /**
+        The default ctor does nothing.
+    */
+    wxLogFormatter();
+
+
+    /**
+        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.
+
+        @return
+            The formated message.
+
+        @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.
+
+        Override this function if you need to customize just the time stamp.
+
+        @param time
+            Time to format.
+
+        @return
+            The formated time string, may be empty.
+    */
+    virtual wxString FormatTime(time_t time) const;
+};
+
+

 /**
     @class wxLog
 
 /**
     @class wxLog
 


@@ -599,7 +695,7 @@ public:
     @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.
 
     @note For console-mode applications, the default target is wxLogStderr, so
           that all @e wxLogXXX() functions print on @c stderr when @c wxUSE_GUI = 0.
 

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

     @category{logging}
 
     @see @ref overview_log, @ref group_funcmacro_log "wxLogXXX() functions" 
     @category{logging}
 
     @see @ref overview_log, @ref group_funcmacro_log "wxLogXXX() functions" 


@@ -863,6 +959,9 @@ public:
     
     /**
         Returns the current timestamp format string.
     
     /**
         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();
 
     */
     static const wxString& GetTimestamp();
 


@@ -871,12 +970,20 @@ public:
         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.
         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.

     */
     static void SetTimestamp(const wxString& format);
 
     /**
         Disables time stamping of the log messages.
 
     */
     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();
         @since 2.9.0
     */
     static void DisableTimestamp();


@@ -899,6 +1006,19 @@ public:
     
     //@}
     
     
     //@}
     

+
+    /**
+        Sets the specified formatter as the active one.
+
+        @param formatter
+            The new formatter. If @NULL, reset to the default formatter.
+
+        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);

     
 
     /**
     
 
     /**


@@ -1293,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
 /**
     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.
     depending on the platform) and the corresponding error message. The second
     form of this function takes the error code explicitly as the first
     argument.