Version: 3.1.1
wxLogGui Class Reference

#include <wx/log.h>

+ Inheritance diagram for wxLogGui:

Detailed Description

This is the default log target for the GUI wxWidgets applications.

Please see Logging Customization 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 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

Public Member Functions

 wxLogGui ()
 Default constructor. More...
 
virtual void Flush ()
 Presents the accumulated log messages, if any, to the user. More...
 
- Public Member Functions inherited from wxLog
wxLogFormatterSetFormatter (wxLogFormatter *formatter)
 Sets the specified formatter as the active one. More...
 
void LogRecord (wxLogLevel level, const wxString &msg, const wxLogRecordInfo &info)
 Log the given record. More...
 

Protected Member Functions

wxString GetTitle () const
 Returns the appropriate title for the dialog. More...
 
int GetSeverityIcon () const
 Returns wxICON_ERROR, wxICON_WARNING or wxICON_INFORMATION depending on the current maximal severity. More...
 
void Clear ()
 Forgets all the currently stored messages. More...
 
- Protected Member Functions inherited from wxLog
virtual void DoLogRecord (wxLogLevel level, const wxString &msg, const wxLogRecordInfo &info)
 Called to log a new record. More...
 
virtual void DoLogTextAtLevel (wxLogLevel level, const wxString &msg)
 Called to log the specified string at given level. More...
 
virtual void DoLogText (const wxString &msg)
 Called to log the specified string. More...
 

Protected Attributes

wxArrayString m_aMessages
 All currently accumulated messages. More...
 
wxArrayInt m_aSeverity
 The severities of each logged message. More...
 
wxArrayLong m_aTimes
 The time stamps of each logged message. More...
 
bool m_bErrors
 True if there any error messages. More...
 
bool m_bWarnings
 True if there any warning messages. More...
 
bool m_bHasMessages
 True if there any messages to be shown to the user. More...
 

Private Member Functions

virtual void DoShowSingleLogMessage (const wxString &message, const wxString &title, int style)
 Method called by Flush() to show a single log message. More...
 
virtual void DoShowMultipleLogMessages (const wxArrayString &messages, const wxArrayInt &severities, const wxArrayLong &times, const wxString &title, int style)
 Method called by Flush() to show multiple log messages. More...
 

Additional Inherited Members

- Static Public Member Functions inherited from wxLog
static void AddTraceMask (const wxString &mask)
 Add the mask to the list of allowed masks for wxLogTrace(). More...
 
static void ClearTraceMasks ()
 Removes all trace masks previously set with AddTraceMask(). More...
 
static const wxArrayStringGetTraceMasks ()
 Returns the currently allowed list of string trace masks. More...
 
static bool IsAllowedTraceMask (const wxString &mask)
 Returns true if the mask is one of allowed masks for wxLogTrace(). More...
 
static void RemoveTraceMask (const wxString &mask)
 Remove the mask from the list of allowed masks for wxLogTrace(). More...
 
static void DontCreateOnDemand ()
 Instructs wxLog to not create new log targets on the fly if there is none currently (see GetActiveTarget()). More...
 
static wxLogGetActiveTarget ()
 Returns the pointer to the active log target (may be NULL). More...
 
static wxLogSetActiveTarget (wxLog *logtarget)
 Sets the specified log target as the active one. More...
 
static wxLogSetThreadActiveTarget (wxLog *logger)
 Sets a thread-specific log target. More...
 
static void FlushActive ()
 Flushes the current log target if any, does nothing if there is none. More...
 
static void Resume ()
 Resumes logging previously suspended by a call to Suspend(). More...
 
static void Suspend ()
 Suspends the logging until Resume() is called. More...
 
static wxLogLevel GetLogLevel ()
 Returns the current log level limit. More...
 
static bool IsLevelEnabled (wxLogLevel level, wxString component)
 Returns true if logging at this level is enabled for the current thread. More...
 
static void SetComponentLevel (const wxString &component, wxLogLevel level)
 Sets the log level for the given component. More...
 
static void SetLogLevel (wxLogLevel logLevel)
 Specifies that log messages with level greater (numerically) than logLevel should be ignored and not sent to the active log target. More...
 
static bool EnableLogging (bool enable=true)
 Globally enable or disable logging. More...
 
static bool IsEnabled ()
 Returns true if logging is enabled at all now. More...
 
static bool GetRepetitionCounting ()
 Returns whether the repetition counting mode is enabled. More...
 
static void SetRepetitionCounting (bool repetCounting=true)
 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. More...
 
static const wxStringGetTimestamp ()
 Returns the current timestamp format string. More...
 
static void SetTimestamp (const wxString &format)
 Sets the timestamp format prepended by the default log targets to all messages. More...
 
static void DisableTimestamp ()
 Disables time stamping of the log messages. More...
 
static bool GetVerbose ()
 Returns whether the verbose mode is currently active. More...
 
static void SetVerbose (bool verbose=true)
 Activates or deactivates verbose mode in which the verbose messages are logged as the normal ones instead of being silently dropped. More...
 

Constructor & Destructor Documentation

wxLogGui::wxLogGui ( )

Default constructor.

Member Function Documentation

void wxLogGui::Clear ( )
protected

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.

virtual void wxLogGui::DoShowMultipleLogMessages ( const wxArrayString messages,
const wxArrayInt severities,
const wxArrayLong times,
const wxString title,
int  style 
)
privatevirtual

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.

Parameters
messagesArray of messages to show; it contains more than one element.
severitiesArray of message severities containing wxLOG_XXX values.
timesArray of time_t values indicating when each message was logged.
titleThe suggested title for the dialog showing the message, see GetTitle().
styleOne of wxICON_XXX constants, see GetSeverityIcon().
virtual void wxLogGui::DoShowSingleLogMessage ( const wxString message,
const wxString title,
int  style 
)
privatevirtual

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.

Parameters
messageThe message to show (it can contain multiple lines).
titleThe suggested title for the dialog showing the message, see GetTitle().
styleOne of wxICON_XXX constants, see GetSeverityIcon().
virtual void wxLogGui::Flush ( )
virtual

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.

Reimplemented from wxLog.

int wxLogGui::GetSeverityIcon ( ) const
protected

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.

wxString wxLogGui::GetTitle ( ) const
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.

Member Data Documentation

wxArrayString wxLogGui::m_aMessages
protected

All currently accumulated messages.

This array may be empty if no messages were logged.

See also
m_aSeverity, m_aTimes
wxArrayInt wxLogGui::m_aSeverity
protected

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 wxLOG_XXX constants, e.g. wxLOG_Error, wxLOG_Warning, wxLOG_Message etc.

wxArrayLong wxLogGui::m_aTimes
protected

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.

bool wxLogGui::m_bErrors
protected

True if there any error messages.

bool wxLogGui::m_bHasMessages
protected

True if there any messages to be shown to the user.

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 wxLogGui::m_bWarnings
protected

True if there any warning messages.

If both wxLogGui::m_bErrors and this member are false, there are only informational messages to be shown.