]> git.saurik.com Git - wxWidgets.git/blame_incremental - include/wx/log.h
Fixed to work with the new wxMacControl system.
[wxWidgets.git] / include / wx / log.h
... / ...
CommitLineData
1/////////////////////////////////////////////////////////////////////////////
2// Name: wx/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 licence
10/////////////////////////////////////////////////////////////////////////////
11
12#ifndef _WX_LOG_H_
13#define _WX_LOG_H_
14
15#if defined(__GNUG__) && !defined(NO_GCC_PRAGMA)
16 #pragma interface "log.h"
17#endif
18
19#include "wx/defs.h"
20
21// ----------------------------------------------------------------------------
22// common constants for use in wxUSE_LOG/!wxUSE_LOG
23// ----------------------------------------------------------------------------
24
25// the trace masks have been superceded by symbolic trace constants, they're
26// for compatibility only andwill be removed soon - do NOT use them
27
28// meaning of different bits of the trace mask (which allows selectively
29// enable/disable some trace messages)
30#define wxTraceMemAlloc 0x0001 // trace memory allocation (new/delete)
31#define wxTraceMessages 0x0002 // trace window messages/X callbacks
32#define wxTraceResAlloc 0x0004 // trace GDI resource allocation
33#define wxTraceRefCount 0x0008 // trace various ref counting operations
34
35#ifdef __WXMSW__
36 #define wxTraceOleCalls 0x0100 // OLE interface calls
37#endif
38
39// ----------------------------------------------------------------------------
40// types
41// ----------------------------------------------------------------------------
42
43// NB: these types are needed even if wxUSE_LOG == 0
44typedef unsigned long wxTraceMask;
45typedef unsigned long wxLogLevel;
46
47// ----------------------------------------------------------------------------
48// headers
49// ----------------------------------------------------------------------------
50
51#include "wx/string.h"
52
53#if wxUSE_LOG
54
55#include "wx/arrstr.h"
56
57#ifndef __WXWINCE__
58 #include <time.h> // for time_t
59#endif
60
61#include "wx/dynarray.h"
62
63#ifndef wxUSE_LOG_DEBUG
64# ifdef __WXDEBUG__
65# define wxUSE_LOG_DEBUG 1
66# else // !__WXDEBUG__
67# define wxUSE_LOG_DEBUG 0
68# endif
69#endif
70
71// ----------------------------------------------------------------------------
72// forward declarations
73// ----------------------------------------------------------------------------
74
75#if wxUSE_GUI
76 class WXDLLIMPEXP_CORE wxTextCtrl;
77 class WXDLLIMPEXP_CORE wxLogFrame;
78 class WXDLLIMPEXP_CORE wxFrame;
79#endif // wxUSE_GUI
80
81// ----------------------------------------------------------------------------
82// constants
83// ----------------------------------------------------------------------------
84
85// different standard log levels (you may also define your own)
86enum
87{
88 wxLOG_FatalError, // program can't continue, abort immediately
89 wxLOG_Error, // a serious error, user must be informed about it
90 wxLOG_Warning, // user is normally informed about it but may be ignored
91 wxLOG_Message, // normal message (i.e. normal output of a non GUI app)
92 wxLOG_Status, // informational: might go to the status line of GUI app
93 wxLOG_Info, // informational message (a.k.a. 'Verbose')
94 wxLOG_Debug, // never shown to the user, disabled in release mode
95 wxLOG_Trace, // trace messages are also only enabled in debug mode
96 wxLOG_Progress, // used for progress indicator (not yet)
97 wxLOG_User = 100, // user defined levels start here
98 wxLOG_Max = 10000
99};
100
101// symbolic trace masks - wxLogTrace("foo", "some trace message...") will be
102// discarded unless the string "foo" has been added to the list of allowed
103// ones with AddTraceMask()
104
105#define wxTRACE_MemAlloc wxT("memalloc") // trace memory allocation (new/delete)
106#define wxTRACE_Messages wxT("messages") // trace window messages/X callbacks
107#define wxTRACE_ResAlloc wxT("resalloc") // trace GDI resource allocation
108#define wxTRACE_RefCount wxT("refcount") // trace various ref counting operations
109
110#ifdef __WXMSW__
111 #define wxTRACE_OleCalls wxT("ole") // OLE interface calls
112#endif
113
114#include "wx/iosfwrap.h"
115
116// ----------------------------------------------------------------------------
117// derive from this class to redirect (or suppress, or ...) log messages
118// normally, only a single instance of this class exists but it's not enforced
119// ----------------------------------------------------------------------------
120
121class WXDLLIMPEXP_BASE wxLog
122{
123public:
124 // ctor
125 wxLog();
126
127 // Internal buffer.
128
129 // Allow replacement of the fixed size static buffer with
130 // a user allocated one. Pass in NULL to restore the
131 // built in static buffer.
132 static wxChar *SetLogBuffer( wxChar *buf, size_t size = 0 );
133
134 // these functions allow to completely disable all log messages
135
136 // is logging disabled now?
137 static bool IsEnabled() { return ms_doLog; }
138
139 // change the flag state, return the previous one
140 static bool EnableLogging(bool doIt = true)
141 { bool doLogOld = ms_doLog; ms_doLog = doIt; return doLogOld; }
142
143 // static sink function - see DoLog() for function to overload in the
144 // derived classes
145 static void OnLog(wxLogLevel level, const wxChar *szString, time_t t)
146 {
147 if ( IsEnabled() && ms_logLevel >= level )
148 {
149 wxLog *pLogger = GetActiveTarget();
150 if ( pLogger )
151 pLogger->DoLog(level, szString, t);
152 }
153 }
154
155 // message buffering
156
157 // flush shows all messages if they're not logged immediately (FILE
158 // and iostream logs don't need it, but wxGuiLog does to avoid showing
159 // 17 modal dialogs one after another)
160 virtual void Flush();
161
162 // flush the active target if any
163 static void FlushActive()
164 {
165 if ( !ms_suspendCount )
166 {
167 wxLog *log = GetActiveTarget();
168 if ( log )
169 log->Flush();
170 }
171 }
172
173 // only one sink is active at each moment
174 // get current log target, will call wxApp::CreateLogTarget() to
175 // create one if none exists
176 static wxLog *GetActiveTarget();
177
178 // change log target, pLogger may be NULL
179 static wxLog *SetActiveTarget(wxLog *pLogger);
180
181 // suspend the message flushing of the main target until the next call
182 // to Resume() - this is mainly for internal use (to prevent wxYield()
183 // from flashing the messages)
184 static void Suspend() { ms_suspendCount++; }
185
186 // must be called for each Suspend()!
187 static void Resume() { ms_suspendCount--; }
188
189 // functions controlling the default wxLog behaviour
190 // verbose mode is activated by standard command-line '-verbose'
191 // option
192 static void SetVerbose(bool bVerbose = true) { ms_bVerbose = bVerbose; }
193
194 // Set log level. Log messages with level > logLevel will not be logged.
195 static void SetLogLevel(wxLogLevel logLevel) { ms_logLevel = logLevel; }
196
197 // should GetActiveTarget() try to create a new log object if the
198 // current is NULL?
199 static void DontCreateOnDemand();
200
201 // trace mask (see wxTraceXXX constants for details)
202 static void SetTraceMask(wxTraceMask ulMask) { ms_ulTraceMask = ulMask; }
203
204 // add string trace mask
205 static void AddTraceMask(const wxString& str)
206 { ms_aTraceMasks.push_back(str); }
207
208 // add string trace mask
209 static void RemoveTraceMask(const wxString& str);
210
211 // remove all string trace masks
212 static void ClearTraceMasks();
213
214 // get string trace masks
215 static const wxArrayString &GetTraceMasks() { return ms_aTraceMasks; }
216
217 // sets the timestamp string: this is used as strftime() format string
218 // for the log targets which add time stamps to the messages - set it
219 // to NULL to disable time stamping completely.
220 static void SetTimestamp(const wxChar *ts) { ms_timestamp = ts; }
221
222
223 // accessors
224
225 // gets the verbose status
226 static bool GetVerbose() { return ms_bVerbose; }
227
228 // get trace mask
229 static wxTraceMask GetTraceMask() { return ms_ulTraceMask; }
230
231 // is this trace mask in the list?
232 static bool IsAllowedTraceMask(const wxChar *mask);
233
234 // return the current loglevel limit
235 static wxLogLevel GetLogLevel() { return ms_logLevel; }
236
237 // get the current timestamp format string (may be NULL)
238 static const wxChar *GetTimestamp() { return ms_timestamp; }
239
240
241 // helpers
242
243 // put the time stamp into the string if ms_timestamp != NULL (don't
244 // change it otherwise)
245 static void TimeStamp(wxString *str);
246
247 // make dtor virtual for all derived classes
248 virtual ~wxLog() { }
249
250
251 // this method exists for backwards compatibility only, don't use
252 bool HasPendingMessages() const { return true; }
253
254protected:
255 // the logging functions that can be overriden
256
257 // default DoLog() prepends the time stamp and a prefix corresponding
258 // to the message to szString and then passes it to DoLogString()
259 virtual void DoLog(wxLogLevel level, const wxChar *szString, time_t t);
260
261 // default DoLogString does nothing but is not pure virtual because if
262 // you override DoLog() you might not need it at all
263 virtual void DoLogString(const wxChar *szString, time_t t);
264
265private:
266 // static variables
267 // ----------------
268
269 static wxLog *ms_pLogger; // currently active log sink
270 static bool ms_doLog; // false => all logging disabled
271 static bool ms_bAutoCreate; // create new log targets on demand?
272 static bool ms_bVerbose; // false => ignore LogInfo messages
273
274 static wxLogLevel ms_logLevel; // limit logging to levels <= ms_logLevel
275
276 static size_t ms_suspendCount; // if positive, logs are not flushed
277
278 // format string for strftime(), if NULL, time stamping log messages is
279 // disabled
280 static const wxChar *ms_timestamp;
281
282 static wxTraceMask ms_ulTraceMask; // controls wxLogTrace behaviour
283 static wxArrayString ms_aTraceMasks; // more powerful filter for wxLogTrace
284};
285
286// ----------------------------------------------------------------------------
287// "trivial" derivations of wxLog
288// ----------------------------------------------------------------------------
289
290// log everything to a "FILE *", stderr by default
291class WXDLLIMPEXP_BASE wxLogStderr : public wxLog
292{
293 DECLARE_NO_COPY_CLASS(wxLogStderr)
294
295public:
296 // redirect log output to a FILE
297 wxLogStderr(FILE *fp = (FILE *) NULL);
298
299protected:
300 // implement sink function
301 virtual void DoLogString(const wxChar *szString, time_t t);
302
303 FILE *m_fp;
304};
305
306#if wxUSE_STD_IOSTREAM
307
308// log everything to an "ostream", cerr by default
309class WXDLLIMPEXP_BASE wxLogStream : public wxLog
310{
311public:
312 // redirect log output to an ostream
313 wxLogStream(wxSTD ostream *ostr = (wxSTD ostream *) NULL);
314
315protected:
316 // implement sink function
317 virtual void DoLogString(const wxChar *szString, time_t t);
318
319 // using ptr here to avoid including <iostream.h> from this file
320 wxSTD ostream *m_ostr;
321};
322
323#endif // wxUSE_STD_IOSTREAM
324
325// ----------------------------------------------------------------------------
326// /dev/null log target: suppress logging until this object goes out of scope
327// ----------------------------------------------------------------------------
328
329// example of usage:
330/*
331 void Foo()
332 {
333 wxFile file;
334
335 // wxFile.Open() normally complains if file can't be opened, we don't
336 // want it
337 wxLogNull logNo;
338
339 if ( !file.Open("bar") )
340 ... process error ourselves ...
341
342 // ~wxLogNull called, old log sink restored
343 }
344 */
345class WXDLLIMPEXP_BASE wxLogNull
346{
347public:
348 wxLogNull() : m_flagOld(wxLog::EnableLogging(false)) { }
349 ~wxLogNull() { (void)wxLog::EnableLogging(m_flagOld); }
350
351private:
352 bool m_flagOld; // the previous value of the wxLog::ms_doLog
353};
354
355// ----------------------------------------------------------------------------
356// chaining log target: installs itself as a log target and passes all
357// messages to the real log target given to it in the ctor but also forwards
358// them to the previously active one
359//
360// note that you don't have to call SetActiveTarget() with this class, it
361// does it itself in its ctor
362// ----------------------------------------------------------------------------
363
364class WXDLLIMPEXP_BASE wxLogChain : public wxLog
365{
366public:
367 wxLogChain(wxLog *logger);
368 virtual ~wxLogChain();
369
370 // change the new log target
371 void SetLog(wxLog *logger);
372
373 // this can be used to temporarily disable (and then reenable) passing
374 // messages to the old logger (by default we do pass them)
375 void PassMessages(bool bDoPass) { m_bPassMessages = bDoPass; }
376
377 // are we passing the messages to the previous log target?
378 bool IsPassingMessages() const { return m_bPassMessages; }
379
380 // return the previous log target (may be NULL)
381 wxLog *GetOldLog() const { return m_logOld; }
382
383 // override base class version to flush the old logger as well
384 virtual void Flush();
385
386protected:
387 // pass the chain to the old logger if needed
388 virtual void DoLog(wxLogLevel level, const wxChar *szString, time_t t);
389
390private:
391 // the current log target
392 wxLog *m_logNew;
393
394 // the previous log target
395 wxLog *m_logOld;
396
397 // do we pass the messages to the old logger?
398 bool m_bPassMessages;
399
400 DECLARE_NO_COPY_CLASS(wxLogChain)
401};
402
403// a chain log target which uses itself as the new logger
404class WXDLLIMPEXP_BASE wxLogPassThrough : public wxLogChain
405{
406public:
407 wxLogPassThrough();
408
409private:
410 DECLARE_NO_COPY_CLASS(wxLogPassThrough)
411};
412
413#if wxUSE_GUI
414 // include GUI log targets:
415 #include "wx/generic/logg.h"
416#endif // wxUSE_GUI
417
418// ============================================================================
419// global functions
420// ============================================================================
421
422// ----------------------------------------------------------------------------
423// Log functions should be used by application instead of stdio, iostream &c
424// for log messages for easy redirection
425// ----------------------------------------------------------------------------
426
427// ----------------------------------------------------------------------------
428// get error code/error message from system in a portable way
429// ----------------------------------------------------------------------------
430
431// return the last system error code
432WXDLLIMPEXP_BASE unsigned long wxSysErrorCode();
433
434// return the error message for given (or last if 0) error code
435WXDLLIMPEXP_BASE const wxChar* wxSysErrorMsg(unsigned long nErrCode = 0);
436
437// ----------------------------------------------------------------------------
438// define wxLog<level>
439// ----------------------------------------------------------------------------
440
441#define DECLARE_LOG_FUNCTION(level) \
442extern void WXDLLIMPEXP_BASE wxVLog##level(const wxChar *szFormat, \
443 va_list argptr); \
444extern void WXDLLIMPEXP_BASE wxLog##level(const wxChar *szFormat, \
445 ...) ATTRIBUTE_PRINTF_1
446#define DECLARE_LOG_FUNCTION2_EXP(level, arg, expdecl) \
447extern void expdecl wxVLog##level(arg, const wxChar *szFormat, \
448 va_list argptr); \
449extern void expdecl wxLog##level(arg, const wxChar *szFormat, \
450 ...) ATTRIBUTE_PRINTF_2
451#else // !wxUSE_LOG
452
453// log functions do nothing at all
454#define DECLARE_LOG_FUNCTION(level) \
455inline void wxVLog##level(const wxChar *szFormat, \
456 va_list argptr) { } \
457inline void wxLog##level(const wxChar *szFormat, ...) { }
458#define DECLARE_LOG_FUNCTION2_EXP(level, arg, expdecl) \
459inline void wxVLog##level(arg, const wxChar *szFormat, \
460 va_list argptr) {} \
461inline void wxLog##level(arg, const wxChar *szFormat, ...) { }
462
463// Empty Class to fake wxLogNull
464class WXDLLIMPEXP_BASE wxLogNull
465{
466public:
467 wxLogNull() { }
468};
469
470// Dummy macros to replace some functions.
471#define wxSysErrorCode() (unsigned long)0
472#define wxSysErrorMsg( X ) (const wxChar*)NULL
473
474// Fake symbolic trace masks... for those that are used frequently
475#define wxTRACE_OleCalls wxEmptyString // OLE interface calls
476
477#endif // wxUSE_LOG/!wxUSE_LOG
478#define DECLARE_LOG_FUNCTION2(level, arg) \
479 DECLARE_LOG_FUNCTION2_EXP(level, arg, WXDLLIMPEXP_BASE)
480
481
482// a generic function for all levels (level is passes as parameter)
483DECLARE_LOG_FUNCTION2(Generic, wxLogLevel level);
484
485// one function per each level
486DECLARE_LOG_FUNCTION(FatalError);
487DECLARE_LOG_FUNCTION(Error);
488DECLARE_LOG_FUNCTION(Warning);
489DECLARE_LOG_FUNCTION(Message);
490DECLARE_LOG_FUNCTION(Info);
491DECLARE_LOG_FUNCTION(Verbose);
492
493// this function sends the log message to the status line of the top level
494// application frame, if any
495DECLARE_LOG_FUNCTION(Status);
496
497#if wxUSE_GUI
498 // this one is the same as previous except that it allows to explicitly
499 class wxFrame;
500 // specify the frame to which the output should go
501 DECLARE_LOG_FUNCTION2_EXP(Status, wxFrame *pFrame, WXDLLIMPEXP_CORE);
502#endif // wxUSE_GUI
503
504// additional one: as wxLogError, but also logs last system call error code
505// and the corresponding error message if available
506DECLARE_LOG_FUNCTION(SysError);
507
508// and another one which also takes the error code (for those broken APIs
509// that don't set the errno (like registry APIs in Win32))
510DECLARE_LOG_FUNCTION2(SysError, long lErrCode);
511
512// debug functions do nothing in release mode
513#if wxUSE_LOG_DEBUG
514 DECLARE_LOG_FUNCTION(Debug);
515
516 // there is no more unconditional LogTrace: it is not different from
517 // LogDebug and it creates overload ambiguities
518 //DECLARE_LOG_FUNCTION(Trace);
519
520 // this version only logs the message if the mask had been added to the
521 // list of masks with AddTraceMask()
522 DECLARE_LOG_FUNCTION2(Trace, const wxChar *mask);
523
524 // and this one does nothing if all of level bits are not set in
525 // wxLog::GetActive()->GetTraceMask() -- it's deprecated in favour of
526 // string identifiers
527 DECLARE_LOG_FUNCTION2(Trace, wxTraceMask mask);
528#else //!debug
529 // these functions do nothing in release builds
530 inline void wxVLogDebug(const wxChar *, va_list) { }
531 inline void wxLogDebug(const wxChar *, ...) { }
532 inline void wxVLogTrace(wxTraceMask, const wxChar *, va_list) { }
533 inline void wxLogTrace(wxTraceMask, const wxChar *, ...) { }
534 inline void wxVLogTrace(const wxChar *, const wxChar *, va_list) { }
535 inline void wxLogTrace(const wxChar *, const wxChar *, ...) { }
536#endif // debug/!debug
537
538// wxLogFatalError helper: show the (fatal) error to the user in a safe way,
539// i.e. without using wxMessageBox() for example because it could crash
540void WXDLLIMPEXP_BASE
541wxSafeShowMessage(const wxString& title, const wxString& text);
542
543// ----------------------------------------------------------------------------
544// debug only logging functions: use them with API name and error code
545// ----------------------------------------------------------------------------
546
547#ifdef __WXDEBUG__
548 // make life easier for people using VC++ IDE: clicking on the message
549 // will take us immediately to the place of the failed API
550#ifdef __VISUALC__
551 #define wxLogApiError(api, rc) \
552 wxLogDebug(wxT("%s(%d): '%s' failed with error 0x%08lx (%s)."), \
553 __TFILE__, __LINE__, api, \
554 (long)rc, wxSysErrorMsg(rc))
555#else // !VC++
556 #define wxLogApiError(api, rc) \
557 wxLogDebug(wxT("In file %s at line %d: '%s' failed with ") \
558 wxT("error 0x%08lx (%s)."), \
559 __TFILE__, __LINE__, api, \
560 (long)rc, wxSysErrorMsg(rc))
561#endif // VC++/!VC++
562
563 #define wxLogLastError(api) wxLogApiError(api, wxSysErrorCode())
564
565#else //!debug
566 inline void wxLogApiError(const wxChar *, long) { }
567 inline void wxLogLastError(const wxChar *) { }
568#endif //debug/!debug
569
570// wxCocoa has additiional trace masks
571#if defined(__WXCOCOA__)
572#include "wx/cocoa/log.h"
573#endif
574
575#endif // _WX_LOG_H_
576