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>
21 // ----------------------------------------------------------------------------
23 // ----------------------------------------------------------------------------
25 // different standard log levels (you may also define your own)
28 wxLOG_FatalError
, // program can't continue, abort immediately
29 wxLOG_Error
, // a serious error, user must be informed about it
30 wxLOG_Warning
, // user is normally informed about it but may be ignored
31 wxLOG_Message
, // normal message (i.e. normal output of a non GUI app)
32 wxLOG_Info
, // informational message (a.k.a. 'Verbose')
33 wxLOG_Status
, // informational: might go to the status line of GUI app
34 wxLOG_Debug
, // never shown to the user, disabled in release mode
35 wxLOG_Trace
, // trace messages are also only enabled in debug mode
36 wxLOG_Progress
, // used for progress indicator (not yet)
37 wxLOG_User
= 100 // user defined levels start here
40 // symbolic trace masks - wxLogTrace("foo", "some trace message...") will be
41 // discarded unless the string "foo" has been added to the list of allowed
42 // ones with AddTraceMask()
44 #define wxTRACE_MemAlloc "memalloc" // trace memory allocation (new/delete)
45 #define wxTRACE_Messages "messages" // trace window messages/X callbacks
46 #define wxTRACE_ResAlloc "resalloc" // trace GDI resource allocation
47 #define wxTRACE_RefCount "refcount" // trace various ref counting operations
50 #define wxTRACE_OleCalls "ole" // OLE interface calls
53 // the trace masks have been superceded by symbolic trace constants, they're
54 // for compatibility only andwill be removed soon - do NOT use them
56 // meaning of different bits of the trace mask (which allows selectively
57 // enable/disable some trace messages)
58 #define wxTraceMemAlloc 0x0001 // trace memory allocation (new/delete)
59 #define wxTraceMessages 0x0002 // trace window messages/X callbacks
60 #define wxTraceResAlloc 0x0004 // trace GDI resource allocation
61 #define wxTraceRefCount 0x0008 // trace various ref counting operations
64 #define wxTraceOleCalls 0x0100 // OLE interface calls
67 typedef unsigned long wxTraceMask
;
68 typedef unsigned long wxLogLevel
;
70 // ----------------------------------------------------------------------------
71 // forward declarations
72 // ----------------------------------------------------------------------------
74 class WXDLLEXPORT wxTextCtrl
;
75 class WXDLLEXPORT wxLogFrame
;
76 class WXDLLEXPORT wxFrame
;
79 // N.B. BC++ doesn't have istream.h, ostream.h
80 # include <iostream.h>
83 # if defined(__VISUALC__) || defined(__MWERKS__)
88 // ----------------------------------------------------------------------------
89 // derive from this class to redirect (or suppress, or ...) log messages
90 // normally, only a single instance of this class exists but it's not enforced
91 // ----------------------------------------------------------------------------
93 class WXDLLEXPORT wxLog
99 // these functions allow to completely disable all log messages
100 // is logging disabled now?
101 static bool IsEnabled() { return ms_doLog
; }
102 // change the flag state, return the previous one
103 static bool EnableLogging(bool doIt
= TRUE
)
104 { bool doLogOld
= ms_doLog
; ms_doLog
= doIt
; return doLogOld
; }
106 // static sink function - see DoLog() for function to overload in the
108 static void OnLog(wxLogLevel level
, const char *szString
, time_t t
)
111 wxLog
*pLogger
= GetActiveTarget();
113 pLogger
->DoLog(level
, szString
, t
);
118 // flush shows all messages if they're not logged immediately (FILE
119 // and iostream logs don't need it, but wxGuiLog does to avoid showing
120 // 17 modal dialogs one after another)
121 virtual void Flush();
122 // call to Flush() may be optimized: call it only if this function
123 // returns true (although Flush() also returns immediately if there is
124 // no messages, this functions is more efficient because inline)
125 bool HasPendingMessages() const { return m_bHasMessages
; }
127 // only one sink is active at each moment
128 // get current log target, will call wxApp::CreateLogTarget() to
129 // create one if none exists
130 static wxLog
*GetActiveTarget();
131 // change log target, pLogger may be NULL
132 static wxLog
*SetActiveTarget(wxLog
*pLogger
);
134 // functions controlling the default wxLog behaviour
135 // verbose mode is activated by standard command-line '-verbose'
137 void SetVerbose(bool bVerbose
= TRUE
) { m_bVerbose
= bVerbose
; }
138 // should GetActiveTarget() try to create a new log object if the
140 static void DontCreateOnDemand() { ms_bAutoCreate
= FALSE
; }
142 // trace mask (see wxTraceXXX constants for details)
143 static void SetTraceMask(wxTraceMask ulMask
) { ms_ulTraceMask
= ulMask
; }
144 // add string trace mask
145 static void AddTraceMask(const wxString
& str
) { ms_aTraceMasks
.Add(str
); }
146 // add string trace mask
147 static void RemoveTraceMask(const wxString
& str
);
150 // gets the verbose status
151 bool GetVerbose() const { return m_bVerbose
; }
153 static wxTraceMask
GetTraceMask() { return ms_ulTraceMask
; }
154 // is this trace mask in the list?
155 static bool IsAllowedTraceMask(const char *mask
)
156 { return ms_aTraceMasks
.Index(mask
) != wxNOT_FOUND
; }
158 // make dtor virtual for all derived classes
162 bool m_bHasMessages
; // any messages in the queue?
163 bool m_bVerbose
; // FALSE => ignore LogInfo messages
165 // the logging functions that can be overriden
166 // default DoLog() prepends the time stamp and a prefix corresponding
167 // to the message to szString and then passes it to DoLogString()
168 virtual void DoLog(wxLogLevel level
, const char *szString
, time_t t
);
169 // default DoLogString does nothing but is not pure virtual because if
170 // you override DoLog() you might not need it at all
171 virtual void DoLogString(const char *szString
, time_t t
);
177 static wxLog
*ms_pLogger
; // currently active log sink
178 static bool ms_doLog
; // FALSE => all logging disabled
179 static bool ms_bAutoCreate
; // create new log targets on demand?
181 static wxTraceMask ms_ulTraceMask
; // controls wxLogTrace behaviour
182 static wxArrayString ms_aTraceMasks
; // more powerful filter for wxLogTrace
185 // ----------------------------------------------------------------------------
186 // "trivial" derivations of wxLog
187 // ----------------------------------------------------------------------------
189 // log everything to a "FILE *", stderr by default
190 class WXDLLEXPORT wxLogStderr
: public wxLog
193 // redirect log output to a FILE
194 wxLogStderr(FILE *fp
= (FILE *) NULL
);
197 // implement sink function
198 virtual void DoLogString(const char *szString
, time_t t
);
203 #if wxUSE_STD_IOSTREAM
204 // log everything to an "ostream", cerr by default
205 class WXDLLEXPORT wxLogStream
: public wxLog
208 // redirect log output to an ostream
209 wxLogStream(ostream
*ostr
= (ostream
*) NULL
);
212 // implement sink function
213 virtual void DoLogString(const char *szString
, time_t t
);
215 // using ptr here to avoid including <iostream.h> from this file
222 #if wxUSE_STD_IOSTREAM
223 // log everything to a text window (GUI only of course)
224 class WXDLLEXPORT wxLogTextCtrl
: public wxLogStream
227 // we just create an ostream from wxTextCtrl and use it in base class
228 wxLogTextCtrl(wxTextCtrl
*pTextCtrl
);
233 // ----------------------------------------------------------------------------
234 // GUI log target, the default one for wxWindows programs
235 // ----------------------------------------------------------------------------
236 class WXDLLEXPORT wxLogGui
: public wxLog
242 // show all messages that were logged since the last Flush()
243 virtual void Flush();
246 virtual void DoLog(wxLogLevel level
, const char *szString
, time_t t
);
251 wxArrayString m_aMessages
;
252 wxArrayLong m_aTimes
;
253 bool m_bErrors
, // do we have any errors?
254 m_bWarnings
; // any warnings?
257 // ----------------------------------------------------------------------------
258 // (background) log window: this class forwards all log messages to the log
259 // target which was active when it was instantiated, but also collects them
260 // to the log window. This window has it's own menu which allows the user to
261 // close it, clear the log contents or save it to the file.
262 // ----------------------------------------------------------------------------
263 class WXDLLEXPORT wxLogWindow
: public wxLog
266 wxLogWindow(wxFrame
*pParent
, // the parent frame (can be NULL)
267 const char *szTitle
, // the title of the frame
268 bool bShow
= TRUE
, // show window immediately?
269 bool bPassToOld
= TRUE
); // pass log messages to the old target?
273 // show/hide the log window
274 void Show(bool bShow
= TRUE
);
275 // retrieve the pointer to the frame
276 wxFrame
*GetFrame() const;
279 // the previous log target (may be NULL)
280 wxLog
*GetOldLog() const { return m_pOldLog
; }
281 // are we passing the messages to the previous log target?
282 bool IsPassingMessages() const { return m_bPassMessages
; }
284 // we can pass the messages to the previous log target (we're in this mode by
285 // default: we collect all messages in the window, but also let the default
286 // processing take place)
287 void PassMessages(bool bDoPass
) { m_bPassMessages
= bDoPass
; }
289 // base class virtuals
290 // we don't need it ourselves, but we pass it to the previous logger
291 virtual void Flush();
294 // called immediately after the log frame creation allowing for
295 // any extra initializations
296 virtual void OnFrameCreate(wxFrame
*frame
);
297 // called right before the log frame is going to be deleted
298 virtual void OnFrameDelete(wxFrame
*frame
);
301 virtual void DoLog(wxLogLevel level
, const char *szString
, time_t t
);
302 virtual void DoLogString(const char *szString
, time_t t
);
305 bool m_bPassMessages
; // pass messages to m_pOldLog?
306 wxLog
*m_pOldLog
; // previous log target
307 wxLogFrame
*m_pLogFrame
; // the log frame
310 #endif // wxUSE_NOGUI
312 // ----------------------------------------------------------------------------
313 // /dev/null log target: suppress logging until this object goes out of scope
314 // ----------------------------------------------------------------------------
321 // wxFile.Open() normally complains if file can't be opened, we don't want it
323 if ( !file.Open("bar") )
324 ... process error ourselves ...
326 // ~wxLogNull called, old log sink restored
329 class WXDLLEXPORT wxLogNull
332 wxLogNull() { m_flagOld
= wxLog::EnableLogging(FALSE
); }
333 ~wxLogNull() { (void)wxLog::EnableLogging(m_flagOld
); }
336 bool m_flagOld
; // the previous value of the wxLog::ms_doLog
339 // ============================================================================
341 // ============================================================================
343 // ----------------------------------------------------------------------------
344 // Log functions should be used by application instead of stdio, iostream &c
345 // for log messages for easy redirection
346 // ----------------------------------------------------------------------------
348 // define wxLog<level>
349 // -------------------
351 #define DECLARE_LOG_FUNCTION(level) \
352 extern void WXDLLEXPORT wxLog##level(const char *szFormat, ...)
353 #define DECLARE_LOG_FUNCTION2(level, arg1) \
354 extern void WXDLLEXPORT wxLog##level(arg1, const char *szFormat, ...)
356 // a generic function for all levels (level is passes as parameter)
357 DECLARE_LOG_FUNCTION2(Generic
, wxLogLevel level
);
359 // one function per each level
360 DECLARE_LOG_FUNCTION(FatalError
);
361 DECLARE_LOG_FUNCTION(Error
);
362 DECLARE_LOG_FUNCTION(Warning
);
363 DECLARE_LOG_FUNCTION(Message
);
364 DECLARE_LOG_FUNCTION(Info
);
365 DECLARE_LOG_FUNCTION(Verbose
);
367 // this function sends the log message to the status line of the top level
368 // application frame, if any
369 DECLARE_LOG_FUNCTION(Status
);
371 // this one is the same as previous except that it allows to explicitly
372 // specify the frame to which the output should go
373 DECLARE_LOG_FUNCTION2(Status
, wxFrame
*pFrame
);
375 // additional one: as wxLogError, but also logs last system call error code
376 // and the corresponding error message if available
377 DECLARE_LOG_FUNCTION(SysError
);
379 // and another one which also takes the error code (for those broken APIs
380 // that don't set the errno (like registry APIs in Win32))
381 DECLARE_LOG_FUNCTION2(SysError
, long lErrCode
);
383 // debug functions do nothing in release mode
385 DECLARE_LOG_FUNCTION(Debug
);
387 // first king of LogTrace is uncoditional: it doesn't check the level,
388 DECLARE_LOG_FUNCTION(Trace
);
390 // this second version will only log the message if the mask had been
391 // added to the list of masks with AddTraceMask()
392 DECLARE_LOG_FUNCTION2(Trace
, const char *mask
);
394 // the last one does nothing if all of level bits are not set
395 // in wxLog::GetActive()->GetTraceMask() - it's deprecated in favour of
396 // string identifiers
397 DECLARE_LOG_FUNCTION2(Trace
, wxTraceMask mask
);
399 // these functions do nothing in release builds
400 inline void wxLogDebug(const char *, ...) { }
401 inline void wxLogTrace(const char *, ...) { }
402 inline void wxLogTrace(wxTraceMask
, const char *, ...) { }
403 inline void wxLogTrace(const char *, const char *, ...) { }
407 // are we in 'verbose' mode?
408 // (note that it's often handy to change this var manually from the
409 // debugger, thus enabling/disabling verbose reporting for some
410 // parts of the program only)
411 WXDLLEXPORT_DATA(extern bool) g_bVerbose
;
413 // ----------------------------------------------------------------------------
414 // get error code/error message from system in a portable way
415 // ----------------------------------------------------------------------------
417 // return the last system error code
418 WXDLLEXPORT
unsigned long wxSysErrorCode();
419 // return the error message for given (or last if 0) error code
420 WXDLLEXPORT
const char* wxSysErrorMsg(unsigned long nErrCode
= 0);
422 // ----------------------------------------------------------------------------
423 // debug only logging functions: use them with API name and error code
424 // ----------------------------------------------------------------------------
427 #define wxLogApiError(api, rc) \
428 wxLogDebug("At %s(%d) '%s' failed with error %lx (%s).", \
429 __FILE__, __LINE__, api, \
430 rc, wxSysErrorMsg(rc))
431 #define wxLogLastError(api) wxLogApiError(api, wxSysErrorCode())
433 inline void wxLogApiError(const char *, long) { }
434 inline void wxLogLastError(const char *) { }
435 #endif //debug/!debug