X-Git-Url: https://git.saurik.com/wxWidgets.git/blobdiff_plain/e4431849b4f2097edf0e01c5d50bf0ed947befa9..36a0190ebd5bd9a7302f60f6dcd608b80574e21c:/interface/wx/log.h?ds=inline diff --git a/interface/wx/log.h b/interface/wx/log.h index 434ef3547a..7dbed9bc56 100644 --- a/interface/wx/log.h +++ b/interface/wx/log.h @@ -1,15 +1,15 @@ ///////////////////////////////////////////////////////////////////////////// // Name: log.h -// Purpose: interface of wxLogWindow +// Purpose: interface of wxLog* classes // Author: wxWidgets team -// RCS-ID: $Id$ -// Licence: wxWindows license +// Licence: wxWindows licence ///////////////////////////////////////////////////////////////////////////// +#if wxUSE_BASE /** Different standard log levels (you may also define your own) used with - by standard wxLog functions wxLogError(), wxLogWarning(), etc... + by standard wxLog functions wxLogGeneric(), wxLogError(), wxLogWarning(), etc... */ enum wxLogLevelValues { @@ -69,1082 +69,1118 @@ 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. + + 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 wxLogTextCtrl + @see @ref overview_log + + @since 2.9.4 */ -class wxLogWindow : public wxLogInterposer +class wxLogFormatter { 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. + 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). - - Return @true from here to allow the frame to close, @false to - prevent this from happening. + This function creates the full log message string. - @see OnFrameDelete() - */ - virtual bool OnFrameClose(wxFrame* frame); + Override it to customize the output string format. - /** - Called immediately after the log frame creation allowing for - any extra initializations. - */ - virtual void OnFrameCreate(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 right before the log frame is going to be deleted: will - always be called unlike OnFrameClose(). + @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 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 log targets 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} + + @see @ref overview_log, @ref group_funcmacro_log "wxLogXXX() functions" */ -class wxLogChain : public wxLog +class wxLog { 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. + /** + @name Log target functions + */ + //@{ - Please see @ref overview_log_customize for explanation of how to change the - default log target. + /** + Instructs wxLog to not create new log targets on the fly if there is none + currently (see GetActiveTarget()). - 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. + (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). - 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. + Note that this function also calls ClearTraceMasks(). + */ + static void DontCreateOnDemand(); - 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 active log target (may be @NULL). - 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 DoShowSingleMessage() to customize - wxLogGui -- the dialogs sample shows how to do this. + 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. - @library{wxcore} - @category{logging} -*/ -class wxLogGui : public wxLog -{ -public: - /** - Default constructor. + 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. - - 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(); + Sets the specified log target as the active one. -protected: - /** - Returns the appropriate title for the dialog. + 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. - 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; + @see SetThreadActiveTarget() + */ + static wxLog* SetActiveTarget(wxLog* logtarget); /** - Returns wxICON_ERROR, wxICON_WARNING or wxICON_INFORMATION depending on - the current maximal severity. - - This value is suitable to be used in the style parameter of - wxMessageBox() function. - */ - int GetSeverityIcon() const; + Sets a thread-specific log target. - /** - Forgets all the currently stored messages. - - 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(); + 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. - /** - Method called by Flush() to show a single log message. + This method is only available if @c wxUSE_THREADS is 1, i.e. wxWidgets + was compiled with threads support. - This function can be overridden to show the message in a different way. - By default a simple wxMessageBox() call is used. + @param logger + The new thread-specific log target, possibly @NULL. + @return + The previous thread-specific log target, initially @NULL. - @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(). + @since 2.9.1 */ - virtual void DoShowSingleLogMessage(const wxString& message, - const wxString& title, - int style); + static wxLog *SetThreadActiveTarget(wxLog *logger); /** - 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. + Flushes the current log target if any, does nothing if there is none. - @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); + 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. + Returns the current log level limit. - If both wxLogGui#m_bErrors and this member are false, there are only - informational messages to be shown. - */ - bool m_bWarnings; + All messages at levels strictly greater than the value returned by this + function are not logged at all. - /** - True if there any messages to be shown to the user. + @see SetLogLevel(), IsLevelEnabled() + */ + static wxLogLevel GetLogLevel(); - 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; -}; + /** + 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 wxLogStream + @since 2.9.1 + */ + static bool IsLevelEnabled(wxLogLevel level, wxString component); - This class can be used to redirect the log messages to a C++ stream. + /** + Sets the log level for the given component. - 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). + For example, to disable all but error messages from wxWidgets network + classes you may use + @code + wxLog::SetComponentLevel("wx/net", wxLOG_Error); + @endcode - @library{wxbase} - @category{logging} + SetLogLevel() may be used to set the global log level. - @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. - */ - wxLogStream(std::ostream *ostr = NULL); -}; + @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. -/** - @class wxLogStderr + @see SetComponentLevel() + */ + static void SetLogLevel(wxLogLevel logLevel); - This class can be used to redirect the log messages to a C file stream (not to - be confused with C++ streams). + //@} - It is the default log target for the non-GUI wxWidgets applications which - send all the output to @c stderr. - @library{wxbase} - @category{logging} - @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. + @name Enable/disable features functions */ - wxLogStderr(FILE* fp = NULL); -}; + //@{ + /** + Globally enable or disable logging. + Calling this function with @false argument disables all log messages + for the current thread. -/** - @class wxLogBuffer + @see wxLogNull, IsEnabled() - 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. + @return + The old state, i.e. @true if logging was previously enabled and + @false if it was disabled. + */ + static bool EnableLogging(bool enable = true); - All the messages collected so far can be shown to the user (and the current - buffer cleared) by calling the overloaded wxLogBuffer::Flush method. + /** + Returns true if logging is enabled at all now. + + @see IsLevelEnabled(), EnableLogging() + */ + static bool IsEnabled(); - @library{wxbase} - @category{logging} -*/ -class wxLogBuffer : public wxLog -{ -public: /** - The default ctor does nothing. + Returns whether the repetition counting mode is enabled. */ - wxLogBuffer(); + static bool GetRepetitionCounting(); /** - 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. + 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. */ - virtual void Flush(); + static void SetRepetitionCounting(bool repetCounting = true); /** - 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 timestamp format string. + + Notice that the current time stamp is only used by the default log + formatter and custom formatters may ignore this format. */ - const wxString& GetBuffer() const; -}; + 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); -/** - @class wxLogInterposer + /** + Disables time stamping of the log messages. - 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. + Notice that the current time stamp is only used by the default log + formatter and custom formatters may ignore calls to this function. - Unlike wxLogChain which is usually used directly as is, this class must be - derived from to implement wxLog::DoLog and/or wxLog::DoLogString methods. + @since 2.9.0 + */ + static void DisableTimestamp(); - wxLogInterposer destroys the previous log target in its destructor. - If you don't want this to happen, use wxLogInterposerTemp instead. + /** + Returns whether the verbose mode is currently active. + */ + static bool GetVerbose(); - @library{wxbase} - @category{logging} -*/ -class wxLogInterposer : public wxLogChain -{ -public: /** - The default constructor installs this object as the current active log target. + 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 */ - wxLogInterposer(); -}; + static void SetVerbose(bool verbose = true); + //@} -/** - @class wxLogTextCtrl + /** + Sets the specified formatter as the active one. - 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. + @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); - @library{wxbase} - @category{logging} - @see wxTextCtrl, wxStreamToTextRedirector -*/ -class wxLogTextCtrl : public wxLog -{ -public: /** - Constructs a log target which sends all the log messages to the given text - control. The @a textctrl parameter cannot be @NULL. + 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. */ - wxLogTextCtrl(wxTextCtrl* pTextCtrl); -}; + 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(). + 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); + // and also send it to the new one + if ( m_logNew && m_logNew != this ) + m_logNew->LogRecord(level, msg, info); + } + @endcode -/** - @class wxLog + @since 2.9.1 + */ + void LogRecord(wxLogLevel level, const wxString& msg, const wxLogRecordInfo& info); - wxLog class defines the interface for the @e log targets 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. Another case is if you wish to customize the behaviour of the standard - logging classes (all of which respect the wxLog settings): for example, set - which trace messages are logged and which are not or change (or even remove - completely) the timestamp on the messages. +protected: + /** + @name Logging callbacks. - Otherwise, it is completely hidden behind the @e wxLogXXX() functions and - you may not even know about its existence. + The functions which should be overridden by custom log targets. - @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. + 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. - @section log_derivingyours Deriving your own log target + 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(). - There are several methods which may be overridden in the derived class to - customize log messages handling: DoLogRecord(), DoLogTextAtLevel() and - DoLogText(). + 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 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(). + /** + Called to log the specified string at given level. - 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). + 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); - There also functions to support message buffering. Why are they needed? - 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). + /** + Called to log the specified string. - Flush() shows them all and clears the buffer contents. - This function doesn't do anything if the buffer is already empty. + 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). - @see FlushActive() + 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); + //@} +}; - @section log_tracemasks Using trace masks - Notice that the use of log trace masks is hardly necessary any longer in - current wxWidgets version as the same effect can be achieved by using - different log components for different log statements of any level. Please - see @ref overview_log_enable for more information about the log components. - The functions below allow some limited customization of wxLog behaviour - without writing a new log target class (which, aside from being a matter of - several minutes, allows you to do anything you want). - The verbose messages are the trace messages which are not disabled in the - release mode and are generated by wxLogVerbose(). - They are not normally shown to the user because they present little interest, - but may be activated, for example, in order to help the user find some program - problem. +/** + @class wxLogChain - 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. + 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. - For example, - @code - wxLogTrace( wxTRACE_OleCalls, "IFoo::Bar() called" ); - @endcode + 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. - will log the message if it was preceded by: + Example of usage: @code - wxLog::AddTraceMask( wxTRACE_OleCalls); - @endcode + wxLogChain *logChain = new wxLogChain(new wxLogStderr); - The standard trace masks are given in wxLogTrace() documentation. - - Finally, the @e wxLog::DoLog() function automatically prepends a time stamp - to all the messages. The format of the time stamp may be changed: it can be - any string with % specifications fully described in the documentation of the - standard @e strftime() function. For example, the default format is - "[%d/%b/%y %H:%M:%S] " which gives something like "[17/Sep/98 22:10:16] " - (without quotes) for the current date. Setting an empty string as the time - format or calling the shortcut wxLog::DisableTimestamp(), disables timestamping - of the messages completely. - - See also - @li AddTraceMask() - @li RemoveTraceMask() - @li ClearTraceMasks() - @li GetTraceMasks() - @li IsAllowedTraceMask() - @li SetVerbose() - @li GetVerbose() - @li SetTimestamp() - @li GetTimestamp() - @li SetTraceMask() - @li GetTraceMask() - @li SetRepetitionCounting() - @li GetRepetitionCounting() - - @note - Timestamping 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, please - use SetTimestamp() explicitly. - - - @section log_target Manipulating the log target - - The functions in this section work with and manipulate the active log - target. - - Get/Set methods are used to install/query the current active target and, - finally, DontCreateOnDemand() disables the automatic creation of a standard - log target if none actually exists. It is only useful when the application - is terminating and shouldn't be used in other situations because it may - easily lead to a loss of messages. - - See also: - @li GetActiveTarget() - @li SetActiveTarget() - @li DontCreateOnDemand() - @li Suspend() - @li Resume() + // 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{wxcore} + @library{wxbase} @category{logging} - - @see @ref overview_log */ -class wxLog +class wxLogChain : public wxLog { public: /** - Add the @a mask to the list of allowed masks for wxLogTrace(). - - @see RemoveTraceMask(), GetTraceMasks() + 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. */ - static void AddTraceMask(const wxString& mask); + wxLogChain(wxLog* logger); /** - Removes all trace masks previously set with AddTraceMask(). - - @see RemoveTraceMask() + Destroys the previous log target. */ - static void ClearTraceMasks(); + virtual ~wxLogChain(); /** - Instructs wxLog to not create new log targets on the fly if there is none - currently. (Almost) for internal use only: it is supposed to be called by the - application shutdown code. - - Note that this function also calls ClearTraceMasks(). + Detaches the old log target so it won't be destroyed when the wxLogChain object + is destroyed. */ - 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); + void DetachOldLog(); /** - 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. + Returns the pointer to the previously active log target (which may be @NULL). */ - virtual void Flush(); + wxLog* GetOldLog() const; /** - 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(). + Returns @true if the messages are passed to the previously active log + target (default) or @false if PassMessages() had been called. */ - static void FlushActive(); + bool IsPassingMessages() const; /** - 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. + 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. */ - static wxLog* GetActiveTarget(); + void PassMessages(bool passMessages); /** - Returns the current log level limit. - - All messages at levels strictly greater than the value returned by this - function are not logged at all. + Sets another log target to use (may be @NULL). - @see SetLogLevel(), IsLevelEnabled() + 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. */ - static wxLogLevel GetLogLevel(); + void SetLog(wxLog* logger); +}; - /** - Returns whether the repetition counting mode is enabled. - */ - static bool GetRepetitionCounting(); - /** - Returns the current timestamp format string. - */ - static const wxString& GetTimestamp(); - /** - @deprecated - Returns the current trace mask, see Customization() section for details. - */ - static wxTraceMask GetTraceMask(); +/** + @class wxLogInterposer - /** - 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. - @see AddTraceMask(). - */ - static const wxArrayString& GetTraceMasks(); + Unlike wxLogChain which is usually used directly as is, this class must be + derived from to implement wxLog::DoLog and/or wxLog::DoLogString methods. + 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: /** - Returns whether the verbose mode is currently active. + The default constructor installs this object as the current active log target. */ - static bool GetVerbose(); + wxLogInterposer(); +}; - /** - Returns @true if the @a mask is one of allowed masks for wxLogTrace(). - See also: AddTraceMask(), RemoveTraceMask() - */ - static bool IsAllowedTraceMask(const wxString& mask); +/** + @class wxLogInterposerTemp + + 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. + + 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 logging is enabled at all now. + The default constructor installs this object as the current active log target. + */ + wxLogInterposerTemp(); +}; - @see IsLevelEnabled(), EnableLogging() - */ - static bool IsEnabled(); +/** + @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). + + @library{wxbase} + @category{logging} + + @see wxLogStderr, wxStreamToTextRedirector +*/ +class wxLogStream : public wxLog +{ +public: /** - Returns true if logging at this level is enabled for the current thread. + 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. + */ + wxLogStream(std::ostream *ostr = NULL); +}; - 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); +/** + @class wxLogStderr + This class can be used to redirect the log messages to a C file stream (not to + be confused with C++ streams). + + It is the default log target for the non-GUI wxWidgets applications which + send all the output to @c stderr. + + @library{wxbase} + @category{logging} + + @see wxLogStream +*/ +class wxLogStderr : public wxLog +{ +public: /** - Remove the @a mask from the list of allowed masks for - wxLogTrace(). + 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); +}; - @see AddTraceMask() + + +/** + @class wxLogBuffer + + 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. + + All the messages collected so far can be shown to the user (and the current + buffer cleared) by calling the overloaded wxLogBuffer::Flush method. + + @library{wxbase} + @category{logging} +*/ +class wxLogBuffer : public wxLog +{ +public: + /** + The default ctor does nothing. */ - static void RemoveTraceMask(const wxString& mask); + wxLogBuffer(); /** - Resumes logging previously suspended by a call to Suspend(). - All messages logged in the meanwhile will be flushed soon. + 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 Resume(); + virtual void Flush(); /** - Sets the specified log target as the active one. + 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. + */ + const wxString& GetBuffer() const; +}; - 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 the log level for the given component. +/** + @class wxLogNull - For example, to disable all but error messages from wxWidgets network - classes you may use - @code - wxLog::SetComponentLevel("wx/net", wxLOG_Error); - @endcode + 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. - SetLogLevel() may be used to set the global log level. + 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. - @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. + For instance, the example of the overview: - @since 2.9.1 - */ - static void SetComponentLevel(const wxString& component, wxLogLevel level); + @code + wxFile file; - /** - Specifies that log messages with level greater (numerically) than - @a logLevel should be ignored and not sent to the active log target. + // 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 - @see SetComponentLevel() - */ - static void SetLogLevel(wxLogLevel logLevel); + wxLogMessage("..."); // ok + @endcode + + 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 + + + @library{wxbase} + @category{logging} +*/ +class wxLogNull +{ +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. + Suspends logging. */ - static void SetRepetitionCounting(bool repetCounting = true); + wxLogNull(); /** - Sets a thread-specific log target. + Resumes logging. + */ + ~wxLogNull(); +}; - 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. +#endif // wxUSE_BASE - Notice that unlike for SetActiveTarget(), wxWidgets does not destroy - the thread-specific log targets when the thread terminates so doing - this is your responsibility. +#if wxUSE_GUI - This method is only available if @c wxUSE_THREADS is 1, i.e. wxWidgets - was compiled with threads support. +/** + @class wxLogWindow - @param logger - The new thread-specific log target, possibly @NULL. - @return - The previous thread-specific log target, initially @NULL. + 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. - @since 2.9.1 - */ - static wxLog *SetThreadActiveTarget(wxLog *logger); + @library{wxcore} + @category{logging} + @see wxLogTextCtrl +*/ +class wxLogWindow : public wxLogInterposer +{ +public: /** - 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 specificators, see @e strftime() manual for details. - Passing an empty string to this function disables message time stamping. + 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. */ - static void SetTimestamp(const wxString& format); + wxLogWindow(wxWindow* pParent, const wxString& szTitle, bool show = true, + bool passToOld = true); /** - Disables time stamping of the log messages. + 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; - @since 2.9.0 + /** + Called if the user closes the window interactively, will not be + called if it is destroyed for another reason (such as when program + exits). + + Return @true from here to allow the frame to close, @false to + prevent this from happening. + + @see OnFrameDelete() */ - static void DisableTimestamp(); + virtual bool OnFrameClose(wxFrame* frame); + + /** + Called right before the log frame is going to be deleted: will + always be called unlike OnFrameClose(). + */ + virtual void OnFrameDelete(wxFrame* frame); /** - @deprecated - Sets the trace mask, see @ref log_tracemasks section for details. + Shows or hides the frame. */ - static void SetTraceMask(wxTraceMask mask); + 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. + + 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. + + @library{wxcore} + @category{logging} +*/ +class wxLogGui : public wxLog +{ +public: /** - Activates or deactivates verbose mode in which the verbose messages are - logged as the normal ones instead of being silently dropped. + Default constructor. */ - static void SetVerbose(bool verbose = true); + wxLogGui(); /** - 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 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). + Presents the accumulated log messages, if any, to the user. - @see Resume(), wxLogNull - */ - static void Suspend(); + 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(); +protected: /** - 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(). + 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, time_t timestamp); + 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 created 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} + + @see wxTextCtrl, wxStreamToTextRedirector */ -class wxLogNull +class wxLogTextCtrl : public wxLog { 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 @@ -1196,6 +1232,18 @@ const wxChar* wxSysErrorMsg(unsigned long errCode = 0); //@} +/** @addtogroup group_funcmacro_log */ +//@{ +/** + Logs a message with the given wxLogLevel. + E.g. using @c wxLOG_Message as first argument, this function behaves like wxLogMessage(). + + @header{wx/log.h} +*/ +void wxLogGeneric(wxLogLevel level, const char* formatString, ... ); +void wxVLogGeneric(wxLogLevel level, const char* formatString, va_list argPtr); +//@} + /** @addtogroup group_funcmacro_log */ //@{ /** @@ -1262,7 +1310,7 @@ void wxVLogError(const char* formatString, va_list argPtr); /** @addtogroup group_funcmacro_log */ //@{ /** - Log a message at wxLOG_Trace log level. + Log a message at @c wxLOG_Trace log level (see ::wxLogLevelValues enum). Notice that the use of trace masks is not recommended any more as setting the log components (please see @ref overview_log_enable) provides a way to @@ -1274,30 +1322,10 @@ 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. - 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 *mask, const char* formatString, ... ); -void wxVLogTrace(const char *mask, const char* formatString, va_list argPtr); -//@} - -/** @addtogroup group_funcmacro_log */ -//@{ -/** - Like wxLogDebug(), trace functions only do something in debug builds and - expand to nothing in the release one. The reason for making it a separate - function is that usually there are a lot of trace messages, so it might - make sense to separate them from other debug messages. - - In this version of wxLogTrace(), trace messages can be separated into - different categories and calls using this function only log the message if - the given @a mask is currently enabled in wxLog. This lets you selectively - trace only some operations and not others by enabling the desired trace - masks with wxLog::AddTraceMask() or by setting the + Trace messages can be separated into different categories; these functions in facts + only log the message if the given @a mask is currently enabled in wxLog. + This lets you selectively trace only some operations and not others by enabling the + desired trace masks with wxLog::AddTraceMask() or by setting the @ref overview_envvars "@c WXTRACE environment variable". The predefined string trace masks used by wxWidgets are: @@ -1310,22 +1338,10 @@ void wxVLogTrace(const char *mask, const char* formatString, va_list argPtr); @itemdef{ wxTRACE_OleCalls, Trace OLE method calls (Win32 only) } @endDefList - @note Since both the mask and the format string are strings, this might - lead to function signature confusion in some cases: if you intend to - call the format string only version of wxLogTrace(), add a "%s" - format string parameter and then supply a second string parameter for - that "%s", the string mask version of wxLogTrace() will erroneously - get called instead, since you are supplying two string parameters to - the function. In this case you'll unfortunately have to avoid having - two leading string parameters, e.g. by adding a bogus integer (with - its "%d" format string). - @header{wx/log.h} */ void wxLogTrace(const char* mask, const char* formatString, ... ); -void wxVLogTrace(const char* mask, - const char* formatString, - va_list argPtr); +void wxVLogTrace(const char* mask, const char* formatString, va_list argPtr); //@} /** @addtogroup group_funcmacro_log */ @@ -1395,7 +1411,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 - 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. @@ -1429,3 +1445,4 @@ void wxVLogSysError(const char* formatString, va_list argPtr); //@} +#endif // wxUSE_BASE