/////////////////////////////////////////////////////////////////////////////
// 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
+
/**
- @class wxLogWindow
+ Different standard log levels (you may also define your own) used with
+ by standard wxLog functions wxLogGeneric(), wxLogError(), wxLogWarning(), etc...
+*/
+enum wxLogLevelValues
+{
+ wxLOG_FatalError, //!< program can't continue, abort immediately
+ wxLOG_Error, //!< a serious error, user must be informed about it
+ wxLOG_Warning, //!< user is normally informed about it but may be ignored
+ wxLOG_Message, //!< normal message (i.e. normal output of a non GUI app)
+ wxLOG_Status, //!< informational: might go to the status line of GUI app
+ wxLOG_Info, //!< informational message (a.k.a. 'Verbose')
+ wxLOG_Debug, //!< never shown to the user, disabled in release mode
+ wxLOG_Trace, //!< trace messages are also only enabled in debug mode
+ wxLOG_Progress, //!< used for progress indicator (not yet)
+ wxLOG_User = 100, //!< user defined levels start here
+ wxLOG_Max = 10000
+};
- 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.
+/**
+ The type used to specify a log level.
+
+ Default values of ::wxLogLevel used by wxWidgets are contained in the
+ ::wxLogLevelValues enumeration.
+*/
+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 wxLogFormatter
+
+ wxLogFormatter class is used to format the log messages. It implements the
+ default formatting and can be derived from to create custom formatters.
+
+ The default implementation formats the message into a string containing
+ the time stamp, level-dependent prefix and the message itself.
+
+ To change it, you can derive from it and override its Format() method. For
+ example, to include the thread id in the log messages you can use
+ @code
+ class LogFormatterWithThread : public wxLogFormatter
+ {
+ virtual wxString Format(wxLogLevel level,
+ const wxString& msg,
+ const wxLogRecordInfo& info) const
+ {
+ return wxString::Format("[%d] %s(%d) : %s",
+ info.threadId, info.filename, info.line, msg);
+ }
+ };
+ @endcode
+ And then associate it with wxLog instance using its SetFormatter(). Then,
+ if you call:
+
+ @code
+ wxLogMessage(_("*** Application started ***"));
+ @endcode
+
+ the log output could be something like:
+
+ @verbatim
+ [7872] d:\testApp\src\testApp.cpp(85) : *** Application started ***
+ @endverbatim
@library{wxbase}
@category{logging}
- @see 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.
+ The default ctor does nothing.
+ */
+ wxLogFormatter();
- @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.
+
+ /**
+ This function creates the full log message string.
+
+ Override it to customize the output string format.
+
+ @param level
+ The level of this log record, e.g. ::wxLOG_Error.
+ @param msg
+ The log message itself.
+ @param info
+ All the other information (such as time, component, location...)
+ associated with this log record.
+
+ @return
+ The formated message.
+
+ @note
+ Time stamping is disabled for Visual C++ users in debug builds by
+ default because otherwise it would be impossible to directly go to the line
+ from which the log message was generated by simply clicking in the debugger
+ window on the corresponding error message. If you wish to enable it, override
+ FormatTime().
*/
- wxLogWindow(wxWindow* pParent, const wxString& szTitle, bool show = true,
- bool passToOld = true);
+ virtual wxString Format(wxLogLevel level,
+ const wxString& msg,
+ const wxLogRecordInfo& info) const;
+protected:
/**
- Returns the associated log frame window. This may be used to position or resize
- it but use Show() to show or hide it.
+ 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.
*/
- wxFrame* GetFrame() const;
+ 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:
/**
- Called if the user closes the window interactively, will not be
- called if it is destroyed for another reason (such as when program
- exits).
+ @name Trace mask functions
+ */
+ //@{
- Return @true from here to allow the frame to close, @false to
- prevent this from happening.
+ /**
+ Add the @a mask to the list of allowed masks for wxLogTrace().
- @see OnFrameDelete()
+ @see RemoveTraceMask(), GetTraceMasks()
*/
- virtual bool OnFrameClose(wxFrame* frame);
+ static void AddTraceMask(const wxString& mask);
/**
- Called immediately after the log frame creation allowing for
- any extra initializations.
+ Removes all trace masks previously set with AddTraceMask().
+
+ @see RemoveTraceMask()
*/
- virtual void OnFrameCreate(wxFrame* frame);
+ static void ClearTraceMasks();
/**
- Called right before the log frame is going to be deleted: will
- always be called unlike OnFrameClose().
+ Returns the currently allowed list of string trace masks.
+
+ @see AddTraceMask().
*/
- virtual void OnFrameDelete(wxFrame* frame);
+ static const wxArrayString& GetTraceMasks();
/**
- Shows or hides the frame.
+ Returns @true if the @a mask is one of allowed masks for wxLogTrace().
+
+ See also: AddTraceMask(), RemoveTraceMask()
*/
- void Show(bool show = true);
-};
+ 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);
-/**
- @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:
/**
- The default constructor installs this object as the current active log target.
+ @name Log target functions
*/
- wxLogInterposerTemp();
+ //@{
+
+ /**
+ 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();
+
+ /**
+ Returns whether the verbose mode is currently active.
+ */
+ static bool GetVerbose();
+
+ /**
+ 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
+ */
+ static void SetVerbose(bool verbose = true);
+
+ //@}
+
+
+ /**
+ Sets the specified formatter as the active one.
+
+ @param formatter
+ The new formatter. If @NULL, reset to the default formatter.
+
+ Returns the pointer to the previous formatter. You must delete it
+ if you don't plan to attach it again to a wxLog object later.
+
+ @since 2.9.4
+ */
+ wxLogFormatter *SetFormatter(wxLogFormatter* formatter);
+
+
+ /**
+ 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.
+ */
+ 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
+
+ @since 2.9.1
+ */
+ void LogRecord(wxLogLevel level, const wxString& msg, const wxLogRecordInfo& info);
+
+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 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);
+
+ /**
+ 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 DoLogTextAtLevel(wxLogLevel level, const wxString& msg);
+
+ /**
+ Called to log the specified string.
+
+ 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 DoLogText(const wxString& msg);
+
+ //@}
};
/**
- @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.
+ @class wxLogInterposer
- 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.
+ 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.
- 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.
+ Unlike wxLogChain which is usually used directly as is, this class must be
+ derived from to implement wxLog::DoLog and/or wxLog::DoLogString methods.
- 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.
+ wxLogInterposer destroys the previous log target in its destructor.
+ If you don't want this to happen, use wxLogInterposerTemp instead.
- @library{wxcore}
+ @library{wxbase}
@category{logging}
*/
-class wxLogGui : public wxLog
+class wxLogInterposer : public wxLogChain
{
public:
/**
- Default constructor.
+ The default constructor installs this object as the current active log target.
*/
- wxLogGui();
-
- /**
- 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();
-
-protected:
- /**
- Returns the appropriate title for the dialog.
-
- 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;
-
- /**
- 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;
-
- /**
- 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();
-
-
- /**
- Method called by Flush() to show a single log message.
-
- This function can be overridden to show the message in a different way.
- By default a simple wxMessageBox() call is used.
-
- @param message
- The message to show (it can contain multiple lines).
- @param title
- The suggested title for the dialog showing the message, see
- GetTitle().
- @param style
- One of @c wxICON_XXX constants, see GetSeverityIcon().
- */
- virtual void DoShowSingleLogMessage(const wxString& message,
- const wxString& title,
- int style);
-
- /**
- Method called by Flush() to show multiple log messages.
-
- This function can be overridden to show the messages in a different way.
- By default a special log dialog showing the most recent message and
- allowing the user to expand it to view the previously logged ones is
- used.
-
- @param messages
- Array of messages to show; it contains more than one element.
- @param severities
- Array of message severities containing @c wxLOG_XXX values.
- @param times
- Array of time_t values indicating when each message was logged.
- @param title
- The suggested title for the dialog showing the message, see
- GetTitle().
- @param style
- One of @c wxICON_XXX constants, see GetSeverityIcon().
- */
- virtual void DoShowMultipleLogMessages(const wxArrayString& messages,
- const wxArrayInt& severities,
- const wxArrayLong& times,
- const wxString& title,
- int style);
-
-
- /**
- All currently accumulated messages.
-
- This array may be empty if no messages were logged.
-
- @see m_aSeverity, m_aTimes
- */
- wxArrayString m_aMessages;
-
- /**
- The severities of each logged message.
-
- 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;
+ wxLogInterposer();
+};
- /**
- 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;
+/**
+ @class wxLogInterposerTemp
- /**
- True if there any messages to be shown to the user.
+ 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.
- 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;
-};
+ 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:
+ /**
+ The default constructor installs this object as the current active log target.
+ */
+ wxLogInterposerTemp();
+};
/**
/**
- @class wxLogInterposer
+ @class wxLogNull
- 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.
+ 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.
- Unlike wxLogChain which is usually used directly as is, this class must be
- derived from to implement wxLog::DoLog and/or wxLog::DoLogString methods.
+ 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.
- wxLogInterposer destroys the previous log target in its destructor.
- If you don't want this to happen, use wxLogInterposerTemp instead.
+ For instance, the example of the overview:
- @library{wxbase}
- @category{logging}
-*/
-class wxLogInterposer : public wxLogChain
-{
-public:
- /**
- The default constructor installs this object as the current active log target.
- */
- wxLogInterposer();
-};
+ @code
+ wxFile file;
+
+ // 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
+ wxLogMessage("..."); // ok
+ @endcode
+ would be better written as:
-/**
- @class wxLogTextCtrl
+ @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
- 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}
@category{logging}
-
- @see wxTextCtrl, wxStreamToTextRedirector
*/
-class wxLogTextCtrl : public wxLog
+class wxLogNull
{
public:
/**
- Constructs a log target which sends all the log messages to the given text
- control. The @a textctrl parameter cannot be @NULL.
+ Suspends logging.
*/
- wxLogTextCtrl(wxTextCtrl* pTextCtrl);
+ wxLogNull();
+
+ /**
+ Resumes logging.
+ */
+ ~wxLogNull();
};
+#endif // wxUSE_BASE
+#if wxUSE_GUI
/**
- @class wxLog
-
- 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.
-
- Otherwise, it is completely hidden behind the @e 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.
-
-
- @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.
-
- 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).
-
- 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).
-
- 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()
-
-
- @section log_tracemasks Using trace masks
-
- 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.
-
- 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.
-
- 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
-
- will log the message if it was preceded by:
-
- @code
- 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
- 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. The OnLog() is called by the @e wxLogXXX() functions
- and invokes the DoLog() of the active log target if any.
-
- 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 OnLog()
- @li GetActiveTarget()
- @li SetActiveTarget()
- @li DontCreateOnDemand()
- @li Suspend()
- @li Resume()
+ @class wxLogWindow
+ 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.
@library{wxcore}
@category{logging}
- @see @ref overview_log
+ @see wxLogTextCtrl
*/
-class wxLog
+class wxLogWindow : public wxLogInterposer
{
public:
/**
- Add the @a mask to the list of allowed masks for wxLogTrace().
+ Creates the log frame window and starts collecting the messages in it.
- @see RemoveTraceMask(), GetTraceMasks()
+ @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 AddTraceMask(const wxString& mask);
+ wxLogWindow(wxWindow* pParent, const wxString& szTitle, bool show = true,
+ bool passToOld = true);
/**
- Removes all trace masks previously set with AddTraceMask().
-
- @see RemoveTraceMask()
+ Returns the associated log frame window. This may be used to position or resize
+ it but use Show() to show or hide it.
*/
- static void ClearTraceMasks();
+ wxFrame* GetFrame() const;
/**
- 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.
+ Called if the user closes the window interactively, will not be
+ called if it is destroyed for another reason (such as when program
+ exits).
- Note that this function also calls ClearTraceMasks().
- */
- static void DontCreateOnDemand();
+ Return @true from here to allow the frame to close, @false to
+ prevent this from happening.
- /**
- Shows all the messages currently in buffer and clears it.
- If the buffer is already empty, nothing happens.
+ @see OnFrameDelete()
*/
- virtual void Flush();
+ virtual bool OnFrameClose(wxFrame* frame);
/**
- Flushes the current log target if any, does nothing if there is none.
-
- @see Flush()
+ Called right before the log frame is going to be deleted: will
+ always be called unlike OnFrameClose().
*/
- static void FlushActive();
+ virtual void OnFrameDelete(wxFrame* frame);
/**
- Returns the pointer to the active log target (may be @NULL).
+ Shows or hides the frame.
*/
- static wxLog* GetActiveTarget();
+ void Show(bool show = true);
+};
- /**
- Returns the current log level limit.
- */
- static wxLogLevel GetLogLevel();
- /**
- Returns whether the repetition counting mode is enabled.
- */
- static bool GetRepetitionCounting();
- /**
- Returns the current timestamp format string.
- */
- static const wxString GetTimestamp();
+/**
+ @class wxLogGui
- /**
- Returns the current trace mask, see Customization() section for details.
- */
- static wxTraceMask GetTraceMask();
+ 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:
/**
- Returns the currently allowed list of string trace masks.
-
- @see AddTraceMask().
+ Default constructor.
*/
- static const wxArrayString GetTraceMasks();
+ wxLogGui();
/**
- Returns whether the verbose mode is currently active.
- */
- static bool GetVerbose();
+ 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();
+protected:
/**
- Returns @true if the @a mask is one of allowed masks for wxLogTrace().
+ Returns the appropriate title for the dialog.
- See also: AddTraceMask(), RemoveTraceMask()
- */
- static bool IsAllowedTraceMask(const wxString& mask);
+ 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;
/**
- 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& message);
+ 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;
/**
- Remove the @a mask from the list of allowed masks for
- wxLogTrace().
+ Forgets all the currently stored messages.
- @see AddTraceMask()
- */
- static void RemoveTraceMask(const wxString& mask);
+ 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();
- /**
- Resumes logging previously suspended by a call to Suspend().
- All messages logged in the meanwhile will be flushed soon.
- */
- static void Resume();
/**
- Sets the specified log target as the active one.
+ All currently accumulated messages.
- 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.
- */
- static wxLog* SetActiveTarget(wxLog* logtarget);
+ This array may be empty if no messages were logged.
- /**
- Specifies that log messages with level logLevel should be ignored
- and not sent to the active log target.
- */
- static void SetLogLevel(wxLogLevel logLevel);
+ @see m_aSeverity, m_aTimes
+ */
+ wxArrayString m_aMessages;
/**
- 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);
+ The severities of each logged message.
- /**
- 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.
- */
- static void SetTimestamp(const wxString& format);
+ 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;
/**
- Disables time stamping of the log messages.
+ The time stamps of each logged message.
- @since 2.9.0
- */
- static void DisableTimestamp();
+ The elements of this array are time_t values corresponding to the time
+ when the message was logged.
+ */
+ wxArrayLong m_aTimes;
/**
- Sets the trace mask, see @ref log_derivingyours section for details.
- */
- static void SetTraceMask(wxTraceMask mask);
+ True if there any error messages.
+ */
+ bool m_bErrors;
/**
- Activates or deactivates verbose mode in which the verbose messages are
- logged as the normal ones instead of being silently dropped.
- */
- static void SetVerbose(bool verbose = true);
+ 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;
/**
- Suspends the logging until Resume() is called.
+ True if there any messages to be shown to the user.
- 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.
+ 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;
- 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).
+private:
+ /**
+ Method called by Flush() to show a single log message.
- @see Resume(), wxLogNull
- */
- static void Suspend();
+ This function can be overridden to show the message in a different way.
+ By default a simple wxMessageBox() call is used.
-protected:
+ @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);
/**
- 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.
-
- 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.
- */
- virtual void DoLog(wxLogLevel level, const wxString& msg, time_t timestamp);
+ Method called by Flush() to show multiple log messages.
- /**
- Called to log the specified string. The timestamp is already included in the
- string but still passed to this function.
+ 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.
- A simple implementation may just send the string to @c stdout or, better,
- @c stderr.
- */
- virtual void DoLogString(const wxString& msg, time_t timestamp);
+ @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);
};
/**
- @class wxLogNull
-
- 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.
-
- 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.
-
- For instance, the example of the overview:
-
- @code
- wxFile file;
-
- // 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
-
- 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
+ @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 : public wxLog
+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
// ============================================================================
-/** @ingroup group_funcmacro_log */
+/** @addtogroup group_funcmacro_log */
//@{
/**
//@}
-/** @ingroup group_funcmacro_log */
+/** @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 */
//@{
/**
For all normal, informational messages. They also appear in a message box
void wxVLogMessage(const char* formatString, va_list argPtr);
//@}
-/** @ingroup group_funcmacro_log */
+/** @addtogroup group_funcmacro_log */
//@{
/**
For verbose output. Normally, it is suppressed, but might be activated if
void wxVLogVerbose(const char* formatString, va_list argPtr);
//@}
-/** @ingroup group_funcmacro_log */
+/** @addtogroup group_funcmacro_log */
//@{
/**
For warnings - they are also normally shown to the user, but don't
void wxVLogWarning(const char* formatString, va_list argPtr);
//@}
-/** @ingroup group_funcmacro_log */
+/** @addtogroup group_funcmacro_log */
//@{
/**
Like wxLogError(), but also terminates the program with the exit code 3.
void wxVLogFatalError(const char* formatString, va_list argPtr);
//@}
-/** @ingroup group_funcmacro_log */
+/** @addtogroup group_funcmacro_log */
//@{
/**
The functions to use for error messages, i.e. the messages that must be
void wxVLogError(const char* formatString, va_list argPtr);
//@}
-/** @ingroup group_funcmacro_log */
+/** @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.
+ Log a message at @c wxLOG_Trace log level (see ::wxLogLevelValues enum).
- 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.
-
- @header{wx/log.h}
-*/
-void wxLogTrace(const char* formatString, ... );
-void wxVLogTrace(const char* formatString, va_list argPtr);
-//@}
+ 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
+ do the same thing for log messages of any level, and not just the tracing
+ ones.
-/** @ingroup 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:
@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);
//@}
-/** @ingroup group_funcmacro_log */
+/** @addtogroup group_funcmacro_log */
//@{
/**
Like wxLogDebug(), trace functions only do something in debug builds and
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.
void wxVLogTrace(wxTraceMask mask, const char* formatString, va_list argPtr);
//@}
-/** @ingroup group_funcmacro_log */
+/** @addtogroup group_funcmacro_log */
//@{
/**
The right functions for debug output. They only do something in debug mode
void wxVLogDebug(const char* formatString, va_list argPtr);
//@}
-/** @ingroup group_funcmacro_log */
+/** @addtogroup group_funcmacro_log */
//@{
/**
Messages logged by this function will appear in the statusbar of the
void wxVLogStatus(const char* formatString, va_list argPtr);
//@}
-/** @ingroup group_funcmacro_log */
+/** @addtogroup group_funcmacro_log */
//@{
/**
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.
void wxVLogSysError(const char* formatString, va_list argPtr);
//@}
+/** @addtogroup group_funcmacro_debug */
+//@{
+
+/**
+ @def wxDISABLE_DEBUG_LOGGING_IN_RELEASE_BUILD()
+
+ Use this macro to disable logging at debug and trace levels in release
+ build when not using wxIMPLEMENT_APP().
+
+ @see wxDISABLE_DEBUG_SUPPORT(),
+ wxDISABLE_ASSERTS_IN_RELEASE_BUILD(),
+ @ref overview_debugging
+
+ @since 2.9.1
+
+ @header{wx/log.h}
+ */
+#define wxDISABLE_DEBUG_LOGGING_IN_RELEASE_BUILD()
+
+//@}
+
+#endif // wxUSE_BASE
projects / wxWidgets.git / blobdiff