added wxLog::IsLevelEnabled() helper; document it and a few related functions which were not, or poorly, documented

git-svn-id: https://svn.wxwidgets.org/svn/wx/wxWidgets/trunk@61348 c3d73ce0-8a6f-49c7-b76d-6d57e0e08775

include/wx/log.h

@@ -164,9 +164,13 @@ public:
 
     // these functions allow to completely disable all log messages
 
-    // is logging disabled now?
+    // is logging enabled at all now?
     static bool IsEnabled() { return ms_doLog; }
 
+    // is logging at this level enabled?
+    static bool IsLevelEnabled(wxLogLevel level)
+        { return IsEnabled() && level <= ms_logLevel; }
+
     // change the flag state, return the previous one
     static bool EnableLogging(bool doIt = true)
         { bool doLogOld = ms_doLog; ms_doLog = doIt; return doLogOld; }

interface/wx/log.h

@@ -724,6 +724,19 @@ public:
     */
     static void DontCreateOnDemand();
 
+    /**
+        Globally enable or disable logging.
+
+        Calling this function with @false argument disables all log messages.
+
+        @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.
@@ -744,6 +757,11 @@ public:
 
     /**
         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();
 
@@ -782,6 +800,23 @@ public:
     */
     static bool IsAllowedTraceMask(const wxString& mask);
 
+    /**
+        Returns true if logging is enabled at all now.
+
+        @see IsLevelEnabled(), EnableLogging()
+     */
+    static bool IsEnabled();
+
+    /**
+        Returns true if logging at this level is enabled.
+
+        This function only returns @true if logging is globally enabled and if
+        this level is less than or equal to the global log level value.
+
+        @see IsEnabled(), SetLogLevel(), GetLogLevel()
+     */
+    static bool IsLevelEnabled(wxLogLevel level);
+
     /**
         Remove the @a mask from the list of allowed masks for
         wxLogTrace().