]> git.saurik.com Git - wxWidgets.git/blobdiff - interface/wx/log.h
Implement wxSTAY_ON_TOP for wxMessageDialog in wxGTK.
[wxWidgets.git] / interface / wx / log.h
index 34cbf28abbf681f38222b22859790cc058d2b4de..64a5c08de1e10ec68cf4a5166e4bebffb2fc3df0 100644 (file)
@@ -9,8 +9,7 @@
 
 /**
     Different standard log levels (you may also define your own) used with
-    wxLog::OnLog() by standard wxLog functions wxLogError(), wxLogWarning(),
-    etc...
+    by standard wxLog functions wxLogError(), wxLogWarning(), etc...
 */
 enum wxLogLevelValues
 {
@@ -27,11 +26,6 @@ enum wxLogLevelValues
     wxLOG_Max = 10000
 };
 
-/**
-    The type used for trace masks.
-*/
-typedef unsigned long wxTraceMask;
-
 /**
     The type used to specify a log level.
 
@@ -40,6 +34,39 @@ typedef unsigned long wxTraceMask;
 */
 typedef unsigned long wxLogLevel;
 
+/**
+    Information about a log record (unit of the log output).
+ */
+class wxLogRecordInfo
+{
+public:
+    /// The name of the file where this log message was generated.
+    const char *filename;
+
+    /// The line number at which this log message was generated.
+    int line;
+
+    /**
+        The name of the function where the log record was generated.
+
+        This field may be @NULL if the compiler doesn't support @c __FUNCTION__
+        (but most modern compilers do).
+     */
+    const char *func;
+
+    /// Time when the log message was generated.
+    time_t timestamp;
+
+    /**
+        Id of the thread in which the message was generated.
+
+        This field is only available if wxWidgets was built with threads
+        support (<code>wxUSE_THREADS == 1</code>).
+
+        @see wxThread::GetCurrentId()
+     */
+    wxThreadIdType threadId;
+};
 
 /**
     @class wxLogWindow
@@ -575,19 +602,23 @@ public:
 
     @section log_derivingyours Deriving your own log target
 
-    There are two functions which must be implemented by any derived class to
-    actually process the log messages: DoLog() and DoLogString().
-    The second function receives a string which just has to be output in some way
-    and the easiest way to write a new log target is to override just this function
-    in the derived class.
+    There are several methods which may be overridden in the derived class to
+    customize log messages handling: DoLogRecord(), DoLogTextAtLevel() and
+    DoLogText().
 
-    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).
+    The last method is the simplest one: you should override it if you simply
+    want to redirect the log output elsewhere, without taking into account the
+    level of the message. If you do want to handle messages of different levels
+    differently, then you should override DoLogTextAtLevel().
+
+    Finally, if more control over the output format is needed, then the first
+    function must be overridden as it allows to construct custom messages
+    depending on the log level or even do completely different things depending
+    on the message severity (for example, throw away all messages except
+    warnings and errors, show warnings on the screen and forward the error
+    messages to the user's (or programmer's) cell phone -- maybe depending on
+    whether the timestamp tells us if it is day or night in the current time
+    zone).
 
     There also functions to support message buffering. Why are they needed?
     Some of wxLog implementations, most notably the standard wxLogGui class,
@@ -597,9 +628,7 @@ public:
     Flush() shows them all and clears the buffer contents.
     This function doesn't do anything if the buffer is already empty.
 
-    See also:
-    @li Flush()
-    @li FlushActive()
+    @see FlushActive()
 
 
     @section log_tracemasks Using trace masks
@@ -613,24 +642,11 @@ public:
     but may be activated, for example, in order to help the user find some program
     problem.
 
-    As for the (real) trace messages, their handling depends on the settings of
-    the (application global) @e trace mask which can either be specified using
-    SetTraceMask(), GetTraceMask() and wxLogTrace() which takes an integer mask
-    or using AddTraceMask() for string trace masks.
+    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.
 
-    The difference between bit-wise and string trace masks is that a message using
-    integer trace mask will only be logged if all bits of the mask are set in the
-    current mask while a message using string mask will be logged simply if the
-    mask had been added before to the list of allowed ones.
     For example,
-
-    @code
-    wxLogTrace( wxTraceRefCount|wxTraceOleCalls, "Active object ref count: %d", nRef );
-    @endcode
-
-    will do something only if the current trace mask contains both @c wxTraceRefCount
-    and @c wxTraceOle, but:
-
     @code
     wxLogTrace( wxTRACE_OleCalls, "IFoo::Bar() called" );
     @endcode
@@ -641,11 +657,6 @@ public:
     wxLog::AddTraceMask( wxTRACE_OleCalls);
     @endcode
 
-    Using string masks is simpler and allows you to easily add custom ones, so this
-    is the preferred way of working with trace messages. The integer trace mask is
-    kept for compatibility and for additional (but very rarely needed) flexibility
-    only.
-
     The standard trace masks are given in wxLogTrace() documentation.
 
     Finally, the @e wxLog::DoLog() function automatically prepends a time stamp
@@ -683,8 +694,7 @@ public:
     @section log_target Manipulating the log target
 
     The functions in this section work with and manipulate the active log
-    target. The OnLog() is called by the @e wxLogXXX() functions
-    and invokes the DoLog() of the active log target if any.
+    target.
 
     Get/Set methods are used to install/query the current active target and,
     finally, DontCreateOnDemand() disables the automatic creation of a standard
@@ -693,7 +703,6 @@ public:
     easily lead to a loss of messages.
 
     See also:
-    @li OnLog()
     @li GetActiveTarget()
     @li SetActiveTarget()
     @li DontCreateOnDemand()
@@ -732,26 +741,65 @@ public:
     */
     static void DontCreateOnDemand();
 
