1 /////////////////////////////////////////////////////////////////////////////
3 // Purpose: interface of wxLogWindow
4 // Author: wxWidgets team
6 // Licence: wxWindows license
7 /////////////////////////////////////////////////////////////////////////////
11 Different standard log levels (you may also define your own) used with
12 by standard wxLog functions wxLogError(), wxLogWarning(), etc...
16 wxLOG_FatalError
, //!< program can't continue, abort immediately
17 wxLOG_Error
, //!< a serious error, user must be informed about it
18 wxLOG_Warning
, //!< user is normally informed about it but may be ignored
19 wxLOG_Message
, //!< normal message (i.e. normal output of a non GUI app)
20 wxLOG_Status
, //!< informational: might go to the status line of GUI app
21 wxLOG_Info
, //!< informational message (a.k.a. 'Verbose')
22 wxLOG_Debug
, //!< never shown to the user, disabled in release mode
23 wxLOG_Trace
, //!< trace messages are also only enabled in debug mode
24 wxLOG_Progress
, //!< used for progress indicator (not yet)
25 wxLOG_User
= 100, //!< user defined levels start here
30 The type used to specify a log level.
32 Default values of ::wxLogLevel used by wxWidgets are contained in the
33 ::wxLogLevelValues enumeration.
35 typedef unsigned long wxLogLevel
;
38 Information about a log record (unit of the log output).
43 /// The name of the file where this log message was generated.
46 /// The line number at which this log message was generated.
50 The name of the function where the log record was generated.
52 This field may be @NULL if the compiler doesn't support @c __FUNCTION__
53 (but most modern compilers do).
57 /// Time when the log message was generated.
61 Id of the thread in which the message was generated.
63 This field is only available if wxWidgets was built with threads
64 support (<code>wxUSE_THREADS == 1</code>).
66 @see wxThread::GetCurrentId()
68 wxThreadIdType threadId
;
74 This class represents a background log window: to be precise, it collects all
75 log messages in the log frame which it manages but also passes them on to the
76 log target which was active at the moment of its creation. This allows you, for
77 example, to show all the log messages in a frame but still continue to process
78 them normally by showing the standard log dialog.
85 class wxLogWindow
: public wxLogInterposer
89 Creates the log frame window and starts collecting the messages in it.
92 The parent window for the log frame, may be @NULL
94 The title for the log frame
96 @true to show the frame initially (default), otherwise
97 Show() must be called later.
99 @true to process the log messages normally in addition to
100 logging them in the log frame (default), @false to only log them in the
103 wxLogWindow(wxWindow
* pParent
, const wxString
& szTitle
, bool show
= true,
104 bool passToOld
= true);
107 Returns the associated log frame window. This may be used to position or resize
108 it but use Show() to show or hide it.
110 wxFrame
* GetFrame() const;
113 Called if the user closes the window interactively, will not be
114 called if it is destroyed for another reason (such as when program
117 Return @true from here to allow the frame to close, @false to
118 prevent this from happening.
122 virtual bool OnFrameClose(wxFrame
* frame
);
125 Called immediately after the log frame creation allowing for
126 any extra initializations.
128 virtual void OnFrameCreate(wxFrame
* frame
);
131 Called right before the log frame is going to be deleted: will
132 always be called unlike OnFrameClose().
134 virtual void OnFrameDelete(wxFrame
* frame
);
137 Shows or hides the frame.
139 void Show(bool show
= true);
145 @class wxLogInterposerTemp
147 A special version of wxLogChain which uses itself as the new log target.
148 It forwards log messages to the previously installed one in addition to
149 processing them itself. Unlike wxLogInterposer, it doesn't delete the old
150 target which means it can be used to temporarily redirect log output.
152 As per wxLogInterposer, this class must be derived from to implement
153 wxLog::DoLog and/or wxLog::DoLogString methods.
158 class wxLogInterposerTemp
: public wxLogChain
162 The default constructor installs this object as the current active log target.
164 wxLogInterposerTemp();
172 This simple class allows you to chain log sinks, that is to install a new sink but
173 keep passing log messages to the old one instead of replacing it completely as
174 wxLog::SetActiveTarget does.
176 It is especially useful when you want to divert the logs somewhere (for
177 example to a file or a log window) but also keep showing the error messages
178 using the standard dialogs as wxLogGui does by default.
183 wxLogChain *logChain = new wxLogChain(new wxLogStderr);
185 // all the log messages are sent to stderr and also processed as usually
188 // don't delete logChain directly as this would leave a dangling
189 // pointer as active log target, use SetActiveTarget() instead
190 delete wxLog::SetActiveTarget(...something else or NULL...);
196 class wxLogChain
: public wxLog
200 Sets the specified @c logger (which may be @NULL) as the default log
201 target but the log messages are also passed to the previous log target if any.
203 wxLogChain(wxLog
* logger
);
206 Destroys the previous log target.
208 virtual ~wxLogChain();
211 Detaches the old log target so it won't be destroyed when the wxLogChain object
217 Returns the pointer to the previously active log target (which may be @NULL).
219 wxLog
* GetOldLog() const;
222 Returns @true if the messages are passed to the previously active log
223 target (default) or @false if PassMessages() had been called.
225 bool IsPassingMessages() const;
228 By default, the log messages are passed to the previously active log target.
229 Calling this function with @false parameter disables this behaviour
230 (presumably temporarily, as you shouldn't use wxLogChain at all otherwise) and
231 it can be reenabled by calling it again with @a passMessages set to @true.
233 void PassMessages(bool passMessages
);
236 Sets another log target to use (may be @NULL).
238 The log target specified in the wxLogChain(wxLog*) constructor or in a
239 previous call to this function is deleted.
240 This doesn't change the old log target value (the one the messages are
241 forwarded to) which still remains the same as was active when wxLogChain
244 void SetLog(wxLog
* logger
);
252 This is the default log target for the GUI wxWidgets applications.
254 Please see @ref overview_log_customize for explanation of how to change the
257 An object of this class is used by default to show the log messages created
258 by using wxLogMessage(), wxLogError() and other logging functions. It
259 doesn't display the messages logged by them immediately however but
260 accumulates all messages logged during an event handler execution and then
261 shows them all at once when its Flush() method is called during the idle
262 time processing. This has the important advantage of showing only a single
263 dialog to the user even if several messages were logged because of a single
264 error as it often happens (e.g. a low level function could log a message
265 because it failed to open a file resulting in its caller logging another
266 message due to the failure of higher level operation requiring the use of
267 this file). If you need to force the display of all previously logged
268 messages immediately you can use wxLog::FlushActive() to force the dialog
271 Also notice that if an error message is logged when several informative
272 messages had been already logged before, the informative messages are
273 discarded on the assumption that they are not useful -- and may be
274 confusing and hence harmful -- any more after the error. The warning
275 and error messages are never discarded however and any informational
276 messages logged after the first error one are also kept (as they may
277 contain information about the error recovery). You may override DoLog()
278 method to change this behaviour.
280 At any rate, it is possible that that several messages were accumulated
281 before this class Flush() method is called. If this is the case, Flush()
282 uses a custom dialog which shows the last message directly and allows the
283 user to view the previously logged ones by expanding the "Details"
284 wxCollapsiblePane inside it. This custom dialog also provides the buttons
285 for copying the log messages to the clipboard and saving them to a file.
287 However if only a single message is present when Flush() is called, just a
288 wxMessageBox() is used to show it. This has the advantage of being closer
289 to the native behaviour but it doesn't give the user any possibility to
290 copy or save the message (except for the recent Windows versions where @c
291 Ctrl-C may be pressed in the message box to copy its contents to the
292 clipboard) so you may want to override DoShowSingleMessage() to customize
293 wxLogGui -- the dialogs sample shows how to do this.
298 class wxLogGui
: public wxLog
307 Presents the accumulated log messages, if any, to the user.
309 This method is called during the idle time and should show any messages
310 accumulated in wxLogGui#m_aMessages field to the user.
312 virtual void Flush();
316 Returns the appropriate title for the dialog.
318 The title is constructed from wxApp::GetAppDisplayName() and the
319 severity string (e.g. "error" or "warning") appropriate for the current
320 wxLogGui#m_bErrors and wxLogGui#m_bWarnings values.
322 wxString
GetTitle() const;
325 Returns wxICON_ERROR, wxICON_WARNING or wxICON_INFORMATION depending on
326 the current maximal severity.
328 This value is suitable to be used in the style parameter of
329 wxMessageBox() function.
331 int GetSeverityIcon() const;
334 Forgets all the currently stored messages.
336 If you override Flush() (and don't call the base class version), you
337 must call this method to avoid messages being logged over and over
344 Method called by Flush() to show a single log message.
346 This function can be overridden to show the message in a different way.
347 By default a simple wxMessageBox() call is used.
350 The message to show (it can contain multiple lines).
352 The suggested title for the dialog showing the message, see
355 One of @c wxICON_XXX constants, see GetSeverityIcon().
357 virtual void DoShowSingleLogMessage(const wxString
& message
,
358 const wxString
& title
,
362 Method called by Flush() to show multiple log messages.
364 This function can be overridden to show the messages in a different way.
365 By default a special log dialog showing the most recent message and
366 allowing the user to expand it to view the previously logged ones is
370 Array of messages to show; it contains more than one element.
372 Array of message severities containing @c wxLOG_XXX values.
374 Array of time_t values indicating when each message was logged.
376 The suggested title for the dialog showing the message, see
379 One of @c wxICON_XXX constants, see GetSeverityIcon().
381 virtual void DoShowMultipleLogMessages(const wxArrayString
& messages
,
382 const wxArrayInt
& severities
,
383 const wxArrayLong
& times
,
384 const wxString
& title
,
389 All currently accumulated messages.
391 This array may be empty if no messages were logged.
393 @see m_aSeverity, m_aTimes
395 wxArrayString m_aMessages
;
398 The severities of each logged message.
400 This array is synchronized with wxLogGui#m_aMessages, i.e. the n-th
401 element of this array corresponds to the severity of the n-th message.
402 The possible severity values are @c wxLOG_XXX constants, e.g.
403 wxLOG_Error, wxLOG_Warning, wxLOG_Message etc.
405 wxArrayInt m_aSeverity
;
408 The time stamps of each logged message.
410 The elements of this array are time_t values corresponding to the time
411 when the message was logged.
413 wxArrayLong m_aTimes
;
416 True if there any error messages.
421 True if there any warning messages.
423 If both wxLogGui#m_bErrors and this member are false, there are only
424 informational messages to be shown.
429 True if there any messages to be shown to the user.
431 This variable is used instead of simply checking whether
432 wxLogGui#m_aMessages array is empty to allow blocking further calls to
433 Flush() while a log dialog is already being shown, even if the messages
434 array hasn't been emptied yet.
444 This class can be used to redirect the log messages to a C++ stream.
446 Please note that this class is only available if wxWidgets was compiled with
447 the standard iostream library support (@c wxUSE_STD_IOSTREAM must be on).
452 @see wxLogStderr, wxStreamToTextRedirector
454 class wxLogStream
: public wxLog
458 Constructs a log target which sends all the log messages to the given
459 output stream. If it is @NULL, the messages are sent to @c cerr.
461 wxLogStream(std
::ostream
*ostr
= NULL
);
469 This class can be used to redirect the log messages to a C file stream (not to
470 be confused with C++ streams).
472 It is the default log target for the non-GUI wxWidgets applications which
473 send all the output to @c stderr.
480 class wxLogStderr
: public wxLog
484 Constructs a log target which sends all the log messages to the given
485 @c FILE. If it is @NULL, the messages are sent to @c stderr.
487 wxLogStderr(FILE* fp
= NULL
);
495 wxLogBuffer is a very simple implementation of log sink which simply collects
496 all the logged messages in a string (except the debug messages which are output
497 in the usual way immediately as we're presumably not interested in collecting
498 them for later). The messages from different log function calls are separated
501 All the messages collected so far can be shown to the user (and the current
502 buffer cleared) by calling the overloaded wxLogBuffer::Flush method.
507 class wxLogBuffer
: public wxLog
511 The default ctor does nothing.
516 Shows all the messages collected so far to the user (using a message box in the
517 GUI applications or by printing them out to the console in text mode) and
518 clears the internal buffer.
520 virtual void Flush();
523 Returns the current buffer contains. Messages from different log function calls
524 are separated with the new lines in the buffer.
525 The buffer can be cleared by Flush() which will also show the current
526 contents to the user.
528 const wxString
& GetBuffer() const;
534 @class wxLogInterposer
536 A special version of wxLogChain which uses itself as the new log target.
537 It forwards log messages to the previously installed one in addition to
538 processing them itself.
540 Unlike wxLogChain which is usually used directly as is, this class must be
541 derived from to implement wxLog::DoLog and/or wxLog::DoLogString methods.
543 wxLogInterposer destroys the previous log target in its destructor.
544 If you don't want this to happen, use wxLogInterposerTemp instead.
549 class wxLogInterposer
: public wxLogChain
553 The default constructor installs this object as the current active log target.
563 Using these target all the log messages can be redirected to a text control.
564 The text control must have been created with @c wxTE_MULTILINE style by the
570 @see wxTextCtrl, wxStreamToTextRedirector
572 class wxLogTextCtrl
: public wxLog
576 Constructs a log target which sends all the log messages to the given text
577 control. The @a textctrl parameter cannot be @NULL.
579 wxLogTextCtrl(wxTextCtrl
* pTextCtrl
);
587 wxLog class defines the interface for the @e log targets used by wxWidgets
588 logging functions as explained in the @ref overview_log.
589 The only situations when you need to directly use this class is when you want
590 to derive your own log target because the existing ones don't satisfy your
591 needs. Another case is if you wish to customize the behaviour of the standard
592 logging classes (all of which respect the wxLog settings): for example, set
593 which trace messages are logged and which are not or change (or even remove
594 completely) the timestamp on the messages.
596 Otherwise, it is completely hidden behind the @e wxLogXXX() functions and
597 you may not even know about its existence.
599 @note For console-mode applications, the default target is wxLogStderr, so
600 that all @e wxLogXXX() functions print on @c stderr when @c wxUSE_GUI = 0.
603 @section log_derivingyours Deriving your own log target
605 There are several methods which may be overridden in the derived class to
606 customize log messages handling: DoLogRecord(), DoLogTextAtLevel() and
609 The last method is the simplest one: you should override it if you simply
610 want to redirect the log output elsewhere, without taking into account the
611 level of the message. If you do want to handle messages of different levels
612 differently, then you should override DoLogTextAtLevel().
614 Finally, if more control over the output format is needed, then the first
615 function must be overridden as it allows to construct custom messages
616 depending on the log level or even do completely different things depending
617 on the message severity (for example, throw away all messages except
618 warnings and errors, show warnings on the screen and forward the error
619 messages to the user's (or programmer's) cell phone -- maybe depending on
620 whether the timestamp tells us if it is day or night in the current time
623 There also functions to support message buffering. Why are they needed?
624 Some of wxLog implementations, most notably the standard wxLogGui class,
625 buffer the messages (for example, to avoid showing the user a zillion of modal
626 message boxes one after another -- which would be really annoying).
628 Flush() shows them all and clears the buffer contents.
629 This function doesn't do anything if the buffer is already empty.
634 @section log_tracemasks Using trace masks
636 The functions below allow some limited customization of wxLog behaviour
637 without writing a new log target class (which, aside from being a matter of
638 several minutes, allows you to do anything you want).
639 The verbose messages are the trace messages which are not disabled in the
640 release mode and are generated by wxLogVerbose().
641 They are not normally shown to the user because they present little interest,
642 but may be activated, for example, in order to help the user find some program
645 As for the (real) trace messages, their handling depends on the currently
646 enabled trace masks: if AddTraceMask() was called for the mask of the given
647 message, it will be logged, otherwise nothing happens.
651 wxLogTrace( wxTRACE_OleCalls, "IFoo::Bar() called" );
654 will log the message if it was preceded by:
657 wxLog::AddTraceMask( wxTRACE_OleCalls);
660 The standard trace masks are given in wxLogTrace() documentation.
662 Finally, the @e wxLog::DoLog() function automatically prepends a time stamp
663 to all the messages. The format of the time stamp may be changed: it can be
664 any string with % specifications fully described in the documentation of the
665 standard @e strftime() function. For example, the default format is
666 "[%d/%b/%y %H:%M:%S] " which gives something like "[17/Sep/98 22:10:16] "
667 (without quotes) for the current date. Setting an empty string as the time
668 format or calling the shortcut wxLog::DisableTimestamp(), disables timestamping
669 of the messages completely.
673 @li RemoveTraceMask()
674 @li ClearTraceMasks()
676 @li IsAllowedTraceMask()
683 @li SetRepetitionCounting()
684 @li GetRepetitionCounting()
687 Timestamping is disabled for Visual C++ users in debug builds by
688 default because otherwise it would be impossible to directly go to the line
689 from which the log message was generated by simply clicking in the debugger
690 window on the corresponding error message. If you wish to enable it, please
691 use SetTimestamp() explicitly.
694 @section log_target Manipulating the log target
696 The functions in this section work with and manipulate the active log
699 Get/Set methods are used to install/query the current active target and,
700 finally, DontCreateOnDemand() disables the automatic creation of a standard
701 log target if none actually exists. It is only useful when the application
702 is terminating and shouldn't be used in other situations because it may
703 easily lead to a loss of messages.
706 @li GetActiveTarget()
707 @li SetActiveTarget()
708 @li DontCreateOnDemand()
716 @see @ref overview_log
722 Add the @a mask to the list of allowed masks for wxLogTrace().
724 @see RemoveTraceMask(), GetTraceMasks()
726 static void AddTraceMask(const wxString
& mask
);
729 Removes all trace masks previously set with AddTraceMask().
731 @see RemoveTraceMask()
733 static void ClearTraceMasks();
736 Instructs wxLog to not create new log targets on the fly if there is none
737 currently. (Almost) for internal use only: it is supposed to be called by the
738 application shutdown code.
740 Note that this function also calls ClearTraceMasks().
742 static void DontCreateOnDemand();
745 Globally enable or disable logging.
747 Calling this function with @false argument disables all log messages.
749 @see wxLogNull, IsEnabled()
752 The old state, i.e. @true if logging was previously enabled and
753 @false if it was disabled.
755 static bool EnableLogging(bool enable
= true);
758 Shows all the messages currently in buffer and clears it.
760 If the buffer is already empty, nothing happens.
762 It should only be called from the main application thread.
764 If you override this method in a derived class, call the base class
765 version first, before doing anything else, to ensure that any buffered
766 messages from the other threads are logged.
768 virtual void Flush();
771 Flushes the current log target if any, does nothing if there is none.
773 As Flush() itself, this method should only be called from the main
776 static void FlushActive();
779 Returns the pointer to the active log target (may be @NULL).
781 static wxLog
* GetActiveTarget();
784 Returns the current log level limit.
786 All messages at levels strictly greater than the value returned by this
787 function are not logged at all.
789 @see SetLogLevel(), IsLevelEnabled()
791 static wxLogLevel
GetLogLevel();
794 Returns whether the repetition counting mode is enabled.
796 static bool GetRepetitionCounting();
799 Returns the current timestamp format string.
801 static const wxString
& GetTimestamp();
805 Returns the current trace mask, see Customization() section for details.
807 static wxTraceMask
GetTraceMask();
810 Returns the currently allowed list of string trace masks.
814 static const wxArrayString
& GetTraceMasks();
817 Returns whether the verbose mode is currently active.
819 static bool GetVerbose();
822 Returns @true if the @a mask is one of allowed masks for wxLogTrace().
824 See also: AddTraceMask(), RemoveTraceMask()
826 static bool IsAllowedTraceMask(const wxString
& mask
);
829 Returns true if logging is enabled at all now.
831 @see IsLevelEnabled(), EnableLogging()
833 static bool IsEnabled();
836 Returns true if logging at this level is enabled.
838 This function only returns @true if logging is globally enabled and if
839 @a level is less than or equal to the maximal log level enabled for the
842 @see IsEnabled(), SetLogLevel(), GetLogLevel(), SetComponentLevel()
846 static bool IsLevelEnabled(wxLogLevel level
, wxString component
);
849 Remove the @a mask from the list of allowed masks for
854 static void RemoveTraceMask(const wxString
& mask
);
857 Resumes logging previously suspended by a call to Suspend().
858 All messages logged in the meanwhile will be flushed soon.
860 static void Resume();
863 Sets the specified log target as the active one.
865 Returns the pointer to the previous active log target (may be @NULL).
866 To suppress logging use a new instance of wxLogNull not @NULL. If the
867 active log target is set to @NULL a new default log target will be
868 created when logging occurs.
870 static wxLog
* SetActiveTarget(wxLog
* logtarget
);
873 Sets the log level for the given component.
875 For example, to disable all but error messages from wxWidgets network
878 wxLog::SetComponentLevel("wx/net", wxLOG_Error);
881 SetLogLevel() may be used to set the global log level.
884 Non-empty component name, possibly using slashes (@c /) to separate
885 it into several parts.
887 Maximal level of log messages from this component which will be
888 handled instead of being simply discarded.
892 static void SetComponentLevel(const wxString
& component
, wxLogLevel level
);
895 Specifies that log messages with level greater (numerically) than
896 @a logLevel should be ignored and not sent to the active log target.
898 @see SetComponentLevel()
900 static void SetLogLevel(wxLogLevel logLevel
);
903 Enables logging mode in which a log message is logged once, and in case exactly
904 the same message successively repeats one or more times, only the number of
905 repetitions is logged.
907 static void SetRepetitionCounting(bool repetCounting
= true);
910 Sets the timestamp format prepended by the default log targets to all
911 messages. The string may contain any normal characters as well as %
912 prefixed format specificators, see @e strftime() manual for details.
913 Passing an empty string to this function disables message time stamping.
915 static void SetTimestamp(const wxString
& format
);
918 Disables time stamping of the log messages.
922 static void DisableTimestamp();
926 Sets the trace mask, see @ref log_tracemasks section for details.
928 static void SetTraceMask(wxTraceMask mask
);
931 Activates or deactivates verbose mode in which the verbose messages are
932 logged as the normal ones instead of being silently dropped.
934 static void SetVerbose(bool verbose
= true);
937 Suspends the logging until Resume() is called.
939 Note that the latter must be called the same number of times as the former
940 to undo it, i.e. if you call Suspend() twice you must call Resume() twice as well.
942 Note that suspending the logging means that the log sink won't be be flushed
943 periodically, it doesn't have any effect if the current log target does the
944 logging immediately without waiting for Flush() to be called (the standard
945 GUI log target only shows the log dialog when it is flushed, so Suspend()
946 works as expected with it).
948 @see Resume(), wxLogNull
950 static void Suspend();
953 Log the given record.
955 This function should only be called from the DoLog() implementations in
956 the derived classes if they need to call DoLogRecord() on another log
957 object (they can, of course, just use wxLog::DoLogRecord() call syntax
958 to call it on the object itself). It should not be used for logging new
959 messages which can be only sent to the currently active logger using
960 OnLog() which also checks if the logging (for this level) is enabled
961 while this method just directly calls DoLog().
963 Example of use of this class from wxLogChain:
965 void wxLogChain::DoLogRecord(wxLogLevel level,
967 const wxLogRecordInfo& info)
969 // let the previous logger show it
970 if ( m_logOld && IsPassingMessages() )
971 m_logOld->LogRecord(level, msg, info);
973 // and also send it to the new one
974 if ( m_logNew && m_logNew != this )
975 m_logNew->LogRecord(level, msg, info);
981 void LogRecord(wxLogLevel level
, const wxString
& msg
, time_t timestamp
);
985 @name Logging callbacks.
987 The functions which should be overridden by custom log targets.
989 When defining a new log target, you have a choice between overriding
990 DoLogRecord(), which provides maximal flexibility, DoLogTextAtLevel()
991 which can be used if you don't intend to change the default log
992 messages formatting but want to handle log messages of different levels
993 differently or, in the simplest case, DoLogText().
998 Called to created log a new record.
1000 Any log message created by wxLogXXX() functions is passed to this
1001 method of the active log target. The default implementation prepends
1002 the timestamp and, for some log levels (e.g. error and warning), the
1003 corresponding prefix to @a msg and passes it to DoLogTextAtLevel().
1005 You may override this method to implement custom formatting of the
1006 log messages or to implement custom filtering of log messages (e.g. you
1007 could discard all log messages coming from the given source file).
1009 virtual void DoLogRecord(wxLogLevel level
,
1010 const wxString
& msg
,
1011 const wxLogRecordInfo
& info
);
1014 Called to log the specified string at given level.
1016 The base class versions logs debug and trace messages on the system
1017 default debug output channel and passes all the other messages to
1020 virtual void DoLogTextAtLevel(wxLogLevel level
, const wxString
& msg
);
1023 Called to log the specified string.
1025 A simple implementation might just send the string to @c stdout or
1026 @c stderr or save it in a file (of course, the already existing
1027 wxLogStderr can be used for this).
1029 The base class version of this function asserts so it must be
1030 overridden if you don't override DoLogRecord() or DoLogTextAtLevel().
1032 virtual void DoLogText(const wxString
& msg
);
1042 This class allows you to temporarily suspend logging. All calls to the log
1043 functions during the life time of an object of this class are just ignored.
1045 In particular, it can be used to suppress the log messages given by wxWidgets
1046 itself but it should be noted that it is rarely the best way to cope with this
1047 problem as @b all log messages are suppressed, even if they indicate a
1048 completely different error than the one the programmer wanted to suppress.
1050 For instance, the example of the overview:
1055 // wxFile.Open() normally complains if file can't be opened, we don't want it
1058 if ( !file.Open("bar") )
1059 ... process error ourselves ...
1060 } // ~wxLogNull called, old log sink restored
1062 wxLogMessage("..."); // ok
1065 would be better written as:
1070 // don't try to open file if it doesn't exist, we are prepared to deal with
1071 // this ourselves - but all other errors are not expected
1072 if ( wxFile::Exists("bar") )
1074 // gives an error message if the file couldn't be opened
1103 // ============================================================================
1104 // Global functions/macros
1105 // ============================================================================
1107 /** @addtogroup group_funcmacro_log */
1111 This function shows a message to the user in a safe way and should be safe
1112 to call even before the application has been initialized or if it is
1113 currently in some other strange state (for example, about to crash). Under
1114 Windows this function shows a message box using a native dialog instead of
1115 wxMessageBox() (which might be unsafe to call), elsewhere it simply prints
1116 the message to the standard output using the title as prefix.
1119 The title of the message box shown to the user or the prefix of the
1122 The text to show to the user.
1124 @see wxLogFatalError()
1128 void wxSafeShowMessage(const wxString
& title
, const wxString
& text
);
1131 Returns the error code from the last system call. This function uses
1132 @c errno on Unix platforms and @c GetLastError under Win32.
1134 @see wxSysErrorMsg(), wxLogSysError()
1138 unsigned long wxSysErrorCode();
1141 Returns the error message corresponding to the given system error code. If
1142 @a errCode is 0 (default), the last error code (as returned by
1143 wxSysErrorCode()) is used.
1145 @see wxSysErrorCode(), wxLogSysError()
1149 const wxChar
* wxSysErrorMsg(unsigned long errCode
= 0);
1153 /** @addtogroup group_funcmacro_log */
1156 For all normal, informational messages. They also appear in a message box
1157 by default (but it can be changed).
1161 void wxLogMessage(const char* formatString
, ... );
1162 void wxVLogMessage(const char* formatString
, va_list argPtr
);
1165 /** @addtogroup group_funcmacro_log */
1168 For verbose output. Normally, it is suppressed, but might be activated if
1169 the user wishes to know more details about the program progress (another,
1170 but possibly confusing name for the same function could be @c wxLogInfo).
1174 void wxLogVerbose(const char* formatString
, ... );
1175 void wxVLogVerbose(const char* formatString
, va_list argPtr
);
1178 /** @addtogroup group_funcmacro_log */
1181 For warnings - they are also normally shown to the user, but don't
1182 interrupt the program work.
1186 void wxLogWarning(const char* formatString
, ... );
1187 void wxVLogWarning(const char* formatString
, va_list argPtr
);
1190 /** @addtogroup group_funcmacro_log */
1193 Like wxLogError(), but also terminates the program with the exit code 3.
1194 Using @e abort() standard function also terminates the program with this
1199 void wxLogFatalError(const char* formatString
, ... );
1200 void wxVLogFatalError(const char* formatString
, va_list argPtr
);
1203 /** @addtogroup group_funcmacro_log */
1206 The functions to use for error messages, i.e. the messages that must be
1207 shown to the user. The default processing is to pop up a message box to
1208 inform the user about it.
1212 void wxLogError(const char* formatString
, ... );
1213 void wxVLogError(const char* formatString
, va_list argPtr
);
1216 /** @addtogroup group_funcmacro_log */
1219 Like wxLogDebug(), trace functions only do something in debug builds and
1220 expand to nothing in the release one. The reason for making it a separate
1221 function is that usually there are a lot of trace messages, so it might
1222 make sense to separate them from other debug messages.
1224 wxLogTrace(const char*,const char*,...) and can be used instead of
1225 wxLogDebug() if you would like to be able to separate trace messages into
1226 different categories which can be enabled or disabled with
1227 wxLog::AddTraceMask() and wxLog::RemoveTraceMask().
1231 void wxLogTrace(const char *mask
, const char* formatString
, ... );
1232 void wxVLogTrace(const char *mask
, const char* formatString
, va_list argPtr
);
1235 /** @addtogroup group_funcmacro_log */
1238 Like wxLogDebug(), trace functions only do something in debug builds and
1239 expand to nothing in the release one. The reason for making it a separate
1240 function is that usually there are a lot of trace messages, so it might
1241 make sense to separate them from other debug messages.
1243 In this version of wxLogTrace(), trace messages can be separated into
1244 different categories and calls using this function only log the message if
1245 the given @a mask is currently enabled in wxLog. This lets you selectively
1246 trace only some operations and not others by enabling the desired trace
1247 masks with wxLog::AddTraceMask() or by setting the
1248 @ref overview_envvars "@c WXTRACE environment variable".
1250 The predefined string trace masks used by wxWidgets are:
1253 @itemdef{ wxTRACE_MemAlloc, Trace memory allocation (new/delete) }
1254 @itemdef{ wxTRACE_Messages, Trace window messages/X callbacks }
1255 @itemdef{ wxTRACE_ResAlloc, Trace GDI resource allocation }
1256 @itemdef{ wxTRACE_RefCount, Trace various ref counting operations }
1257 @itemdef{ wxTRACE_OleCalls, Trace OLE method calls (Win32 only) }
1260 @note Since both the mask and the format string are strings, this might
1261 lead to function signature confusion in some cases: if you intend to
1262 call the format string only version of wxLogTrace(), add a "%s"
1263 format string parameter and then supply a second string parameter for
1264 that "%s", the string mask version of wxLogTrace() will erroneously
1265 get called instead, since you are supplying two string parameters to
1266 the function. In this case you'll unfortunately have to avoid having
1267 two leading string parameters, e.g. by adding a bogus integer (with
1268 its "%d" format string).
1272 void wxLogTrace(const char* mask
, const char* formatString
, ... );
1273 void wxVLogTrace(const char* mask
,
1274 const char* formatString
,
1278 /** @addtogroup group_funcmacro_log */
1281 Like wxLogDebug(), trace functions only do something in debug builds and
1282 expand to nothing in the release one. The reason for making it a separate
1283 function is that usually there are a lot of trace messages, so it might
1284 make sense to separate them from other debug messages.
1287 This version of wxLogTrace() only logs the message if all the bits
1288 corresponding to the @a mask are set in the wxLog trace mask which can be
1289 set by calling wxLog::SetTraceMask(). This version is less flexible than
1290 wxLogTrace(const char*,const char*,...) because it doesn't allow defining
1291 the user trace masks easily. This is why it is deprecated in favour of
1292 using string trace masks.
1294 The following bitmasks are defined for wxTraceMask:
1297 @itemdef{ wxTraceMemAlloc, Trace memory allocation (new/delete) }
1298 @itemdef{ wxTraceMessages, Trace window messages/X callbacks }
1299 @itemdef{ wxTraceResAlloc, Trace GDI resource allocation }
1300 @itemdef{ wxTraceRefCount, Trace various ref counting operations }
1301 @itemdef{ wxTraceOleCalls, Trace OLE method calls (Win32 only) }
1306 void wxLogTrace(wxTraceMask mask
, const char* formatString
, ... );
1307 void wxVLogTrace(wxTraceMask mask
, const char* formatString
, va_list argPtr
);
1310 /** @addtogroup group_funcmacro_log */
1313 The right functions for debug output. They only do something in debug mode
1314 (when the preprocessor symbol @c __WXDEBUG__ is defined) and expand to
1315 nothing in release mode (otherwise).
1319 void wxLogDebug(const char* formatString
, ... );
1320 void wxVLogDebug(const char* formatString
, va_list argPtr
);
1323 /** @addtogroup group_funcmacro_log */
1326 Messages logged by this function will appear in the statusbar of the
1327 @a frame or of the top level application window by default (i.e. when using
1328 the second version of the functions).
1330 If the target frame doesn't have a statusbar, the message will be lost.
1334 void wxLogStatus(wxFrame
* frame
, const char* formatString
, ... );
1335 void wxVLogStatus(wxFrame
* frame
, const char* formatString
, va_list argPtr
);
1336 void wxLogStatus(const char* formatString
, ... );
1337 void wxVLogStatus(const char* formatString
, va_list argPtr
);
1340 /** @addtogroup group_funcmacro_log */
1343 Mostly used by wxWidgets itself, but might be handy for logging errors
1344 after system call (API function) failure. It logs the specified message
1345 text as well as the last system error code (@e errno or @e ::GetLastError()
1346 depending on the platform) and the corresponding error message. The second
1347 form of this function takes the error code explicitly as the first
1350 @see wxSysErrorCode(), wxSysErrorMsg()
1354 void wxLogSysError(const char* formatString
, ... );
1355 void wxVLogSysError(const char* formatString
, va_list argPtr
);