1 /////////////////////////////////////////////////////////////////////////////
3 // Purpose: Assorted wxLogXXX functions, and wxLog (sink for logs)
4 // Author: Vadim Zeitlin
8 // Copyright: (c) 1998 Vadim Zeitlin <zeitlin@dptmaths.ens-cachan.fr>
9 // Licence: wxWindows license
10 /////////////////////////////////////////////////////////////////////////////
15 #if defined(__GNUG__) && !defined(__APPLE__)
16 #pragma interface "log.h"
20 #include "wx/string.h"
22 // ----------------------------------------------------------------------------
23 // forward declarations
24 // ----------------------------------------------------------------------------
26 class WXDLLEXPORT wxTextCtrl
;
27 class WXDLLEXPORT wxLogFrame
;
28 class WXDLLEXPORT wxFrame
;
30 // ----------------------------------------------------------------------------
32 // ----------------------------------------------------------------------------
34 typedef unsigned long wxTraceMask
;
35 typedef unsigned long wxLogLevel
;
37 // ----------------------------------------------------------------------------
39 // ----------------------------------------------------------------------------
44 #include <time.h> // for time_t
47 #include "wx/dynarray.h"
49 #ifndef wxUSE_LOG_DEBUG
51 # define wxUSE_LOG_DEBUG 1
52 # else // !__WXDEBUG__
53 # define wxUSE_LOG_DEBUG 0
57 // ----------------------------------------------------------------------------
59 // ----------------------------------------------------------------------------
61 // different standard log levels (you may also define your own)
64 wxLOG_FatalError
, // program can't continue, abort immediately
65 wxLOG_Error
, // a serious error, user must be informed about it
66 wxLOG_Warning
, // user is normally informed about it but may be ignored
67 wxLOG_Message
, // normal message (i.e. normal output of a non GUI app)
68 wxLOG_Status
, // informational: might go to the status line of GUI app
69 wxLOG_Info
, // informational message (a.k.a. 'Verbose')
70 wxLOG_Debug
, // never shown to the user, disabled in release mode
71 wxLOG_Trace
, // trace messages are also only enabled in debug mode
72 wxLOG_Progress
, // used for progress indicator (not yet)
73 wxLOG_User
= 100, // user defined levels start here
77 // symbolic trace masks - wxLogTrace("foo", "some trace message...") will be
78 // discarded unless the string "foo" has been added to the list of allowed
79 // ones with AddTraceMask()
81 #define wxTRACE_MemAlloc wxT("memalloc") // trace memory allocation (new/delete)
82 #define wxTRACE_Messages wxT("messages") // trace window messages/X callbacks
83 #define wxTRACE_ResAlloc wxT("resalloc") // trace GDI resource allocation
84 #define wxTRACE_RefCount wxT("refcount") // trace various ref counting operations
87 #define wxTRACE_OleCalls wxT("ole") // OLE interface calls
90 // the trace masks have been superceded by symbolic trace constants, they're
91 // for compatibility only andwill be removed soon - do NOT use them
93 // meaning of different bits of the trace mask (which allows selectively
94 // enable/disable some trace messages)
95 #define wxTraceMemAlloc 0x0001 // trace memory allocation (new/delete)
96 #define wxTraceMessages 0x0002 // trace window messages/X callbacks
97 #define wxTraceResAlloc 0x0004 // trace GDI resource allocation
98 #define wxTraceRefCount 0x0008 // trace various ref counting operations
101 #define wxTraceOleCalls 0x0100 // OLE interface calls
104 #include "wx/ioswrap.h"
106 // ----------------------------------------------------------------------------
107 // derive from this class to redirect (or suppress, or ...) log messages
108 // normally, only a single instance of this class exists but it's not enforced
109 // ----------------------------------------------------------------------------
111 class WXDLLEXPORT wxLog
118 // Allow replacement of the fixed size static buffer with
119 // a user allocated one. Pass in NULL to restore the
120 // built in static buffer.
121 static wxChar
*SetLogBuffer( wxChar
*buf
, size_t size
= 0 );
123 // these functions allow to completely disable all log messages
124 // is logging disabled now?
125 static bool IsEnabled() { return ms_doLog
; }
126 // change the flag state, return the previous one
127 static bool EnableLogging(bool doIt
= TRUE
)
128 { bool doLogOld
= ms_doLog
; ms_doLog
= doIt
; return doLogOld
; }
130 // static sink function - see DoLog() for function to overload in the
132 static void OnLog(wxLogLevel level
, const wxChar
*szString
, time_t t
)
134 if ( IsEnabled() && ms_logLevel
>= level
) {
135 wxLog
*pLogger
= GetActiveTarget();
137 pLogger
->DoLog(level
, szString
, t
);
142 // flush shows all messages if they're not logged immediately (FILE
143 // and iostream logs don't need it, but wxGuiLog does to avoid showing
144 // 17 modal dialogs one after another)
145 virtual void Flush();
146 // call to Flush() may be optimized: call it only if this function
147 // returns true (although Flush() also returns immediately if there is
148 // no messages, this functions is more efficient because inline)
149 bool HasPendingMessages() const { return m_bHasMessages
; }
151 // only one sink is active at each moment
152 // flush the active target if any
153 static void FlushActive()
155 if ( !ms_suspendCount
)
157 wxLog
*log
= GetActiveTarget();
158 if ( log
&& log
->HasPendingMessages() )
162 // get current log target, will call wxApp::CreateLogTarget() to
163 // create one if none exists
164 static wxLog
*GetActiveTarget();
165 // change log target, pLogger may be NULL
166 static wxLog
*SetActiveTarget(wxLog
*pLogger
);
168 // suspend the message flushing of the main target until the next call
169 // to Resume() - this is mainly for internal use (to prevent wxYield()
170 // from flashing the messages)
171 static void Suspend() { ms_suspendCount
++; }
172 // must be called for each Suspend()!
173 static void Resume() { ms_suspendCount
--; }
175 // functions controlling the default wxLog behaviour
176 // verbose mode is activated by standard command-line '-verbose'
178 static void SetVerbose(bool bVerbose
= TRUE
) { ms_bVerbose
= bVerbose
; }
180 // Set log level. Log messages with level > logLevel will not be logged.
181 static void SetLogLevel(wxLogLevel logLevel
) { ms_logLevel
= logLevel
; }
183 // should GetActiveTarget() try to create a new log object if the
185 static void DontCreateOnDemand();
187 // trace mask (see wxTraceXXX constants for details)
188 static void SetTraceMask(wxTraceMask ulMask
) { ms_ulTraceMask
= ulMask
; }
189 // add string trace mask
190 static void AddTraceMask(const wxString
& str
) { ms_aTraceMasks
.Add(str
); }
191 // add string trace mask
192 static void RemoveTraceMask(const wxString
& str
);
193 // remove all string trace masks
194 static void ClearTraceMasks();
195 // get string trace masks
196 static const wxArrayString
&GetTraceMasks() { return ms_aTraceMasks
; }
198 // sets the timestamp string: this is used as strftime() format string
199 // for the log targets which add time stamps to the messages - set it
200 // to NULL to disable time stamping completely.
201 static void SetTimestamp(const wxChar
*ts
) { ms_timestamp
= ts
; }
205 // gets the verbose status
206 static bool GetVerbose() { return ms_bVerbose
; }
208 static wxTraceMask
GetTraceMask() { return ms_ulTraceMask
; }
209 // is this trace mask in the list?
210 static bool IsAllowedTraceMask(const wxChar
*mask
)
211 { return ms_aTraceMasks
.Index(mask
) != wxNOT_FOUND
; }
212 // return the current loglevel limit
213 static wxLogLevel
GetLogLevel() { return ms_logLevel
; }
215 // get the current timestamp format string (may be NULL)
216 static const wxChar
*GetTimestamp() { return ms_timestamp
; }
220 // put the time stamp into the string if ms_timestamp != NULL (don't
221 // change it otherwise)
222 static void TimeStamp(wxString
*str
);
224 // make dtor virtual for all derived classes
228 bool m_bHasMessages
; // any messages in the queue?
230 // the logging functions that can be overriden
231 // default DoLog() prepends the time stamp and a prefix corresponding
232 // to the message to szString and then passes it to DoLogString()
233 virtual void DoLog(wxLogLevel level
, const wxChar
*szString
, time_t t
);
234 // default DoLogString does nothing but is not pure virtual because if
235 // you override DoLog() you might not need it at all
236 virtual void DoLogString(const wxChar
*szString
, time_t t
);
242 static wxLog
*ms_pLogger
; // currently active log sink
243 static bool ms_doLog
; // FALSE => all logging disabled
244 static bool ms_bAutoCreate
; // create new log targets on demand?
245 static bool ms_bVerbose
; // FALSE => ignore LogInfo messages
247 static wxLogLevel ms_logLevel
; // limit logging to levels <= ms_logLevel
249 static size_t ms_suspendCount
; // if positive, logs are not flushed
251 // format string for strftime(), if NULL, time stamping log messages is
253 static const wxChar
*ms_timestamp
;
255 static wxTraceMask ms_ulTraceMask
; // controls wxLogTrace behaviour
256 static wxArrayString ms_aTraceMasks
; // more powerful filter for wxLogTrace
259 // ----------------------------------------------------------------------------
260 // "trivial" derivations of wxLog
261 // ----------------------------------------------------------------------------
263 // log everything to a "FILE *", stderr by default
264 class WXDLLEXPORT wxLogStderr
: public wxLog
266 DECLARE_NO_COPY_CLASS(wxLogStderr
)
269 // redirect log output to a FILE
270 wxLogStderr(FILE *fp
= (FILE *) NULL
);
273 // implement sink function
274 virtual void DoLogString(const wxChar
*szString
, time_t t
);
279 #if wxUSE_STD_IOSTREAM
281 // log everything to an "ostream", cerr by default
282 class WXDLLEXPORT wxLogStream
: public wxLog
285 // redirect log output to an ostream
286 wxLogStream(wxSTD ostream
*ostr
= (wxSTD ostream
*) NULL
);
289 // implement sink function
290 virtual void DoLogString(const wxChar
*szString
, time_t t
);
292 // using ptr here to avoid including <iostream.h> from this file
293 wxSTD ostream
*m_ostr
;
296 #endif // wxUSE_STD_IOSTREAM
298 // ----------------------------------------------------------------------------
299 // /dev/null log target: suppress logging until this object goes out of scope
300 // ----------------------------------------------------------------------------
308 // wxFile.Open() normally complains if file can't be opened, we don't
312 if ( !file.Open("bar") )
313 ... process error ourselves ...
315 // ~wxLogNull called, old log sink restored
318 class WXDLLEXPORT wxLogNull
321 wxLogNull() : m_flagOld(wxLog::EnableLogging(FALSE
)) { }
322 ~wxLogNull() { (void)wxLog::EnableLogging(m_flagOld
); }
325 bool m_flagOld
; // the previous value of the wxLog::ms_doLog
328 // ----------------------------------------------------------------------------
329 // chaining log target: installs itself as a log target and passes all
330 // messages to the real log target given to it in the ctor but also forwards
331 // them to the previously active one
333 // note that you don't have to call SetActiveTarget() with this class, it
334 // does it itself in its ctor
335 // ----------------------------------------------------------------------------
337 class WXDLLEXPORT wxLogChain
: public wxLog
340 wxLogChain(wxLog
*logger
);
341 virtual ~wxLogChain();
343 // change the new log target
344 void SetLog(wxLog
*logger
);
346 // this can be used to temporarily disable (and then reenable) passing
347 // messages to the old logger (by default we do pass them)
348 void PassMessages(bool bDoPass
) { m_bPassMessages
= bDoPass
; }
350 // are we passing the messages to the previous log target?
351 bool IsPassingMessages() const { return m_bPassMessages
; }
353 // return the previous log target (may be NULL)
354 wxLog
*GetOldLog() const { return m_logOld
; }
356 // override base class version to flush the old logger as well
357 virtual void Flush();
360 // pass the chain to the old logger if needed
361 virtual void DoLog(wxLogLevel level
, const wxChar
*szString
, time_t t
);
364 // the current log target
367 // the previous log target
370 // do we pass the messages to the old logger?
371 bool m_bPassMessages
;
373 DECLARE_NO_COPY_CLASS(wxLogChain
)
376 // a chain log target which uses itself as the new logger
377 class WXDLLEXPORT wxLogPassThrough
: public wxLogChain
383 // ----------------------------------------------------------------------------
384 // the following log targets are only compiled in if the we're compiling the
385 // GUI part (andnot just the base one) of the library, they're implemented in
386 // src/generic/logg.cpp *and not src/common/log.cpp unlike all the rest)
387 // ----------------------------------------------------------------------------
393 // log everything to a text window (GUI only of course)
394 class WXDLLEXPORT wxLogTextCtrl
: public wxLog
397 wxLogTextCtrl(wxTextCtrl
*pTextCtrl
);
400 // implement sink function
401 virtual void DoLogString(const wxChar
*szString
, time_t t
);
403 // the control we use
404 wxTextCtrl
*m_pTextCtrl
;
406 DECLARE_NO_COPY_CLASS(wxLogTextCtrl
)
409 #endif // wxUSE_TEXTCTRL
411 // ----------------------------------------------------------------------------
412 // GUI log target, the default one for wxWindows programs
413 // ----------------------------------------------------------------------------
417 class WXDLLEXPORT wxLogGui
: public wxLog
423 // show all messages that were logged since the last Flush()
424 virtual void Flush();
427 virtual void DoLog(wxLogLevel level
, const wxChar
*szString
, time_t t
);
432 wxArrayString m_aMessages
; // the log message texts
433 wxArrayInt m_aSeverity
; // one of wxLOG_XXX values
434 wxArrayLong m_aTimes
; // the time of each message
435 bool m_bErrors
, // do we have any errors?
436 m_bWarnings
; // any warnings?
439 #endif // wxUSE_LOGGUI
441 // ----------------------------------------------------------------------------
442 // (background) log window: this class forwards all log messages to the log
443 // target which was active when it was instantiated, but also collects them
444 // to the log window. This window has it's own menu which allows the user to
445 // close it, clear the log contents or save it to the file.
446 // ----------------------------------------------------------------------------
450 class WXDLLEXPORT wxLogWindow
: public wxLogPassThrough
453 wxLogWindow(wxFrame
*pParent
, // the parent frame (can be NULL)
454 const wxChar
*szTitle
, // the title of the frame
455 bool bShow
= TRUE
, // show window immediately?
456 bool bPassToOld
= TRUE
); // pass messages to the old target?
461 // show/hide the log window
462 void Show(bool bShow
= TRUE
);
463 // retrieve the pointer to the frame
464 wxFrame
*GetFrame() const;
467 // called immediately after the log frame creation allowing for
468 // any extra initializations
469 virtual void OnFrameCreate(wxFrame
*frame
);
470 // called if the user closes the window interactively, will not be
471 // called if it is destroyed for another reason (such as when program
472 // exits) - return TRUE from here to allow the frame to close, FALSE
473 // to prevent this from happening
474 virtual bool OnFrameClose(wxFrame
*frame
);
475 // called right before the log frame is going to be deleted: will
476 // always be called unlike OnFrameClose()
477 virtual void OnFrameDelete(wxFrame
*frame
);
480 virtual void DoLog(wxLogLevel level
, const wxChar
*szString
, time_t t
);
481 virtual void DoLogString(const wxChar
*szString
, time_t t
);
484 wxLogFrame
*m_pLogFrame
; // the log frame
486 DECLARE_NO_COPY_CLASS(wxLogWindow
)
489 #endif // wxUSE_LOGWINDOW
493 // ============================================================================
495 // ============================================================================
497 // ----------------------------------------------------------------------------
498 // Log functions should be used by application instead of stdio, iostream &c
499 // for log messages for easy redirection
500 // ----------------------------------------------------------------------------
502 // ----------------------------------------------------------------------------
503 // get error code/error message from system in a portable way
504 // ----------------------------------------------------------------------------
506 // return the last system error code
507 WXDLLEXPORT
unsigned long wxSysErrorCode();
509 // return the error message for given (or last if 0) error code
510 WXDLLEXPORT
const wxChar
* wxSysErrorMsg(unsigned long nErrCode
= 0);
512 // ----------------------------------------------------------------------------
513 // define wxLog<level>
514 // ----------------------------------------------------------------------------
516 #define DECLARE_LOG_FUNCTION(level) \
517 extern void WXDLLEXPORT wxVLog##level(const wxChar *szFormat, \
519 extern void WXDLLEXPORT wxLog##level(const wxChar *szFormat, \
520 ...) ATTRIBUTE_PRINTF_1
521 #define DECLARE_LOG_FUNCTION2(level, arg1) \
522 extern void WXDLLEXPORT wxVLog##level(arg1, const wxChar *szFormat, \
524 extern void WXDLLEXPORT wxLog##level(arg1, const wxChar *szFormat, \
525 ...) ATTRIBUTE_PRINTF_2
529 // log functions do nothing at all
530 #define DECLARE_LOG_FUNCTION(level) \
531 inline void WXDLLEXPORT wxVLog##level(const wxChar *szFormat, \
533 inline void WXDLLEXPORT wxLog##level(const wxChar *szFormat, ...) {}
534 #define DECLARE_LOG_FUNCTION2(level, arg1) \
535 inline void WXDLLEXPORT wxVLog##level(arg1, const wxChar *szFormat, \
537 inline void WXDLLEXPORT wxLog##level(arg1, const wxChar *szFormat, ...) {}
539 #endif // wxUSE_LOG/!wxUSE_LOG
541 // a generic function for all levels (level is passes as parameter)
542 DECLARE_LOG_FUNCTION2(Generic
, wxLogLevel level
);
544 // one function per each level
545 DECLARE_LOG_FUNCTION(FatalError
);
546 DECLARE_LOG_FUNCTION(Error
);
547 DECLARE_LOG_FUNCTION(Warning
);
548 DECLARE_LOG_FUNCTION(Message
);
549 DECLARE_LOG_FUNCTION(Info
);
550 DECLARE_LOG_FUNCTION(Verbose
);
552 // this function sends the log message to the status line of the top level
553 // application frame, if any
554 DECLARE_LOG_FUNCTION(Status
);
556 // this one is the same as previous except that it allows to explicitly
557 // specify the frame to which the output should go
558 DECLARE_LOG_FUNCTION2(Status
, wxFrame
*pFrame
);
560 // additional one: as wxLogError, but also logs last system call error code
561 // and the corresponding error message if available
562 DECLARE_LOG_FUNCTION(SysError
);
564 // and another one which also takes the error code (for those broken APIs
565 // that don't set the errno (like registry APIs in Win32))
566 DECLARE_LOG_FUNCTION2(SysError
, long lErrCode
);
568 // debug functions do nothing in release mode
570 DECLARE_LOG_FUNCTION(Debug
);
572 // first kind of LogTrace is unconditional: it doesn't check the level,
573 DECLARE_LOG_FUNCTION(Trace
);
575 // this second version will only log the message if the mask had been
576 // added to the list of masks with AddTraceMask()
577 DECLARE_LOG_FUNCTION2(Trace
, const wxChar
*mask
);
579 // the last one does nothing if all of level bits are not set
580 // in wxLog::GetActive()->GetTraceMask() - it's deprecated in favour of
581 // string identifiers
582 DECLARE_LOG_FUNCTION2(Trace
, wxTraceMask mask
);
584 // these functions do nothing in release builds
585 inline void wxVLogDebug(const wxChar
*, va_list) { }
586 inline void wxLogDebug(const wxChar
*, ...) { }
587 inline void wxVLogTrace(const wxChar
*, va_list) { }
588 inline void wxLogTrace(const wxChar
*, ...) { }
589 inline void wxVLogTrace(wxTraceMask
, const wxChar
*, va_list) { }
590 inline void wxLogTrace(wxTraceMask
, const wxChar
*, ...) { }
591 inline void wxVLogTrace(const wxChar
*, const wxChar
*, va_list) { }
592 inline void wxLogTrace(const wxChar
*, const wxChar
*, ...) { }
593 #endif // debug/!debug
595 // wxLogFatalError helper: show the (fatal) error to the user in a safe way,
596 // i.e. without using wxMessageBox() for example because it could crash
597 void WXDLLEXPORT
wxSafeShowMessage(const wxString
& title
, const wxString
& text
);
599 // ----------------------------------------------------------------------------
600 // debug only logging functions: use them with API name and error code
601 // ----------------------------------------------------------------------------
604 // make life easier for people using VC++ IDE: clicking on the message
605 // will take us immediately to the place of the failed API
607 #define wxLogApiError(api, rc) \
608 wxLogDebug(wxT("%s(%d): '%s' failed with error 0x%08lx (%s)."), \
609 __TFILE__, __LINE__, api, \
610 (long)rc, wxSysErrorMsg(rc))
612 #define wxLogApiError(api, rc) \
613 wxLogDebug(wxT("In file %s at line %d: '%s' failed with " \
614 "error 0x%08lx (%s)."), \
615 __TFILE__, __LINE__, api, \
616 (long)rc, wxSysErrorMsg(rc))
619 #define wxLogLastError(api) wxLogApiError(api, wxSysErrorCode())
622 inline void wxLogApiError(const wxChar
*, long) { }
623 inline void wxLogLastError(const wxChar
*) { }
624 #endif //debug/!debug