+    /**
+        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);
+
     /**
         Shows all the messages currently in buffer and clears it.
+
         If the buffer is already empty, nothing happens.
+
+        If you override this method in a derived class, call the base class
+        version first, before doing anything else.
     */
     virtual void Flush();
 
     /**
         Flushes the current log target if any, does nothing if there is none.
 
-        @see Flush()
+        When this method is called from the main thread context, it also
+        flushes any previously buffered messages logged by the other threads.
+        When it is called from the other threads it simply calls Flush() on the
+        currently active log target, so it mostly makes sense to do this if a
+        thread has its own logger set with SetThreadActiveTarget().
     */
     static void FlushActive();
 
     /**
         Returns the pointer to the active log target (may be @NULL).
+
+        Notice that if SetActiveTarget() hadn't been previously explicitly
+        called, this function will by default try to create a log target by
+        calling wxAppTraits::CreateLogTarget() which may be overridden in a
+        user-defined traits class to change the default behaviour. You may also
+        call DontCreateOnDemand() to disable this behaviour.
+
+        When this function is called from threads other than main one,
+        auto-creation doesn't happen. But if the thread has a thread-specific
+        log target previously set by SetThreadActiveTarget(), it is returned
+        instead of the global one. Otherwise, the global log target is
+        returned.
     */
     static wxLog* GetActiveTarget();
 
     /**
         Returns the current log level limit.
+
+        All messages at levels strictly greater than the value returned by this
+        function are not logged at all.
+
+        @see SetLogLevel(), IsLevelEnabled()
     */
     static wxLogLevel GetLogLevel();
 
@@ -766,6 +814,7 @@ public:
     static const wxString& GetTimestamp();
 
     /**
+        @deprecated
         Returns the current trace mask, see Customization() section for details.
     */
     static wxTraceMask GetTraceMask();
@@ -790,10 +839,24 @@ public:
     static bool IsAllowedTraceMask(const wxString& mask);
 
     /**
-        Forwards the message at specified level to the @e DoLog() function of the
-        active log target if there is any, does nothing otherwise.
-    */
-    static void OnLog(wxLogLevel level, const wxString& msg, time_t t);
+        Returns true if logging is enabled at all now.
+
+        @see IsLevelEnabled(), EnableLogging()
+     */
+    static bool IsEnabled();
+
+    /**
+        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);
 
     /**
         Remove the @a mask from the list of allowed masks for
@@ -816,12 +879,38 @@ public:
         To suppress logging use a new instance of wxLogNull not @NULL.  If the
         active log target is set to @NULL a new default log target will be
         created when logging occurs.
+
+        @see SetThreadActiveTarget()
     */
     static wxLog* SetActiveTarget(wxLog* logtarget);
 
+    /**
+        Sets the log level for the given component.
+
+        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);
 
@@ -832,6 +921,32 @@ public:
     */
     static void SetRepetitionCounting(bool repetCounting = true);
 
+    /**
+        Sets a thread-specific log target.
+
+        The log target passed to this function will be used for all messages
+        logged by the current thread using the usual wxLog functions. This
+        shouldn't be called from the main thread which never uses a thread-
+        specific log target but can be used for the other threads to handle
+        thread logging completely separately; instead of buffering thread log
+        messages in the main thread logger.
+
+        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);
+
     /**
         Sets the timestamp format prepended by the default log targets to all
         messages. The string may contain any normal characters as well as %
@@ -848,7 +963,8 @@ public:
     static void DisableTimestamp();
 
     /**
-        Sets the trace mask, see @ref log_derivingyours section for details.
+        @deprecated
+        Sets the trace mask, see @ref log_tracemasks section for details.
     */
     static void SetTraceMask(wxTraceMask mask);
 
