X-Git-Url: https://git.saurik.com/wxWidgets.git/blobdiff_plain/ae3c17b4013e80b99976c750c19fca47729517f6..704ceca8d2cd8da51a5cc22f8c51fd61c762dbf5:/interface/wx/log.h?ds=sidebyside diff --git a/interface/wx/log.h b/interface/wx/log.h index bb96ae2926..b4eb85f3c9 100644 --- a/interface/wx/log.h +++ b/interface/wx/log.h @@ -8,7 +8,6 @@ /** @class wxLogWindow - @wxheader{log.h} 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 @@ -81,7 +80,6 @@ public: /** @class wxLogInterposerTemp - @wxheader{log.h} A special version of wxLogChain which uses itself as the new log target. It forwards log messages to the previously installed one in @@ -109,7 +107,6 @@ public: /** @class wxLogChain - @wxheader{log.h} 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 @@ -129,7 +126,7 @@ public: // 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...); + delete wxLog::SetActiveTarget(...something else or NULL...); @endcode @library{wxbase} @@ -147,7 +144,7 @@ public: /** Destroys the previous log target. */ - ~wxLogChain(); + virtual ~wxLogChain(); /** Detaches the old log target so it won't be destroyed when the wxLogChain object @@ -190,13 +187,51 @@ public: /** @class wxLogGui - @wxheader{log.h} - 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 @@ -206,13 +241,144 @@ 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; }; /** @class wxLogStream - @wxheader{log.h} This class can be used to redirect the log messages to a C++ stream. @@ -238,7 +404,6 @@ public: /** @class wxLogStderr - @wxheader{log.h} 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 @@ -263,7 +428,6 @@ public: /** @class wxLogBuffer - @wxheader{log.h} 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 @@ -301,7 +465,6 @@ public: /** @class wxLogInterposer - @wxheader{log.h} A special version of wxLogChain which uses itself as the new log target. It forwards log messages to the previously installed one in @@ -330,7 +493,6 @@ public: /** @class wxLogTextCtrl - @wxheader{log.h} 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 @@ -355,7 +517,6 @@ public: /** @class wxLog - @wxheader{log.h} wxLog class defines the interface for the @e log targets used by wxWidgets logging functions as explained in the @ref overview_log. @@ -504,14 +665,11 @@ public: */ static void ClearTraceMasks(); - */ - - /** Disables time stamping of the log messages. This function is new since wxWidgets version 2.9 */ - void SetTimestamp(const wxString& format); + static void SetTimestamp(const wxString& format); /** Called to process the message of the specified severity. @a msg is the text @@ -639,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); @@ -705,7 +864,6 @@ public: /** @class wxLogNull - @wxheader{log.h} 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.