]> git.saurik.com Git - wxWidgets.git/blame - include/wx/log.h
Generic dirctrl corrections
[wxWidgets.git] / include / wx / log.h
CommitLineData
c801d85f
KB
1/////////////////////////////////////////////////////////////////////////////
2// Name: log.h
3// Purpose: Assorted wxLogXXX functions, and wxLog (sink for logs)
4// Author: Vadim Zeitlin
5// Modified by:
6// Created: 29/01/98
7// RCS-ID: $Id$
8// Copyright: (c) 1998 Vadim Zeitlin <zeitlin@dptmaths.ens-cachan.fr>
9// Licence: wxWindows license
10/////////////////////////////////////////////////////////////////////////////
11
34138703
JS
12#ifndef _WX_LOG_H_
13#define _WX_LOG_H_
c801d85f 14
d6b9496a
VZ
15#ifdef __GNUG__
16 #pragma interface "log.h"
0d3820b3 17#endif
c801d85f 18
38830220 19#include "wx/setup.h"
d1af991f 20#include "wx/string.h"
38830220 21
546db2a8
VZ
22// ----------------------------------------------------------------------------
23// forward declarations
24// ----------------------------------------------------------------------------
25
26class WXDLLEXPORT wxTextCtrl;
27class WXDLLEXPORT wxLogFrame;
28class WXDLLEXPORT wxFrame;
29
30// ----------------------------------------------------------------------------
31// types
32// ----------------------------------------------------------------------------
33
34typedef unsigned long wxTraceMask;
35typedef unsigned long wxLogLevel;
36
37// ----------------------------------------------------------------------------
38// headers
39// ----------------------------------------------------------------------------
40
88ac883a
VZ
41#if wxUSE_LOG
42
c30aaf75
VZ
43#include <time.h> // for time_t
44
45#include "wx/dynarray.h"
d6b9496a 46
9ef3052c
VZ
47// ----------------------------------------------------------------------------
48// constants
49// ----------------------------------------------------------------------------
50
51// different standard log levels (you may also define your own)
52enum
53{
d6b9496a
VZ
54 wxLOG_FatalError, // program can't continue, abort immediately
55 wxLOG_Error, // a serious error, user must be informed about it
56 wxLOG_Warning, // user is normally informed about it but may be ignored
57 wxLOG_Message, // normal message (i.e. normal output of a non GUI app)
58 wxLOG_Info, // informational message (a.k.a. 'Verbose')
59 wxLOG_Status, // informational: might go to the status line of GUI app
60 wxLOG_Debug, // never shown to the user, disabled in release mode
61 wxLOG_Trace, // trace messages are also only enabled in debug mode
62 wxLOG_Progress, // used for progress indicator (not yet)
63 wxLOG_User = 100 // user defined levels start here
9ef3052c
VZ
64};
65
d6b9496a
VZ
66// symbolic trace masks - wxLogTrace("foo", "some trace message...") will be
67// discarded unless the string "foo" has been added to the list of allowed
68// ones with AddTraceMask()
69
08298395
OK
70#define wxTRACE_MemAlloc wxT("memalloc") // trace memory allocation (new/delete)
71#define wxTRACE_Messages wxT("messages") // trace window messages/X callbacks
72#define wxTRACE_ResAlloc wxT("resalloc") // trace GDI resource allocation
73#define wxTRACE_RefCount wxT("refcount") // trace various ref counting operations
d6b9496a
VZ
74
75#ifdef __WXMSW__
08298395 76 #define wxTRACE_OleCalls wxT("ole") // OLE interface calls
d6b9496a
VZ
77#endif
78
79// the trace masks have been superceded by symbolic trace constants, they're
80// for compatibility only andwill be removed soon - do NOT use them
81
9ef3052c
VZ
82// meaning of different bits of the trace mask (which allows selectively
83// enable/disable some trace messages)
84#define wxTraceMemAlloc 0x0001 // trace memory allocation (new/delete)
85#define wxTraceMessages 0x0002 // trace window messages/X callbacks
86#define wxTraceResAlloc 0x0004 // trace GDI resource allocation
87#define wxTraceRefCount 0x0008 // trace various ref counting operations
88
2049ba38 89#ifdef __WXMSW__
d6b9496a 90 #define wxTraceOleCalls 0x0100 // OLE interface calls
9ef3052c
VZ
91#endif
92
38830220 93#include "wx/ioswrap.h"
470b7da3 94
c801d85f
KB
95// ----------------------------------------------------------------------------
96// derive from this class to redirect (or suppress, or ...) log messages
97// normally, only a single instance of this class exists but it's not enforced
c801d85f 98// ----------------------------------------------------------------------------
d6b9496a 99
c801d85f
KB
100class WXDLLEXPORT wxLog
101{
102public:
d6b9496a
VZ
103 // ctor
104 wxLog();
105
106 // these functions allow to completely disable all log messages
107 // is logging disabled now?
108 static bool IsEnabled() { return ms_doLog; }
109 // change the flag state, return the previous one
110 static bool EnableLogging(bool doIt = TRUE)
111 { bool doLogOld = ms_doLog; ms_doLog = doIt; return doLogOld; }
112
113 // static sink function - see DoLog() for function to overload in the
114 // derived classes
9e3d3318 115 static void OnLog(wxLogLevel level, const wxChar *szString, time_t t)
d6b9496a
VZ
116 {
117 if ( IsEnabled() ) {
118 wxLog *pLogger = GetActiveTarget();
119 if ( pLogger )
120 pLogger->DoLog(level, szString, t);
121 }
803bf1c5 122 }
d6b9496a
VZ
123
124 // message buffering
125 // flush shows all messages if they're not logged immediately (FILE
126 // and iostream logs don't need it, but wxGuiLog does to avoid showing
127 // 17 modal dialogs one after another)
128 virtual void Flush();
129 // call to Flush() may be optimized: call it only if this function
130 // returns true (although Flush() also returns immediately if there is
131 // no messages, this functions is more efficient because inline)
132 bool HasPendingMessages() const { return m_bHasMessages; }
133
134 // only one sink is active at each moment
bbfa0322
VZ
135 // flush the active target if any
136 static void FlushActive()
137 {
2ed3265e
VZ
138 if ( !ms_suspendCount )
139 {
140 wxLog *log = GetActiveTarget();
141 if ( log && log->HasPendingMessages() )
142 log->Flush();
143 }
bbfa0322 144 }
d6b9496a
VZ
145 // get current log target, will call wxApp::CreateLogTarget() to
146 // create one if none exists
147 static wxLog *GetActiveTarget();
148 // change log target, pLogger may be NULL
149 static wxLog *SetActiveTarget(wxLog *pLogger);
150
2ed3265e
VZ
151 // suspend the message flushing of the main target until the next call
152 // to Resume() - this is mainly for internal use (to prevent wxYield()
153 // from flashing the messages)
154 static void Suspend() { ms_suspendCount++; }
155 // must be called for each Suspend()!
156 static void Resume() { ms_suspendCount--; }
157
d6b9496a
VZ
158 // functions controlling the default wxLog behaviour
159 // verbose mode is activated by standard command-line '-verbose'
160 // option
161 void SetVerbose(bool bVerbose = TRUE) { m_bVerbose = bVerbose; }
162 // should GetActiveTarget() try to create a new log object if the
163 // current is NULL?
164 static void DontCreateOnDemand() { ms_bAutoCreate = FALSE; }
165
166 // trace mask (see wxTraceXXX constants for details)
167 static void SetTraceMask(wxTraceMask ulMask) { ms_ulTraceMask = ulMask; }
168 // add string trace mask
169 static void AddTraceMask(const wxString& str) { ms_aTraceMasks.Add(str); }
170 // add string trace mask
171 static void RemoveTraceMask(const wxString& str);
172
d2e1ef19
VZ
173 // sets the timestamp string: this is used as strftime() format string
174 // for the log targets which add time stamps to the messages - set it
175 // to NULL to disable time stamping completely.
176 static void SetTimestamp(const wxChar *ts) { ms_timestamp = ts; }
177
d6b9496a
VZ
178 // accessors
179 // gets the verbose status
180 bool GetVerbose() const { return m_bVerbose; }
181 // get trace mask
182 static wxTraceMask GetTraceMask() { return ms_ulTraceMask; }
183 // is this trace mask in the list?
9e3d3318 184 static bool IsAllowedTraceMask(const wxChar *mask)
d6b9496a
VZ
185 { return ms_aTraceMasks.Index(mask) != wxNOT_FOUND; }
186
d2e1ef19
VZ
187 // get the current timestamp format string (may be NULL)
188 static const wxChar *GetTimestamp() { return ms_timestamp; }
189
190 // helpers
191 // put the time stamp into the string if ms_timestamp != NULL (don't
192 // change it otherwise)
193 static void TimeStamp(wxString *str);
194
d6b9496a
VZ
195 // make dtor virtual for all derived classes
196 virtual ~wxLog() { }
c801d85f
KB
197
198protected:
d6b9496a
VZ
199 bool m_bHasMessages; // any messages in the queue?
200 bool m_bVerbose; // FALSE => ignore LogInfo messages
c801d85f 201
d6b9496a
VZ
202 // the logging functions that can be overriden
203 // default DoLog() prepends the time stamp and a prefix corresponding
204 // to the message to szString and then passes it to DoLogString()
9e3d3318 205 virtual void DoLog(wxLogLevel level, const wxChar *szString, time_t t);
d6b9496a
VZ
206 // default DoLogString does nothing but is not pure virtual because if
207 // you override DoLog() you might not need it at all
9e3d3318 208 virtual void DoLogString(const wxChar *szString, time_t t);
c801d85f 209
d6b9496a
VZ
210private:
211 // static variables
212 // ----------------
06db8ebd 213
d6b9496a
VZ
214 static wxLog *ms_pLogger; // currently active log sink
215 static bool ms_doLog; // FALSE => all logging disabled
216 static bool ms_bAutoCreate; // create new log targets on demand?
fe7b1156 217
2ed3265e
VZ
218 static size_t ms_suspendCount; // if positive, logs are not flushed
219
d2e1ef19
VZ
220 // format string for strftime(), if NULL, time stamping log messages is
221 // disabled
222 static const wxChar *ms_timestamp;
223
d6b9496a
VZ
224 static wxTraceMask ms_ulTraceMask; // controls wxLogTrace behaviour
225 static wxArrayString ms_aTraceMasks; // more powerful filter for wxLogTrace
c801d85f
KB
226};
227
228// ----------------------------------------------------------------------------
229// "trivial" derivations of wxLog
230// ----------------------------------------------------------------------------
231
232// log everything to a "FILE *", stderr by default
233class WXDLLEXPORT wxLogStderr : public wxLog
234{
235public:
d6b9496a
VZ
236 // redirect log output to a FILE
237 wxLogStderr(FILE *fp = (FILE *) NULL);
c801d85f
KB
238
239private:
d6b9496a 240 // implement sink function
9e3d3318 241 virtual void DoLogString(const wxChar *szString, time_t t);
c801d85f 242
d6b9496a 243 FILE *m_fp;
c801d85f
KB
244};
245
4bf78aae 246#if wxUSE_STD_IOSTREAM
c801d85f
KB
247// log everything to an "ostream", cerr by default
248class WXDLLEXPORT wxLogStream : public wxLog
249{
250public:
d6b9496a
VZ
251 // redirect log output to an ostream
252 wxLogStream(ostream *ostr = (ostream *) NULL);
c801d85f
KB
253
254protected:
d6b9496a 255 // implement sink function
9e3d3318 256 virtual void DoLogString(const wxChar *szString, time_t t);
c801d85f 257
d6b9496a
VZ
258 // using ptr here to avoid including <iostream.h> from this file
259 ostream *m_ostr;
c801d85f 260};
f5abe911 261#endif
c801d85f 262
dd85fc6b
VZ
263// the following log targets are only compiled in if the we're compiling the
264// GUI part (andnot just the base one) of the library, they're implemented in
265// src/generic/logg.cpp *and not src/common/log.cpp unlike all the rest)
266
e90c1d2a 267#if wxUSE_GUI
03f38c58 268
c801d85f 269// log everything to a text window (GUI only of course)
d2e1ef19 270class WXDLLEXPORT wxLogTextCtrl : public wxLog
c801d85f
KB
271{
272public:
d6b9496a 273 wxLogTextCtrl(wxTextCtrl *pTextCtrl);
d2e1ef19
VZ
274
275private:
276 // implement sink function
277 virtual void DoLogString(const wxChar *szString, time_t t);
278
279 // the control we use
280 wxTextCtrl *m_pTextCtrl;
c801d85f 281};
c801d85f
KB
282
283// ----------------------------------------------------------------------------
284// GUI log target, the default one for wxWindows programs
285// ----------------------------------------------------------------------------
286class WXDLLEXPORT wxLogGui : public wxLog
287{
288public:
d6b9496a
VZ
289 // ctor
290 wxLogGui();
c801d85f 291
d6b9496a
VZ
292 // show all messages that were logged since the last Flush()
293 virtual void Flush();
c801d85f
KB
294
295protected:
9e3d3318 296 virtual void DoLog(wxLogLevel level, const wxChar *szString, time_t t);
d6b9496a
VZ
297
298 // empty everything
299 void Clear();
c801d85f 300
f1df0927
VZ
301 wxArrayString m_aMessages; // the log message texts
302 wxArrayInt m_aSeverity; // one of wxLOG_XXX values
303 wxArrayLong m_aTimes; // the time of each message
d6b9496a
VZ
304 bool m_bErrors, // do we have any errors?
305 m_bWarnings; // any warnings?
c801d85f
KB
306};
307
9ef3052c
VZ
308// ----------------------------------------------------------------------------
309// (background) log window: this class forwards all log messages to the log
310// target which was active when it was instantiated, but also collects them
311// to the log window. This window has it's own menu which allows the user to
312// close it, clear the log contents or save it to the file.
313// ----------------------------------------------------------------------------
9ef3052c
VZ
314class WXDLLEXPORT wxLogWindow : public wxLog
315{
316public:
d6b9496a 317 wxLogWindow(wxFrame *pParent, // the parent frame (can be NULL)
9e3d3318 318 const wxChar *szTitle, // the title of the frame
d6b9496a
VZ
319 bool bShow = TRUE, // show window immediately?
320 bool bPassToOld = TRUE); // pass log messages to the old target?
321 ~wxLogWindow();
06db8ebd 322
d6b9496a 323 // window operations
f6bcfd97 324 // show/hide the log window
d6b9496a 325 void Show(bool bShow = TRUE);
f6bcfd97 326 // retrieve the pointer to the frame
d6b9496a 327 wxFrame *GetFrame() const;
9ef3052c 328
d6b9496a 329 // accessors
f6bcfd97 330 // the previous log target (may be NULL)
d6b9496a 331 wxLog *GetOldLog() const { return m_pOldLog; }
f6bcfd97 332 // are we passing the messages to the previous log target?
d6b9496a 333 bool IsPassingMessages() const { return m_bPassMessages; }
a3622daa 334
d6b9496a
VZ
335 // we can pass the messages to the previous log target (we're in this mode by
336 // default: we collect all messages in the window, but also let the default
337 // processing take place)
338 void PassMessages(bool bDoPass) { m_bPassMessages = bDoPass; }
2283a22c 339
d6b9496a 340 // base class virtuals
f6bcfd97 341 // we don't need it ourselves, but we pass it to the previous logger
d6b9496a 342 virtual void Flush();
fe7b1156 343
d6b9496a 344 // overridables
f6bcfd97
BP
345 // called immediately after the log frame creation allowing for
346 // any extra initializations
d6b9496a 347 virtual void OnFrameCreate(wxFrame *frame);
f6bcfd97
BP
348 // called if the user closes the window interactively, will not be
349 // called if it is destroyed for another reason (such as when program
350 // exits) - return TRUE from here to allow the frame to close, FALSE
351 // to prevent this from happening
352 virtual bool OnFrameClose(wxFrame *frame);
353 // called right before the log frame is going to be deleted: will
354 // always be called unlike OnFrameClose()
d6b9496a 355 virtual void OnFrameDelete(wxFrame *frame);
fe7b1156 356
9ef3052c 357protected:
9e3d3318
OK
358 virtual void DoLog(wxLogLevel level, const wxChar *szString, time_t t);
359 virtual void DoLogString(const wxChar *szString, time_t t);
06db8ebd 360
9ef3052c 361private:
d6b9496a
VZ
362 bool m_bPassMessages; // pass messages to m_pOldLog?
363 wxLog *m_pOldLog; // previous log target
364 wxLogFrame *m_pLogFrame; // the log frame
9ef3052c
VZ
365};
366
e90c1d2a 367#endif // wxUSE_GUI
03f38c58 368
c801d85f
KB
369// ----------------------------------------------------------------------------
370// /dev/null log target: suppress logging until this object goes out of scope
371// ----------------------------------------------------------------------------
372
373// example of usage:
374/*
d6b9496a
VZ
375 void Foo() {
376 wxFile file;
c801d85f 377
d6b9496a
VZ
378// wxFile.Open() normally complains if file can't be opened, we don't want it
379wxLogNull logNo;
380if ( !file.Open("bar") )
381... process error ourselves ...
c801d85f 382
d6b9496a 383// ~wxLogNull called, old log sink restored
c801d85f 384}
d6b9496a 385 */
c801d85f
KB
386class WXDLLEXPORT wxLogNull
387{
388public:
d6b9496a
VZ
389 wxLogNull() { m_flagOld = wxLog::EnableLogging(FALSE); }
390 ~wxLogNull() { (void)wxLog::EnableLogging(m_flagOld); }
c801d85f
KB
391
392private:
d6b9496a 393 bool m_flagOld; // the previous value of the wxLog::ms_doLog
c801d85f
KB
394};
395
396// ============================================================================
397// global functions
398// ============================================================================
399
400// ----------------------------------------------------------------------------
401// Log functions should be used by application instead of stdio, iostream &c
402// for log messages for easy redirection
403// ----------------------------------------------------------------------------
404
88ac883a
VZ
405// are we in 'verbose' mode?
406// (note that it's often handy to change this var manually from the
407// debugger, thus enabling/disabling verbose reporting for some
408// parts of the program only)
409WXDLLEXPORT_DATA(extern bool) g_bVerbose;
410
411// ----------------------------------------------------------------------------
412// get error code/error message from system in a portable way
413// ----------------------------------------------------------------------------
414
415// return the last system error code
416WXDLLEXPORT unsigned long wxSysErrorCode();
417// return the error message for given (or last if 0) error code
418WXDLLEXPORT const wxChar* wxSysErrorMsg(unsigned long nErrCode = 0);
419
c801d85f
KB
420// define wxLog<level>
421// -------------------
422
c801d85f 423#define DECLARE_LOG_FUNCTION(level) \
9e3d3318 424extern void WXDLLEXPORT wxLog##level(const wxChar *szFormat, ...)
a1530845 425#define DECLARE_LOG_FUNCTION2(level, arg1) \
9e3d3318 426extern void WXDLLEXPORT wxLog##level(arg1, const wxChar *szFormat, ...)
a1530845 427
88ac883a
VZ
428#else // !wxUSE_LOG
429
430// log functions do nothing at all
431#define DECLARE_LOG_FUNCTION(level) \
546db2a8 432inline void WXDLLEXPORT wxLog##level(const wxChar *szFormat, ...) {}
88ac883a 433#define DECLARE_LOG_FUNCTION2(level, arg1) \
546db2a8 434inline void WXDLLEXPORT wxLog##level(arg1, const wxChar *szFormat, ...) {}
88ac883a
VZ
435
436#endif // wxUSE_LOG/!wxUSE_LOG
c801d85f 437
88ac883a
VZ
438// a generic function for all levels (level is passes as parameter)
439DECLARE_LOG_FUNCTION2(Generic, wxLogLevel level);
c801d85f 440
88ac883a
VZ
441// one function per each level
442DECLARE_LOG_FUNCTION(FatalError);
443DECLARE_LOG_FUNCTION(Error);
444DECLARE_LOG_FUNCTION(Warning);
445DECLARE_LOG_FUNCTION(Message);
446DECLARE_LOG_FUNCTION(Info);
447DECLARE_LOG_FUNCTION(Verbose);
470b7da3 448
88ac883a
VZ
449// this function sends the log message to the status line of the top level
450// application frame, if any
451DECLARE_LOG_FUNCTION(Status);
470b7da3 452
88ac883a
VZ
453// this one is the same as previous except that it allows to explicitly
454// specify the frame to which the output should go
455DECLARE_LOG_FUNCTION2(Status, wxFrame *pFrame);
c801d85f 456
88ac883a
VZ
457// additional one: as wxLogError, but also logs last system call error code
458// and the corresponding error message if available
459DECLARE_LOG_FUNCTION(SysError);
c801d85f 460
88ac883a
VZ
461// and another one which also takes the error code (for those broken APIs
462// that don't set the errno (like registry APIs in Win32))
463DECLARE_LOG_FUNCTION2(SysError, long lErrCode);
464
465// debug functions do nothing in release mode
b2aef89b 466#ifdef __WXDEBUG__
d6b9496a
VZ
467 DECLARE_LOG_FUNCTION(Debug);
468
469 // first king of LogTrace is uncoditional: it doesn't check the level,
470 DECLARE_LOG_FUNCTION(Trace);
471
472 // this second version will only log the message if the mask had been
473 // added to the list of masks with AddTraceMask()
f6bcfd97 474 DECLARE_LOG_FUNCTION2(Trace, const wxChar *mask);
9ef3052c 475
d6b9496a
VZ
476 // the last one does nothing if all of level bits are not set
477 // in wxLog::GetActive()->GetTraceMask() - it's deprecated in favour of
478 // string identifiers
479 DECLARE_LOG_FUNCTION2(Trace, wxTraceMask mask);
9ef3052c 480#else //!debug
d6b9496a 481 // these functions do nothing in release builds
9e3d3318
OK
482 inline void wxLogDebug(const wxChar *, ...) { }
483 inline void wxLogTrace(const wxChar *, ...) { }
484 inline void wxLogTrace(wxTraceMask, const wxChar *, ...) { }
485 inline void wxLogTrace(const wxChar *, const wxChar *, ...) { }
88ac883a 486#endif // debug/!debug
c801d85f 487
88ac883a
VZ
488// ----------------------------------------------------------------------------
489// debug only logging functions: use them with API name and error code
490// ----------------------------------------------------------------------------
c801d85f 491
9e3d3318 492#ifndef __TFILE__
e90c1d2a 493 #define __XFILE__(x) Tx)
88ac883a 494 #define __TFILE__ __XFILE__(__FILE__)
9e3d3318
OK
495#endif
496
e90babdf 497#ifdef __WXDEBUG__
42e69d6b
VZ
498 // make life easier for people using VC++ IDE: clicking on the message
499 // will take us immediately to the place of the failed API
500#ifdef __VISUALC__
4b7f2165
VZ
501 #define wxLogApiError(api, rc) \
502 wxLogDebug(wxT("%s(%d): '%s' failed with error 0x%08lx (%s)."), \
f6bcfd97 503 __TFILE__, __LINE__, api, \
42e69d6b
VZ
504 rc, wxSysErrorMsg(rc))
505#else // !VC++
4b7f2165
VZ
506 #define wxLogApiError(api, rc) \
507 wxLogDebug(wxT("In file %s at line %d: '%s' failed with " \
508 "error 0x%08lx (%s)."), \
f6bcfd97 509 __TFILE__, __LINE__, api, \
42e69d6b
VZ
510 rc, wxSysErrorMsg(rc))
511#endif // VC++/!VC++
512
513 #define wxLogLastError(api) wxLogApiError(api, wxSysErrorCode())
514
c801d85f 515#else //!debug
9e3d3318
OK
516 inline void wxLogApiError(const wxChar *, long) { }
517 inline void wxLogLastError(const wxChar *) { }
c801d85f
KB
518#endif //debug/!debug
519
34138703 520#endif // _WX_LOG_H_