@@ -875,54 +991,88 @@ public:
     static void Suspend();
 
     /**
-        Log the given message.
+        Log the given record.
 
         This function should only be called from the DoLog() implementations in
-        the derived classes (which can't call wxLog::DoLog() directly as it is
-        protected), 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().
+        the derived classes if they need to call DoLogRecord() on another log
+        object (they can, of course, just use wxLog::DoLogRecord() call syntax
+        to call it on the object itself). It should not be used for logging new
+        messages which can be only sent to the currently active logger using
+        OnLog() which also checks if the logging (for this level) is enabled
+        while this method just directly calls DoLog().
 
         Example of use of this class from wxLogChain:
         @code
-        void wxLogChain::DoLog(wxLogLevel level, const wxString& msg, time_t t)
+        void wxLogChain::DoLogRecord(wxLogLevel level,
+                                     const wxString& msg,
+                                     const wxLogRecordInfo& info)
         {
             // let the previous logger show it
             if ( m_logOld && IsPassingMessages() )
-                m_logOld->Log(level, msg, t);
+                m_logOld->LogRecord(level, msg, info);
 
             // and also send it to the new one
             if ( m_logNew && m_logNew != this )
-                m_logNew->Log(level, msg, t);
+                m_logNew->LogRecord(level, msg, info);
         }
         @endcode
 
-        @since 2.9.0
+        @since 2.9.1
      */
-    void Log(wxLogLevel level, const wxString& msg, time_t timestamp);
+    void LogRecord(wxLogLevel level, const wxString& msg, time_t timestamp);
 
 protected:
+    /**
+        @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 process the message of the specified severity. @a msg is the text
-        of the message as specified in the call of @e wxLogXXX() function which
-        generated it and @a timestamp is the moment when the message was generated.
+        Called to created log a new record.
+
+        Any log message created by wxLogXXX() functions is passed to this
+        method of the active log target. The default implementation prepends
+        the timestamp and, for some log levels (e.g. error and warning), the
+        corresponding prefix to @a msg and passes it to DoLogTextAtLevel().
+
+        You may override this method to implement custom formatting of the
+        log messages or to implement custom filtering of log messages (e.g. you
+        could discard all log messages coming from the given source file).
+     */
+    virtual void DoLogRecord(wxLogLevel level,
+                             const wxString& msg,
+                             const wxLogRecordInfo& info);
 
-        The base class version prepends the timestamp to the message, adds a prefix
-        corresponding to the log level and then calls
-        DoLogString() with the resulting string.
+    /**
+        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().
     */
-    virtual void DoLog(wxLogLevel level, const wxString& msg, time_t timestamp);
+    virtual void DoLogTextAtLevel(wxLogLevel level, const wxString& msg);
 
     /**
-        Called to log the specified string. The timestamp is already included in the
-        string but still passed to this function.
+        Called to log the specified string.
 
-        A simple implementation may just send the string to @c stdout or, better,
-        @c stderr.
+        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 DoLogString(const wxString& msg, time_t timestamp);
+    virtual void DoLogText(const wxString& msg);
+
+    //@}
 };
 
 
@@ -975,7 +1125,7 @@ protected:
     @library{wxbase}
     @category{logging}
 */
-class wxLogNull : public wxLog
+class wxLogNull
 {
 public:
     /**
@@ -1112,15 +1262,15 @@ void wxVLogError(const char* formatString, va_list argPtr);
     function is that usually there are a lot of trace messages, so it might
     make sense to separate them from other debug messages.
 
-    wxLogDebug(const char*,const char*,...) and
-    wxLogDebug(wxTraceMask,const char*,...) can be used instead if you would
-    like to be able to separate trace messages into different categories which
-    can be enabled or disabled with the static functions provided in wxLog.
+    wxLogTrace(const char*,const char*,...) and can be used instead of
+    wxLogDebug() if you would like to be able to separate trace messages into
+    different categories which can be enabled or disabled with
+    wxLog::AddTraceMask() and wxLog::RemoveTraceMask().
 
     @header{wx/log.h}
 */
-void wxLogTrace(const char* formatString, ... );
-void wxVLogTrace(const char* formatString, va_list argPtr);
+void wxLogTrace(const char *mask, const char* formatString, ... );
+void wxVLogTrace(const char *mask, const char* formatString, va_list argPtr);
 //@}
 
 /** @addtogroup group_funcmacro_log */
@@ -1178,7 +1328,7 @@ void wxVLogTrace(const char* mask,
     This version of wxLogTrace() only logs the message if all the bits
     corresponding to the @a mask are set in the wxLog trace mask which can be
     set by calling wxLog::SetTraceMask(). This version is less flexible than
-    wxLogDebug(const char*,const char*,...) because it doesn't allow defining
+    wxLogTrace(const char*,const char*,...) because it doesn't allow defining
     the user trace masks easily. This is why it is deprecated in favour of
     using string trace masks.