X-Git-Url: https://git.saurik.com/wxWidgets.git/blobdiff_plain/1c17754879a49daf0f0e66b4a4bfd2cb5208098c..92c0fc34c104c8d7c12d6a3b78ea232690fc23f4:/interface/wx/log.h?ds=sidebyside diff --git a/interface/wx/log.h b/interface/wx/log.h index c440515b0e..7dbed9bc56 100644 --- a/interface/wx/log.h +++ b/interface/wx/log.h @@ -2,10 +2,10 @@ // Name: log.h // Purpose: interface of wxLog* classes // Author: wxWidgets team -// RCS-ID: $Id$ // Licence: wxWindows licence ///////////////////////////////////////////////////////////////////////////// +#if wxUSE_BASE /** Different standard log levels (you may also define your own) used with @@ -68,8 +68,6 @@ public: wxThreadIdType threadId; }; - - /** @class wxLogFormatter @@ -170,12 +168,12 @@ protected: wxLog class defines the interface for the 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. - Otherwise, it is completely hidden behind the @ref group_funcmacro_log "wxLogXXX() functions" + 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 @@ -184,7 +182,7 @@ protected: @library{wxbase} @category{logging} - @see @ref overview_log, @ref group_funcmacro_log "wxLogXXX() functions" + @see @ref overview_log, @ref group_funcmacro_log "wxLogXXX() functions" */ class wxLog { @@ -193,7 +191,7 @@ public: @name Trace mask functions */ //@{ - + /** Add the @a mask to the list of allowed masks for wxLogTrace(). @@ -229,7 +227,7 @@ public: @see AddTraceMask() */ static void RemoveTraceMask(const wxString& mask); - + //@} @@ -238,11 +236,11 @@ public: @name Log target functions */ //@{ - + /** Instructs wxLog to not create new log targets on the fly if there is none - currently (see GetActiveTarget()). - + 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). @@ -305,7 +303,7 @@ public: @since 2.9.1 */ static wxLog *SetThreadActiveTarget(wxLog *logger); - + /** Flushes the current log target if any, does nothing if there is none. @@ -316,7 +314,7 @@ public: 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. @@ -338,16 +336,16 @@ public: @see Resume(), wxLogNull */ static void Suspend(); - + //@} - + /** @name Log level functions */ //@{ - + /** Returns the current log level limit. @@ -357,7 +355,7 @@ public: @see SetLogLevel(), IsLevelEnabled() */ static wxLogLevel GetLogLevel(); - + /** Returns true if logging at this level is enabled for the current thread. @@ -400,7 +398,7 @@ public: @see SetComponentLevel() */ static void SetLogLevel(wxLogLevel logLevel); - + //@} @@ -409,7 +407,7 @@ public: @name Enable/disable features functions */ //@{ - + /** Globally enable or disable logging. @@ -430,7 +428,7 @@ public: @see IsLevelEnabled(), EnableLogging() */ static bool IsEnabled(); - + /** Returns whether the repetition counting mode is enabled. */ @@ -442,7 +440,7 @@ public: repetitions is logged. */ static void SetRepetitionCounting(bool repetCounting = true); - + /** Returns the current timestamp format string. @@ -473,7 +471,7 @@ public: @since 2.9.0 */ static void DisableTimestamp(); - + /** Returns whether the verbose mode is currently active. */ @@ -482,16 +480,16 @@ public: /** 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. @@ -505,7 +503,7 @@ public: @since 2.9.4 */ wxLogFormatter *SetFormatter(wxLogFormatter* formatter); - + /** Some of wxLog implementations, most notably the standard wxLogGui class, @@ -518,7 +516,7 @@ public: version first, before doing anything else. */ virtual void Flush(); - + /** Log the given record. @@ -686,6 +684,33 @@ public: +/** + @class wxLogInterposer + + 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 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: + /** + The default constructor installs this object as the current active log target. + */ + wxLogInterposer(); +}; + + + /** @class wxLogInterposerTemp @@ -710,7 +735,6 @@ public: }; - /** @class wxLogStream @@ -803,33 +827,6 @@ public: -/** - @class wxLogInterposer - - 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 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: - /** - The default constructor installs this object as the current active log target. - */ - wxLogInterposer(); -}; - - - /** @class wxLogNull @@ -892,6 +889,297 @@ public: ~wxLogNull(); }; +#endif // wxUSE_BASE + +#if wxUSE_GUI + +/** + @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 wxLogTextCtrl +*/ +class wxLogWindow : public wxLogInterposer +{ +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. + 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. + */ + wxLogWindow(wxWindow* pParent, const wxString& szTitle, bool show = true, + bool passToOld = true); + + /** + 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. + + @see OnFrameDelete() + */ + 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); + + /** + Shows or hides the frame. + */ + 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: + /** + 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(); + + + /** + 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; + +private: + /** + 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); +}; + + + +/** + @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{wxcore} + @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. + */ + wxLogTextCtrl(wxTextCtrl* pTextCtrl); +}; + + +#endif // wxUSE_GUI + +#if wxUSE_BASE // ============================================================================ @@ -1157,3 +1445,4 @@ void wxVLogSysError(const char* formatString, va_list argPtr); //@} +#endif // wxUSE_BASE