From 5d81550097b18ecd1d980f4f5479fb2ccf4a8e68 Mon Sep 17 00:00:00 2001 From: Vadim Zeitlin Date: Thu, 11 Sep 2008 14:03:48 +0000 Subject: [PATCH] made wxLogGui more flexible and documented it and added example of customizing it to the dialogs sample (now with the docs) git-svn-id: https://svn.wxwidgets.org/svn/wx/wxWidgets/trunk@55554 c3d73ce0-8a6f-49c7-b76d-6d57e0e08775 --- interface/wx/log.h | 197 +++++++++++++++++++++++++++++++++++++++++---- 1 file changed, 183 insertions(+), 14 deletions(-) diff --git a/interface/wx/log.h b/interface/wx/log.h index fb684e769f..df0ffcea37 100644 --- a/interface/wx/log.h +++ b/interface/wx/log.h @@ -188,11 +188,50 @@ public: /** @class wxLogGui - This is the default log target for the GUI wxWidgets applications. It is passed - to wxLog::SetActiveTarget at the program - startup and is deleted by wxWidgets during the program shut down. + 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 DoShowSingleMessage() to customize + wxLogGui -- the dialogs sample shows how to do this. - @library{wxbase} + @library{wxcore} @category{logging} */ class wxLogGui : public wxLog @@ -202,6 +241,138 @@ public: Default constructor. */ 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; + + /** + 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. + + 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; }; @@ -494,9 +665,6 @@ public: */ static void ClearTraceMasks(); - */ - - /** Disables time stamping of the log messages. This function is new since wxWidgets version 2.9 @@ -629,17 +797,18 @@ public: static void RemoveTraceMask(const wxString& mask); /** - Resumes logging previously suspended by a call to - Suspend(). All messages logged in the meanwhile will be - flushed soon. + 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. 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. + 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. */ static wxLog* SetActiveTarget(wxLog* logtarget); -- 2.45.2