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 /////////////////////////////////////////////////////////////////////////////
16 #pragma interface "log.h"
19 #include <wx/dynarray.h>
22 // ----------------------------------------------------------------------------
24 // ----------------------------------------------------------------------------
26 // different standard log levels (you may also define your own)
29 wxLOG_FatalError
, // program can't continue, abort immediately
30 wxLOG_Error
, // a serious error, user must be informed about it
31 wxLOG_Warning
, // user is normally informed about it but may be ignored
32 wxLOG_Message
, // normal message (i.e. normal output of a non GUI app)
33 wxLOG_Info
, // informational message (a.k.a. 'Verbose')
34 wxLOG_Status
, // informational: might go to the status line of GUI app
35 wxLOG_Debug
, // never shown to the user, disabled in release mode
36 wxLOG_Trace
, // trace messages are also only enabled in debug mode
37 wxLOG_Progress
, // used for progress indicator (not yet)
38 wxLOG_User
= 100 // user defined levels start here
41 // symbolic trace masks - wxLogTrace("foo", "some trace message...") will be
42 // discarded unless the string "foo" has been added to the list of allowed
43 // ones with AddTraceMask()
45 #define wxTRACE_MemAlloc "memalloc" // trace memory allocation (new/delete)
46 #define wxTRACE_Messages "messages" // trace window messages/X callbacks
47 #define wxTRACE_ResAlloc "resalloc" // trace GDI resource allocation
48 #define wxTRACE_RefCount "refcount" // trace various ref counting operations
51 #define wxTRACE_OleCalls "ole" // OLE interface calls
54 // the trace masks have been superceded by symbolic trace constants, they're
55 // for compatibility only andwill be removed soon - do NOT use them
57 // meaning of different bits of the trace mask (which allows selectively
58 // enable/disable some trace messages)
59 #define wxTraceMemAlloc 0x0001 // trace memory allocation (new/delete)
60 #define wxTraceMessages 0x0002 // trace window messages/X callbacks
61 #define wxTraceResAlloc 0x0004 // trace GDI resource allocation
62 #define wxTraceRefCount 0x0008 // trace various ref counting operations
65 #define wxTraceOleCalls 0x0100 // OLE interface calls
68 typedef unsigned long wxTraceMask
;
69 typedef unsigned long wxLogLevel
;
71 // ----------------------------------------------------------------------------
72 // forward declarations
73 // ----------------------------------------------------------------------------
75 class WXDLLEXPORT wxTextCtrl
;
76 class WXDLLEXPORT wxLogFrame
;
77 class WXDLLEXPORT wxFrame
;
80 // N.B. BC++ doesn't have istream.h, ostream.h
81 # include <iostream.h>
84 # if defined(__VISUALC__) || defined(__MWERKS__)
89 // ----------------------------------------------------------------------------
90 // derive from this class to redirect (or suppress, or ...) log messages
91 // normally, only a single instance of this class exists but it's not enforced
92 // ----------------------------------------------------------------------------
94 class WXDLLEXPORT wxLog
100 // these functions allow to completely disable all log messages
101 // is logging disabled now?
102 static bool IsEnabled() { return ms_doLog
; }
103 // change the flag state, return the previous one
104 static bool EnableLogging(bool doIt
= TRUE
)
105 { bool doLogOld
= ms_doLog
; ms_doLog
= doIt
; return doLogOld
; }
107 // static sink function - see DoLog() for function to overload in the
109 static void OnLog(wxLogLevel level
, const char *szString
, time_t t
)
112 wxLog
*pLogger
= GetActiveTarget();
114 pLogger
->DoLog(level
, szString
, t
);
119 // flush shows all messages if they're not logged immediately (FILE
120 // and iostream logs don't need it, but wxGuiLog does to avoid showing
121 // 17 modal dialogs one after another)
122 virtual void Flush();
123 // call to Flush() may be optimized: call it only if this function
124 // returns true (although Flush() also returns immediately if there is
125 // no messages, this functions is more efficient because inline)
126 bool HasPendingMessages() const { return m_bHasMessages
; }
128 // only one sink is active at each moment
129 // get current log target, will call wxApp::CreateLogTarget() to
130 // create one if none exists
131 static wxLog
*GetActiveTarget();
132 // change log target, pLogger may be NULL
133 static wxLog
*SetActiveTarget(wxLog
*pLogger
);
135 // functions controlling the default wxLog behaviour
136 // verbose mode is activated by standard command-line '-verbose'
138 void SetVerbose(bool bVerbose
= TRUE
) { m_bVerbose
= bVerbose
; }
139 // should GetActiveTarget() try to create a new log object if the
141 static void DontCreateOnDemand() { ms_bAutoCreate
= FALSE
; }
143 // trace mask (see wxTraceXXX constants for details)
144 static void SetTraceMask(wxTraceMask ulMask
) { ms_ulTraceMask
= ulMask
; }
145 // add string trace mask
146 static void AddTraceMask(const wxString
& str
) { ms_aTraceMasks
.Add(str
); }
147 // add string trace mask
148 static void RemoveTraceMask(const wxString
& str
);
151 // gets the verbose status
152 bool GetVerbose() const { return m_bVerbose
; }
154 static wxTraceMask
GetTraceMask() { return ms_ulTraceMask
; }
155 // is this trace mask in the list?
156 static bool IsAllowedTraceMask(const char *mask
)
157 { return ms_aTraceMasks
.Index(mask
) != wxNOT_FOUND
; }
159 // make dtor virtual for all derived classes
163 bool m_bHasMessages
; // any messages in the queue?
164 bool m_bVerbose
; // FALSE => ignore LogInfo messages
166 // the logging functions that can be overriden
167 // default DoLog() prepends the time stamp and a prefix corresponding
168 // to the message to szString and then passes it to DoLogString()
169 virtual void DoLog(wxLogLevel level
, const char *szString
, time_t t
);
170 // default DoLogString does nothing but is not pure virtual because if
171 // you override DoLog() you might not need it at all
172 virtual void DoLogString(const char *szString
, time_t t
);
178 static wxLog
*ms_pLogger
; // currently active log sink
179 static bool ms_doLog
; // FALSE => all logging disabled
180 static bool ms_bAutoCreate
; // create new log targets on demand?
182 static wxTraceMask ms_ulTraceMask
; // controls wxLogTrace behaviour
183 static wxArrayString ms_aTraceMasks
; // more powerful filter for wxLogTrace
186 // ----------------------------------------------------------------------------
187 // "trivial" derivations of wxLog
188 // ----------------------------------------------------------------------------
190 // log everything to a "FILE *", stderr by default
191 class WXDLLEXPORT wxLogStderr
: public wxLog
194 // redirect log output to a FILE
195 wxLogStderr(FILE *fp
= (FILE *) NULL
);
198 // implement sink function
199 virtual void DoLogString(const char *szString
, time_t t
);
204 #if wxUSE_STD_IOSTREAM
205 // log everything to an "ostream", cerr by default
206 class WXDLLEXPORT wxLogStream
: public wxLog
209 // redirect log output to an ostream
210 wxLogStream(ostream
*ostr
= (ostream
*) NULL
);
213 // implement sink function
214 virtual void DoLogString(const char *szString
, time_t t
);
216 // using ptr here to avoid including <iostream.h> from this file
223 #if wxUSE_STD_IOSTREAM
224 // log everything to a text window (GUI only of course)
225 class WXDLLEXPORT wxLogTextCtrl
: public wxLogStream
228 // we just create an ostream from wxTextCtrl and use it in base class
229 wxLogTextCtrl(wxTextCtrl
*pTextCtrl
);
234 // ----------------------------------------------------------------------------
235 // GUI log target, the default one for wxWindows programs
236 // ----------------------------------------------------------------------------
237 class WXDLLEXPORT wxLogGui
: public wxLog
243 // show all messages that were logged since the last Flush()
244 virtual void Flush();
247 virtual void DoLog(wxLogLevel level
, const char *szString
, time_t t
);
252 wxArrayString m_aMessages
;
253 wxArrayLong m_aTimes
;
254 bool m_bErrors
, // do we have any errors?
255 m_bWarnings
; // any warnings?
258 // ----------------------------------------------------------------------------
259 // (background) log window: this class forwards all log messages to the log
260 // target which was active when it was instantiated, but also collects them
261 // to the log window. This window has it's own menu which allows the user to
262 // close it, clear the log contents or save it to the file.
263 // ----------------------------------------------------------------------------
264 class WXDLLEXPORT wxLogWindow
: public wxLog
267 wxLogWindow(wxFrame
*pParent
, // the parent frame (can be NULL)
268 const char *szTitle
, // the title of the frame
269 bool bShow
= TRUE
, // show window immediately?
270 bool bPassToOld
= TRUE
); // pass log messages to the old target?
274 // show/hide the log window
275 void Show(bool bShow
= TRUE
);
276 // retrieve the pointer to the frame
277 wxFrame
*GetFrame() const;
280 // the previous log target (may be NULL)
281 wxLog
*GetOldLog() const { return m_pOldLog
; }
282 // are we passing the messages to the previous log target?
283 bool IsPassingMessages() const { return m_bPassMessages
; }
285 // we can pass the messages to the previous log target (we're in this mode by
286 // default: we collect all messages in the window, but also let the default
287 // processing take place)
288 void PassMessages(bool bDoPass
) { m_bPassMessages
= bDoPass
; }
290 // base class virtuals
291 // we don't need it ourselves, but we pass it to the previous logger
292 virtual void Flush();
295 // called immediately after the log frame creation allowing for
296 // any extra initializations
297 virtual void OnFrameCreate(wxFrame
*frame
);
298 // called right before the log frame is going to be deleted
299 virtual void OnFrameDelete(wxFrame
*frame
);
302 virtual void DoLog(wxLogLevel level
, const char *szString
, time_t t
);
303 virtual void DoLogString(const char *szString
, time_t t
);
306 bool m_bPassMessages
; // pass messages to m_pOldLog?
307 wxLog
*m_pOldLog
; // previous log target
308 wxLogFrame
*m_pLogFrame
; // the log frame
311 #endif // wxUSE_NOGUI
313 // ----------------------------------------------------------------------------
314 // /dev/null log target: suppress logging until this object goes out of scope
315 // ----------------------------------------------------------------------------
322 // wxFile.Open() normally complains if file can't be opened, we don't want it
324 if ( !file.Open("bar") )
325 ... process error ourselves ...
327 // ~wxLogNull called, old log sink restored
330 class WXDLLEXPORT wxLogNull
333 wxLogNull() { m_flagOld
= wxLog::EnableLogging(FALSE
); }
334 ~wxLogNull() { (void)wxLog::EnableLogging(m_flagOld
); }
337 bool m_flagOld
; // the previous value of the wxLog::ms_doLog
340 // ============================================================================
342 // ============================================================================
344 // ----------------------------------------------------------------------------
345 // Log functions should be used by application instead of stdio, iostream &c
346 // for log messages for easy redirection
347 // ----------------------------------------------------------------------------
349 // define wxLog<level>
350 // -------------------
352 #define DECLARE_LOG_FUNCTION(level) \
353 extern void WXDLLEXPORT wxLog##level(const char *szFormat, ...)
354 #define DECLARE_LOG_FUNCTION2(level, arg1) \
355 extern void WXDLLEXPORT wxLog##level(arg1, const char *szFormat, ...)
357 // a generic function for all levels (level is passes as parameter)
358 DECLARE_LOG_FUNCTION2(Generic
, wxLogLevel level
);
360 // one function per each level
361 DECLARE_LOG_FUNCTION(FatalError
);
362 DECLARE_LOG_FUNCTION(Error
);
363 DECLARE_LOG_FUNCTION(Warning
);
364 DECLARE_LOG_FUNCTION(Message
);
365 DECLARE_LOG_FUNCTION(Info
);
366 DECLARE_LOG_FUNCTION(Verbose
);
368 // this function sends the log message to the status line of the top level
369 // application frame, if any
370 DECLARE_LOG_FUNCTION(Status
);
372 // this one is the same as previous except that it allows to explicitly
373 // specify the frame to which the output should go
374 DECLARE_LOG_FUNCTION2(Status
, wxFrame
*pFrame
);
376 // additional one: as wxLogError, but also logs last system call error code
377 // and the corresponding error message if available
378 DECLARE_LOG_FUNCTION(SysError
);
380 // and another one which also takes the error code (for those broken APIs
381 // that don't set the errno (like registry APIs in Win32))
382 DECLARE_LOG_FUNCTION2(SysError
, long lErrCode
);
384 // debug functions do nothing in release mode
386 DECLARE_LOG_FUNCTION(Debug
);
388 // first king of LogTrace is uncoditional: it doesn't check the level,
389 DECLARE_LOG_FUNCTION(Trace
);
391 // this second version will only log the message if the mask had been
392 // added to the list of masks with AddTraceMask()
393 DECLARE_LOG_FUNCTION2(Trace
, const char *mask
);
395 // the last one does nothing if all of level bits are not set
396 // in wxLog::GetActive()->GetTraceMask() - it's deprecated in favour of
397 // string identifiers
398 DECLARE_LOG_FUNCTION2(Trace
, wxTraceMask mask
);
400 // these functions do nothing in release builds
401 inline void wxLogDebug(const char *, ...) { }
402 inline void wxLogTrace(const char *, ...) { }
403 inline void wxLogTrace(wxTraceMask
, const char *, ...) { }
404 inline void wxLogTrace(const char *, const char *, ...) { }
408 // are we in 'verbose' mode?
409 // (note that it's often handy to change this var manually from the
410 // debugger, thus enabling/disabling verbose reporting for some
411 // parts of the program only)
412 WXDLLEXPORT_DATA(extern bool) g_bVerbose
;
414 // ----------------------------------------------------------------------------
415 // get error code/error message from system in a portable way
416 // ----------------------------------------------------------------------------
418 // return the last system error code
419 WXDLLEXPORT
unsigned long wxSysErrorCode();
420 // return the error message for given (or last if 0) error code
421 WXDLLEXPORT
const char* wxSysErrorMsg(unsigned long nErrCode
= 0);
423 // ----------------------------------------------------------------------------
424 // debug only logging functions: use them with API name and error code
425 // ----------------------------------------------------------------------------
428 #define wxLogApiError(api, rc) \
429 wxLogDebug("At %s(%d) '%s' failed with error %lx (%s).", \
430 __FILE__, __LINE__, api, \
431 rc, wxSysErrorMsg(rc))
432 #define wxLogLastError(api) wxLogApiError(api, wxSysErrorCode())
434 inline void wxLogApiError(const char *, long) { }
435 inline void wxLogLastError(const char *) { }
436 #endif //debug/!debug