+ 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
+
+ wxLog class defines the interface for the <em>log targets</em> used by wxWidgets
+ logging functions as explained in the @ref overview_log.
+
+ The only situations when you need to directly use this class is when you want
+ to derive your own log target because the existing ones don't satisfy your
+ needs.
+
+ Otherwise, it is completely hidden behind the @ref group_funcmacro_log "wxLogXXX() functions"
+ and you may not even know about its existence.
+
+ @note For console-mode applications, the default target is wxLogStderr, so
+ that all @e wxLogXXX() functions print on @c stderr when @c wxUSE_GUI = 0.
+
+ @library{wxbase}
+ @category{logging}
+
+ @see @ref overview_log, @ref group_funcmacro_log "wxLogXXX() functions"
+*/
+class wxLog
+{
+public:
+ /**
+ @name Trace mask functions
+ */
+ //@{
+
+ /**
+ Add the @a mask to the list of allowed masks for wxLogTrace().
+
+ @see RemoveTraceMask(), GetTraceMasks()
+ */
+ static void AddTraceMask(const wxString& mask);
+
+ /**
+ Removes all trace masks previously set with AddTraceMask().
+
+ @see RemoveTraceMask()
+ */
+ static void ClearTraceMasks();
+
+ /**
+ Returns the currently allowed list of string trace masks.
+
+ @see AddTraceMask().
+ */
+ static const wxArrayString& GetTraceMasks();
+
+ /**
+ Returns @true if the @a mask is one of allowed masks for wxLogTrace().
+
+ See also: AddTraceMask(), RemoveTraceMask()
+ */
+ static bool IsAllowedTraceMask(const wxString& mask);
+
+ /**
+ Remove the @a mask from the list of allowed masks for
+ wxLogTrace().
+
+ @see AddTraceMask()
+ */
+ static void RemoveTraceMask(const wxString& mask);
+
+ //@}
+
+
+
+ /**
+ @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).
+
+ Note that this function also calls ClearTraceMasks().
+ */
+ static void DontCreateOnDemand();
+
+ /**
+ 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();
+
+ /**
+ Sets the specified log target as the active one.
+
+ Returns the pointer to the previous active log target (may be @NULL).
+ To suppress logging use a new instance of wxLogNull not @NULL. If the
+ active log target is set to @NULL a new default log target will be
+ created when logging occurs.
+
+ @see SetThreadActiveTarget()
+ */
+ static wxLog* SetActiveTarget(wxLog* logtarget);
+
+ /**
+ 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);
+
+ /**
+ Flushes the current log target if any, does nothing if there is none.
+
+ 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();
+
+ /**
+ 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
+ */
+ static void Suspend();
+
+ //@}
+
+
+
+ /**
+ @name Log level functions
+ */
+ //@{
+
+ /**
+ Returns the current log level limit.
+
+ All messages at levels strictly greater than the value returned by this
+ function are not logged at all.
+
+ @see SetLogLevel(), IsLevelEnabled()
+ */
+ static wxLogLevel GetLogLevel();
+
+ /**
+ Returns true if logging at this level is enabled for the current thread.
+
+ This function only returns @true if logging is globally enabled and if
+ @a level is less than or equal to the maximal log level enabled for the
+ given @a component.
+
+ @see IsEnabled(), SetLogLevel(), GetLogLevel(), SetComponentLevel()
+
+ @since 2.9.1
+ */
+ static bool IsLevelEnabled(wxLogLevel level, wxString component);
+
+ /**
+ Sets the log level for the given component.
+
+ For example, to disable all but error messages from wxWidgets network
+ classes you may use
+ @code
+ wxLog::SetComponentLevel("wx/net", wxLOG_Error);
+ @endcode
+
+ SetLogLevel() may be used to set the global log level.
+
+ @param component
+ Non-empty component name, possibly using slashes (@c /) to separate
+ it into several parts.
+ @param level
+ Maximal level of log messages from this component which will be
+ handled instead of being simply discarded.
+
+ @since 2.9.1
+ */
+ static void SetComponentLevel(const wxString& component, wxLogLevel level);
+
+ /**
+ Specifies that log messages with level greater (numerically) than
+ @a logLevel should be ignored and not sent to the active log target.
+
+ @see SetComponentLevel()
+ */
+ static void SetLogLevel(wxLogLevel logLevel);
+
+ //@}
+
+
+
+ /**
+ @name Enable/disable features functions
+ */
+ //@{
+
+ /**
+ Globally enable or disable logging.
+
+ Calling this function with @false argument disables all log messages
+ for the current thread.
+
+ @see wxLogNull, IsEnabled()
+
+ @return
+ The old state, i.e. @true if logging was previously enabled and
+ @false if it was disabled.
+ */
+ static bool EnableLogging(bool enable = true);
+
+ /**
+ Returns true if logging is enabled at all now.
+
+ @see IsLevelEnabled(), EnableLogging()
+ */
+ static bool IsEnabled();
+
+ /**
+ Returns whether the repetition counting mode is enabled.
+ */
+ static bool GetRepetitionCounting();
+
+ /**
+ Enables logging mode in which a log message is logged once, and in case exactly
+ 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.
+
+ Notice that the current time stamp is only used by the default log
+ formatter and custom formatters may ignore this format.
+ */
+ static const wxString& GetTimestamp();
+
+ /**
+ Sets the timestamp format prepended by the default log targets to all
+ messages. The string may contain any normal characters as well as %
+ prefixed format specifiers, see @e strftime() manual for details.
+ Passing an empty string to this function disables message time stamping.
+
+ Notice that the current time stamp is only used by the default log
+ formatter and custom formatters may ignore this format. You can also
+ define a custom wxLogFormatter to customize the time stamp handling
+ beyond changing its format.
+ */
+ static void SetTimestamp(const wxString& format);
+
+ /**
+ Disables time stamping of the log messages.
+
+ Notice that the current time stamp is only used by the default log
+ formatter and custom formatters may ignore calls to this function.
+
+ @since 2.9.0
+ */
+ static void DisableTimestamp();
projects / wxWidgets.git / blobdiff