Use /bin/echo for creation of Mac OS X PkgInfo files.
[wxWidgets.git] / include / wx / log.h
CommitLineData
c801d85f 1/////////////////////////////////////////////////////////////////////////////
8ca28fb7 2// Name: wx/log.h
c801d85f
KB
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>
65571936 9// Licence: wxWindows licence
c801d85f
KB
10/////////////////////////////////////////////////////////////////////////////
11
886dd7d2
VZ
12#ifndef _WX_LOG_H_
13#define _WX_LOG_H_
c801d85f 14
df5168c4 15#include "wx/defs.h"
38830220 16
0b4f47a3 17// ----------------------------------------------------------------------------
34085a0d 18// types
0b4f47a3
DS
19// ----------------------------------------------------------------------------
20
34085a0d
VZ
21// NB: this is needed even if wxUSE_LOG == 0
22typedef unsigned long wxLogLevel;
0b4f47a3 23
34085a0d
VZ
24// the trace masks have been superseded by symbolic trace constants, they're
25// for compatibility only and will be removed soon - do NOT use them
26#if WXWIN_COMPATIBILITY_2_8
27 #define wxTraceMemAlloc 0x0001 // trace memory allocation (new/delete)
28 #define wxTraceMessages 0x0002 // trace window messages/X callbacks
29 #define wxTraceResAlloc 0x0004 // trace GDI resource allocation
30 #define wxTraceRefCount 0x0008 // trace various ref counting operations
0b4f47a3 31
34085a0d
VZ
32 #ifdef __WXMSW__
33 #define wxTraceOleCalls 0x0100 // OLE interface calls
34 #endif
546db2a8 35
34085a0d
VZ
36 typedef unsigned long wxTraceMask;
37#endif // WXWIN_COMPATIBILITY_2_8
546db2a8
VZ
38
39// ----------------------------------------------------------------------------
40// headers
41// ----------------------------------------------------------------------------
42
b6e4e44a 43#include "wx/string.h"
c9f78968 44#include "wx/strvararg.h"
b6e4e44a 45
b0d58b0e
VZ
46// ----------------------------------------------------------------------------
47// forward declarations
48// ----------------------------------------------------------------------------
49
50class WXDLLIMPEXP_FWD_BASE wxObject;
51
52#if wxUSE_GUI
53 class WXDLLIMPEXP_FWD_CORE wxFrame;
54#endif // wxUSE_GUI
55
1782be31
VZ
56#if wxUSE_LOG
57
1782be31
VZ
58#include "wx/arrstr.h"
59
0e0126c2 60#ifndef __WXWINCE__
1782be31 61 #include <time.h> // for time_t
0e0126c2 62#endif
c30aaf75
VZ
63
64#include "wx/dynarray.h"
af588446 65#include "wx/hashmap.h"
d6b9496a 66
bc73d5ae
VZ
67#if wxUSE_THREADS
68 #include "wx/thread.h"
69#endif // wxUSE_THREADS
70
711f12ef 71// wxUSE_LOG_DEBUG enables the debug log messages
edc73852 72#ifndef wxUSE_LOG_DEBUG
23fb9bf5
VZ
73 #if wxDEBUG_LEVEL
74 #define wxUSE_LOG_DEBUG 1
75 #else // !wxDEBUG_LEVEL
76 #define wxUSE_LOG_DEBUG 0
77 #endif
edc73852
RD
78#endif
79
711f12ef
VZ
80// wxUSE_LOG_TRACE enables the trace messages, they are disabled by default
81#ifndef wxUSE_LOG_TRACE
9d2214dd 82 #if wxDEBUG_LEVEL
711f12ef 83 #define wxUSE_LOG_TRACE 1
9d2214dd 84 #else // !wxDEBUG_LEVEL
711f12ef
VZ
85 #define wxUSE_LOG_TRACE 0
86 #endif
87#endif // wxUSE_LOG_TRACE
88
c602c59b
VZ
89// wxLOG_COMPONENT identifies the component which generated the log record and
90// can be #define'd to a user-defined value when compiling the user code to use
91// component-based filtering (see wxLog::SetComponentLevel())
92#ifndef wxLOG_COMPONENT
93 // this is a variable and not a macro in order to allow the user code to
94 // just #define wxLOG_COMPONENT without #undef'ining it first
95 extern WXDLLIMPEXP_DATA_BASE(const char *) wxLOG_COMPONENT;
96
97 #ifdef WXBUILDING
98 #define wxLOG_COMPONENT "wx"
99 #endif
100#endif
101
9ef3052c
VZ
102// ----------------------------------------------------------------------------
103// constants
104// ----------------------------------------------------------------------------
105
106// different standard log levels (you may also define your own)
90adbcca 107enum wxLogLevelValues
9ef3052c 108{
d6b9496a
VZ
109 wxLOG_FatalError, // program can't continue, abort immediately
110 wxLOG_Error, // a serious error, user must be informed about it
111 wxLOG_Warning, // user is normally informed about it but may be ignored
112 wxLOG_Message, // normal message (i.e. normal output of a non GUI app)
d6b9496a 113 wxLOG_Status, // informational: might go to the status line of GUI app
edc73852 114 wxLOG_Info, // informational message (a.k.a. 'Verbose')
d6b9496a
VZ
115 wxLOG_Debug, // never shown to the user, disabled in release mode
116 wxLOG_Trace, // trace messages are also only enabled in debug mode
117 wxLOG_Progress, // used for progress indicator (not yet)
edc73852 118 wxLOG_User = 100, // user defined levels start here
65ca8c0b 119 wxLOG_Max = 10000
9ef3052c
VZ
120};
121
d6b9496a
VZ
122// symbolic trace masks - wxLogTrace("foo", "some trace message...") will be
123// discarded unless the string "foo" has been added to the list of allowed
124// ones with AddTraceMask()
125
08298395
OK
126#define wxTRACE_MemAlloc wxT("memalloc") // trace memory allocation (new/delete)
127#define wxTRACE_Messages wxT("messages") // trace window messages/X callbacks
128#define wxTRACE_ResAlloc wxT("resalloc") // trace GDI resource allocation
129#define wxTRACE_RefCount wxT("refcount") // trace various ref counting operations
d6b9496a
VZ
130
131#ifdef __WXMSW__
08298395 132 #define wxTRACE_OleCalls wxT("ole") // OLE interface calls
d6b9496a
VZ
133#endif
134
65f19af1 135#include "wx/iosfwrap.h"
470b7da3 136
bc73d5ae
VZ
137// ----------------------------------------------------------------------------
138// information about a log record, i.e. unit of log output
139// ----------------------------------------------------------------------------
140
af588446 141class wxLogRecordInfo
bc73d5ae 142{
af588446
VZ
143public:
144 // default ctor creates an uninitialized object
bc73d5ae
VZ
145 wxLogRecordInfo()
146 {
c602c59b 147 memset(this, 0, sizeof(*this));
af588446
VZ
148 }
149
150 // normal ctor, used by wxLogger specifies the location of the log
151 // statement; its time stamp and thread id are set up here
152 wxLogRecordInfo(const char *filename_,
153 int line_,
c602c59b
VZ
154 const char *func_,
155 const char *component_)
af588446
VZ
156 {
157 filename = filename_;
158 func = func_;
159 line = line_;
c602c59b 160 component = component_;
af588446
VZ
161
162 timestamp = time(NULL);
bc73d5ae
VZ
163
164#if wxUSE_THREADS
af588446 165 threadId = wxThread::GetCurrentId();
bc73d5ae 166#endif // wxUSE_THREADS
af588446
VZ
167
168 m_data = NULL;
169 }
170
171 // we need to define copy ctor and assignment operator because of m_data
172 wxLogRecordInfo(const wxLogRecordInfo& other)
173 {
174 Copy(other);
175 }
176
177 wxLogRecordInfo& operator=(const wxLogRecordInfo& other)
178 {
179 if ( &other != this )
180 {
181 delete m_data;
182 Copy(other);
183 }
184
185 return *this;
bc73d5ae
VZ
186 }
187
af588446
VZ
188 // dtor is non-virtual, this class is not meant to be derived from
189 ~wxLogRecordInfo()
190 {
191 delete m_data;
192 }
bc73d5ae
VZ
193
194
af588446
VZ
195 // the file name and line number of the file where the log record was
196 // generated, if available or NULL and 0 otherwise
197 const char *filename;
198 int line;
199
200 // the name of the function where the log record was generated (may be NULL
201 // if the compiler doesn't support __FUNCTION__)
202 const char *func;
203
c602c59b
VZ
204 // the name of the component which generated this message, may be NULL if
205 // not set (i.e. wxLOG_COMPONENT not defined)
206 const char *component;
207
bc73d5ae
VZ
208 // time of record generation
209 time_t timestamp;
210
211#if wxUSE_THREADS
212 // id of the thread which logged this record
213 wxThreadIdType threadId;
214#endif // wxUSE_THREADS
af588446
VZ
215
216
217 // store an arbitrary value in this record context
218 //
219 // wxWidgets always uses keys starting with "wx.", e.g. "wx.sys_error"
220 void StoreValue(const wxString& key, wxUIntPtr val)
221 {
222 if ( !m_data )
223 m_data = new ExtraData;
224
225 m_data->numValues[key] = val;
226 }
227
228 void StoreValue(const wxString& key, const wxString& val)
229 {
230 if ( !m_data )
231 m_data = new ExtraData;
232
233 m_data->strValues[key] = val;
234 }
235
236
237 // these functions retrieve the value of either numeric or string key,
238 // return false if not found
239 bool GetNumValue(const wxString& key, wxUIntPtr *val) const
240 {
241 if ( !m_data )
242 return false;
243
244 wxStringToNumHashMap::const_iterator it = m_data->numValues.find(key);
245 if ( it == m_data->numValues.end() )
246 return false;
247
248 *val = it->second;
249
250 return true;
251 }
252
253 bool GetStrValue(const wxString& key, wxString *val) const
254 {
255 if ( !m_data )
256 return false;
257
258 wxStringToStringHashMap::const_iterator it = m_data->strValues.find(key);
259 if ( it == m_data->strValues.end() )
260 return false;
261
262 *val = it->second;
263
264 return true;
265 }
266
267private:
268 void Copy(const wxLogRecordInfo& other)
269 {
c602c59b 270 memcpy(this, &other, sizeof(*this));
af588446
VZ
271 if ( other.m_data )
272 m_data = new ExtraData(*other.m_data);
273 }
274
275 // extra data associated with the log record: this is completely optional
276 // and can be used to pass information from the log function to the log
277 // sink (e.g. wxLogSysError() uses this to pass the error code)
278 struct ExtraData
279 {
280 wxStringToNumHashMap numValues;
281 wxStringToStringHashMap strValues;
282 };
283
284 // NULL if not used
285 ExtraData *m_data;
bc73d5ae
VZ
286};
287
af588446
VZ
288#define wxLOG_KEY_TRACE_MASK "wx.trace_mask"
289
232addd1
VZ
290// ----------------------------------------------------------------------------
291// log record: a unit of log output
292// ----------------------------------------------------------------------------
293
294struct wxLogRecord
295{
296 wxLogRecord(wxLogLevel level_,
297 const wxString& msg_,
298 const wxLogRecordInfo& info_)
299 : level(level_),
300 msg(msg_),
301 info(info_)
302 {
303 }
304
305 wxLogLevel level;
306 wxString msg;
307 wxLogRecordInfo info;
308};
309
4ffdb640
VZ
310// ----------------------------------------------------------------------------
311// Derive from this class to customize format of log messages.
312// ----------------------------------------------------------------------------
313
314class WXDLLIMPEXP_BASE wxLogFormatter
315{
316public:
317 // Default constructor.
318 wxLogFormatter() { }
319
320 // Trivial but virtual destructor for the base class.
321 virtual ~wxLogFormatter() { }
322
323
324 // Override this method to implement custom formatting of the given log
325 // record. The default implementation simply prepends a level-dependent
326 // prefix to the message and optionally adds a time stamp.
327 virtual wxString Format(wxLogLevel level,
328 const wxString& msg,
329 const wxLogRecordInfo& info) const;
330
331protected:
332 // Override this method to change just the time stamp formatting. It is
333 // called by default Format() implementation.
334 virtual wxString FormatTime(time_t t) const;
335};
336
337
c801d85f
KB
338// ----------------------------------------------------------------------------
339// derive from this class to redirect (or suppress, or ...) log messages
340// normally, only a single instance of this class exists but it's not enforced
c801d85f 341// ----------------------------------------------------------------------------
d6b9496a 342
bddd7a8d 343class WXDLLIMPEXP_BASE wxLog
c801d85f
KB
344{
345public:
d6b9496a 346 // ctor
4ffdb640 347 wxLog() : m_formatter(new wxLogFormatter) { }
bc73d5ae
VZ
348
349 // make dtor virtual for all derived classes
350 virtual ~wxLog();
351
d6b9496a 352
c602c59b
VZ
353 // log messages selection
354 // ----------------------
355
356 // these functions allow to completely disable all log messages or disable
53ff8df7
VZ
357 // log messages at level less important than specified for the current
358 // thread
d1b20379 359
ba3af101 360 // is logging enabled at all now?
53ff8df7
VZ
361 static bool IsEnabled()
362 {
363#if wxUSE_THREADS
364 if ( !wxThread::IsMain() )
365 return IsThreadLoggingEnabled();
366#endif // wxUSE_THREADS
367
368 return ms_doLog;
369 }
d1b20379
DS
370
371 // change the flag state, return the previous one
53ff8df7
VZ
372 static bool EnableLogging(bool enable = true)
373 {
374#if wxUSE_THREADS
375 if ( !wxThread::IsMain() )
376 return EnableThreadLogging(enable);
377#endif // wxUSE_THREADS
d6b9496a 378
53ff8df7
VZ
379 bool doLogOld = ms_doLog;
380 ms_doLog = enable;
381 return doLogOld;
382 }
c602c59b
VZ
383
384 // return the current global log level
385 static wxLogLevel GetLogLevel() { return ms_logLevel; }
386
387 // set global log level: messages with level > logLevel will not be logged
388 static void SetLogLevel(wxLogLevel logLevel) { ms_logLevel = logLevel; }
389
390 // set the log level for the given component
391 static void SetComponentLevel(const wxString& component, wxLogLevel level);
392
393 // return the effective log level for this component, falling back to
394 // parent component and to the default global log level if necessary
395 //
396 // NB: component argument is passed by value and not const reference in an
397 // attempt to encourage compiler to avoid an extra copy: as we modify
398 // the component internally, we'd create one anyhow and like this it
399 // can be avoided if the string is a temporary anyhow
400 static wxLogLevel GetComponentLevel(wxString component);
401
402
403 // is logging of messages from this component enabled at this level?
404 //
405 // usually always called with wxLOG_COMPONENT as second argument
406 static bool IsLevelEnabled(wxLogLevel level, wxString component)
407 {
408 return IsEnabled() && level <= GetComponentLevel(component);
409 }
410
411
412 // enable/disable messages at wxLOG_Verbose level (only relevant if the
413 // current log level is greater or equal to it)
414 //
415 // notice that verbose mode can be activated by the standard command-line
416 // '--verbose' option
417 static void SetVerbose(bool bVerbose = true) { ms_bVerbose = bVerbose; }
418
419 // check if verbose messages are enabled
420 static bool GetVerbose() { return ms_bVerbose; }
421
422
d6b9496a 423 // message buffering
c602c59b 424 // -----------------
d1b20379
DS
425
426 // flush shows all messages if they're not logged immediately (FILE
e55919d8 427 // and iostream logs don't need it, but wxLogGui does to avoid showing
d1b20379 428 // 17 modal dialogs one after another)
d6b9496a 429 virtual void Flush();
d6b9496a 430
acad886c
VZ
431 // flush the active target if any and also output any pending messages from
432 // background threads
433 static void FlushActive();
1ec5cbf3 434
acad886c
VZ
435 // only one sink is active at each moment get current log target, will call
436 // wxAppTraits::CreateLogTarget() to create one if none exists
d6b9496a 437 static wxLog *GetActiveTarget();
d1b20379 438
acad886c
VZ
439 // change log target, logger may be NULL
440 static wxLog *SetActiveTarget(wxLog *logger);
441
442#if wxUSE_THREADS
443 // change log target for the current thread only, shouldn't be called from
444 // the main thread as it doesn't use thread-specific log target
445 static wxLog *SetThreadActiveTarget(wxLog *logger);
446#endif // wxUSE_THREADS
d6b9496a 447
d1b20379
DS
448 // suspend the message flushing of the main target until the next call
449 // to Resume() - this is mainly for internal use (to prevent wxYield()
450 // from flashing the messages)
2ed3265e 451 static void Suspend() { ms_suspendCount++; }
d1b20379
DS
452
453 // must be called for each Suspend()!
2ed3265e
VZ
454 static void Resume() { ms_suspendCount--; }
455
d1b20379
DS
456 // should GetActiveTarget() try to create a new log object if the
457 // current is NULL?
36bd6902 458 static void DontCreateOnDemand();
d6b9496a 459
e94cd97d
DE
460 // Make GetActiveTarget() create a new log object again.
461 static void DoCreateOnDemand();
462
f9837791
VZ
463 // log the count of repeating messages instead of logging the messages
464 // multiple times
465 static void SetRepetitionCounting(bool bRepetCounting = true)
2e7f3845 466 { ms_bRepetCounting = bRepetCounting; }
f9837791
VZ
467
468 // gets duplicate counting status
469 static bool GetRepetitionCounting() { return ms_bRepetCounting; }
470
d1b20379 471 // add string trace mask
f96233d5 472 static void AddTraceMask(const wxString& str);
d1b20379
DS
473
474 // add string trace mask
d6b9496a 475 static void RemoveTraceMask(const wxString& str);
d1b20379
DS
476
477 // remove all string trace masks
36bd6902 478 static void ClearTraceMasks();
d1b20379 479
f96233d5
VZ
480 // get string trace masks: note that this is MT-unsafe if other threads can
481 // call AddTraceMask() concurrently
55e5154d 482 static const wxArrayString& GetTraceMasks();
d6b9496a 483
4ffdb640
VZ
484 // is this trace mask in the list?
485 static bool IsAllowedTraceMask(const wxString& mask);
486
487
488 // log formatting
489 // -----------------
490
491 // Change wxLogFormatter object used by wxLog to format the log messages.
492 //
493 // wxLog takes ownership of the pointer passed in but the caller is
494 // responsible for deleting the returned pointer.
495 wxLogFormatter* SetFormatter(wxLogFormatter* formatter);
496
497
498 // All the time stamp related functions below only work when the default
499 // wxLogFormatter is being used. Defining a custom formatter overrides them
500 // as it could use its own time stamp format or format messages without
501 // using time stamp at all.
502
503
7b1bf3ad
VZ
504 // sets the time stamp string format: this is used as strftime() format
505 // string for the log targets which add time stamps to the messages; set
506 // it to empty string to disable time stamping completely.
d993e05b 507 static void SetTimestamp(const wxString& ts) { ms_timestamp = ts; }
d2e1ef19 508
7b1bf3ad
VZ
509 // disable time stamping of log messages
510 static void DisableTimestamp() { SetTimestamp(wxEmptyString); }
511
edc73852 512
d1279c9a 513 // get the current timestamp format string (maybe empty)
d993e05b 514 static const wxString& GetTimestamp() { return ms_timestamp; }
d2e1ef19 515
edc73852 516
bc73d5ae
VZ
517
518 // helpers: all functions in this section are mostly for internal use only,
519 // don't call them from your code even if they are not formally deprecated
d1b20379 520
4ffdb640
VZ
521 // put the time stamp into the string if ms_timestamp is not empty (don't
522 // change it otherwise); the first overload uses the current time.
d2e1ef19 523 static void TimeStamp(wxString *str);
4ffdb640 524 static void TimeStamp(wxString *str, time_t t);
d2e1ef19 525
bc73d5ae
VZ
526 // these methods should only be called from derived classes DoLogRecord(),
527 // DoLogTextAtLevel() and DoLogText() implementations respectively and
528 // shouldn't be called directly, use logging functions instead
529 void LogRecord(wxLogLevel level,
530 const wxString& msg,
531 const wxLogRecordInfo& info)
efce878a 532 {
bc73d5ae 533 DoLogRecord(level, msg, info);
efce878a
VZ
534 }
535
bc73d5ae
VZ
536 void LogTextAtLevel(wxLogLevel level, const wxString& msg)
537 {
538 DoLogTextAtLevel(level, msg);
539 }
540
541 void LogText(const wxString& msg)
542 {
543 DoLogText(msg);
544 }
545
546 // this is a helper used by wxLogXXX() functions, don't call it directly
547 // and see DoLog() for function to overload in the derived classes
548 static void OnLog(wxLogLevel level,
549 const wxString& msg,
550 const wxLogRecordInfo& info);
551
552 // version called when no information about the location of the log record
553 // generation is available (but the time stamp is), it mainly exists for
554 // backwards compatibility, don't use it in new code
555 static void OnLog(wxLogLevel level, const wxString& msg, time_t t);
556
557 // a helper calling the above overload with current time
558 static void OnLog(wxLogLevel level, const wxString& msg)
559 {
560 OnLog(level, msg, time(NULL));
561 }
c801d85f 562
c801d85f 563
1ec5cbf3 564 // this method exists for backwards compatibility only, don't use
d1b20379 565 bool HasPendingMessages() const { return true; }
1ec5cbf3 566
2e7f3845
VZ
567#if WXWIN_COMPATIBILITY_2_6
568 // this function doesn't do anything any more, don't call it
d65e9d57
VZ
569 static wxDEPRECATED_INLINE(
570 wxChar *SetLogBuffer(wxChar *, size_t = 0), return NULL;
bc73d5ae
VZ
571 );
572#endif // WXWIN_COMPATIBILITY_2_6
2e7f3845 573
34085a0d
VZ
574 // don't use integer masks any more, use string trace masks instead
575#if WXWIN_COMPATIBILITY_2_8
d65e9d57 576 static wxDEPRECATED_INLINE( void SetTraceMask(wxTraceMask ulMask),
34085a0d 577 ms_ulTraceMask = ulMask; )
b356aa55
VZ
578
579 // this one can't be marked deprecated as it's used in our own wxLogger
580 // below but it still is deprecated and shouldn't be used
581 static wxTraceMask GetTraceMask() { return ms_ulTraceMask; }
34085a0d
VZ
582#endif // WXWIN_COMPATIBILITY_2_8
583
1ec5cbf3 584protected:
bc73d5ae
VZ
585 // the logging functions that can be overridden: DoLogRecord() is called
586 // for every "record", i.e. a unit of log output, to be logged and by
587 // default formats the message and passes it to DoLogTextAtLevel() which in
588 // turn passes it to DoLogText() by default
af588446 589
bc73d5ae
VZ
590 // override this method if you want to change message formatting or do
591 // dynamic filtering
592 virtual void DoLogRecord(wxLogLevel level,
593 const wxString& msg,
594 const wxLogRecordInfo& info);
595
596 // override this method to redirect output to different channels depending
597 // on its level only; if even the level doesn't matter, override
598 // DoLogText() instead
599 virtual void DoLogTextAtLevel(wxLogLevel level, const wxString& msg);
600
601 // this function is not pure virtual as it might not be needed if you do
602 // the logging in overridden DoLogRecord() or DoLogTextAtLevel() directly
603 // but if you do not override them in your derived class you must override
604 // this one as the default implementation of it simply asserts
605 virtual void DoLogText(const wxString& msg);
606
607
608 // the rest of the functions are for backwards compatibility only, don't
609 // use them in new code; if you're updating your existing code you need to
610 // switch to overriding DoLogRecord/Text() above (although as long as these
611 // functions exist, log classes using them will continue to work)
5a20d2ce 612#if WXWIN_COMPATIBILITY_2_8
5d88a6b5
VZ
613 wxDEPRECATED_BUT_USED_INTERNALLY(
614 virtual void DoLog(wxLogLevel level, const char *szString, time_t t)
615 );
616
617 wxDEPRECATED_BUT_USED_INTERNALLY(
618 virtual void DoLog(wxLogLevel level, const wchar_t *wzString, time_t t)
619 );
d1b20379 620
5a20d2ce 621 // these shouldn't be used by new code
bc73d5ae
VZ
622 wxDEPRECATED_BUT_USED_INTERNALLY_INLINE(
623 virtual void DoLogString(const char *WXUNUSED(szString),
624 time_t WXUNUSED(t)),
ae2070fb 625 wxEMPTY_PARAMETER_VALUE
bc73d5ae
VZ
626 )
627
628 wxDEPRECATED_BUT_USED_INTERNALLY_INLINE(
629 virtual void DoLogString(const wchar_t *WXUNUSED(wzString),
630 time_t WXUNUSED(t)),
ae2070fb 631 wxEMPTY_PARAMETER_VALUE
bc73d5ae 632 )
b99891b0
VZ
633#endif // WXWIN_COMPATIBILITY_2_8
634
c801d85f 635
2064113c 636 // log a message indicating the number of times the previous message was
bc73d5ae
VZ
637 // repeated if previous repetition counter is strictly positive, does
638 // nothing otherwise; return the old value of repetition counter
dbaa16de 639 unsigned LogLastRepeatIfNeeded();
f9837791 640
d6b9496a 641private:
acad886c
VZ
642#if wxUSE_THREADS
643 // called from FlushActive() to really log any buffered messages logged
644 // from the other threads
645 void FlushThreadMessages();
53ff8df7
VZ
646
647 // these functions are called for non-main thread only by IsEnabled() and
648 // EnableLogging() respectively
649 static bool IsThreadLoggingEnabled();
650 static bool EnableThreadLogging(bool enable = true);
acad886c
VZ
651#endif // wxUSE_THREADS
652
5d7526b0
VZ
653 // get the active log target for the main thread, auto-creating it if
654 // necessary
655 //
656 // this is called from GetActiveTarget() and OnLog() when they're called
657 // from the main thread
658 static wxLog *GetMainThreadActiveTarget();
659
acad886c
VZ
660 // called from OnLog() if it's called from the main thread or if we have a
661 // (presumably MT-safe) thread-specific logger and by FlushThreadMessages()
232addd1 662 // when it plays back the buffered messages logged from the other threads
acad886c
VZ
663 void CallDoLogNow(wxLogLevel level,
664 const wxString& msg,
665 const wxLogRecordInfo& info);
232addd1
VZ
666
667
4ffdb640
VZ
668 // variables
669 // ----------------
670
671 wxLogFormatter *m_formatter; // We own this pointer.
672
673
d6b9496a
VZ
674 // static variables
675 // ----------------
06db8ebd 676
2064113c
VZ
677 // if true, don't log the same message multiple times, only log it once
678 // with the number of times it was repeated
f9837791 679 static bool ms_bRepetCounting;
2064113c 680
d6b9496a 681 static wxLog *ms_pLogger; // currently active log sink
d1b20379 682 static bool ms_doLog; // false => all logging disabled
d6b9496a 683 static bool ms_bAutoCreate; // create new log targets on demand?
d1b20379 684 static bool ms_bVerbose; // false => ignore LogInfo messages
fe7b1156 685
edc73852
RD
686 static wxLogLevel ms_logLevel; // limit logging to levels <= ms_logLevel
687
2ed3265e
VZ
688 static size_t ms_suspendCount; // if positive, logs are not flushed
689
d1279c9a 690 // format string for strftime(), if empty, time stamping log messages is
d2e1ef19 691 // disabled
d993e05b 692 static wxString ms_timestamp;
d2e1ef19 693
34085a0d 694#if WXWIN_COMPATIBILITY_2_8
d6b9496a 695 static wxTraceMask ms_ulTraceMask; // controls wxLogTrace behaviour
34085a0d 696#endif // WXWIN_COMPATIBILITY_2_8
c801d85f
KB
697};
698
699// ----------------------------------------------------------------------------
700// "trivial" derivations of wxLog
701// ----------------------------------------------------------------------------
702
711f12ef
VZ
703// log everything except for the debug/trace messages (which are passed to
704// wxMessageOutputDebug) to a buffer
d3fc1755
VZ
705class WXDLLIMPEXP_BASE wxLogBuffer : public wxLog
706{
707public:
708 wxLogBuffer() { }
709
710 // get the string contents with all messages logged
711 const wxString& GetBuffer() const { return m_str; }
712
713 // show the buffer contents to the user in the best possible way (this uses
714 // wxMessageOutputMessageBox) and clear it
715 virtual void Flush();
716
717protected:
bc73d5ae 718 virtual void DoLogTextAtLevel(wxLogLevel level, const wxString& msg);
b99891b0 719
d3fc1755
VZ
720private:
721 wxString m_str;
722
c0c133e1 723 wxDECLARE_NO_COPY_CLASS(wxLogBuffer);
d3fc1755
VZ
724};
725
0f8218d7 726
c801d85f 727// log everything to a "FILE *", stderr by default
bddd7a8d 728class WXDLLIMPEXP_BASE wxLogStderr : public wxLog
c801d85f
KB
729{
730public:
d6b9496a 731 // redirect log output to a FILE
d3b9f782 732 wxLogStderr(FILE *fp = NULL);
c801d85f 733
03147cd0 734protected:
d6b9496a 735 // implement sink function
bc73d5ae 736 virtual void DoLogText(const wxString& msg);
b99891b0 737
d6b9496a 738 FILE *m_fp;
d3fc1755 739
c0c133e1 740 wxDECLARE_NO_COPY_CLASS(wxLogStderr);
c801d85f
KB
741};
742
4bf78aae 743#if wxUSE_STD_IOSTREAM
03147cd0 744
c801d85f 745// log everything to an "ostream", cerr by default
bddd7a8d 746class WXDLLIMPEXP_BASE wxLogStream : public wxLog
c801d85f
KB
747{
748public:
d6b9496a 749 // redirect log output to an ostream
dd107c50 750 wxLogStream(wxSTD ostream *ostr = (wxSTD ostream *) NULL);
c801d85f
KB
751
752protected:
d6b9496a 753 // implement sink function
bc73d5ae 754 virtual void DoLogText(const wxString& msg);
b99891b0 755
d6b9496a 756 // using ptr here to avoid including <iostream.h> from this file
dd107c50 757 wxSTD ostream *m_ostr;
c801d85f 758};
03147cd0
VZ
759
760#endif // wxUSE_STD_IOSTREAM
c801d85f 761
03147cd0
VZ
762// ----------------------------------------------------------------------------
763// /dev/null log target: suppress logging until this object goes out of scope
764// ----------------------------------------------------------------------------
765
766// example of usage:
767/*
768 void Foo()
769 {
770 wxFile file;
771
772 // wxFile.Open() normally complains if file can't be opened, we don't
773 // want it
774 wxLogNull logNo;
775
776 if ( !file.Open("bar") )
777 ... process error ourselves ...
778
779 // ~wxLogNull called, old log sink restored
780 }
781 */
bddd7a8d 782class WXDLLIMPEXP_BASE wxLogNull
03147cd0
VZ
783{
784public:
d1b20379 785 wxLogNull() : m_flagOld(wxLog::EnableLogging(false)) { }
be52b341 786 ~wxLogNull() { (void)wxLog::EnableLogging(m_flagOld); }
03147cd0
VZ
787
788private:
789 bool m_flagOld; // the previous value of the wxLog::ms_doLog
790};
791
792// ----------------------------------------------------------------------------
793// chaining log target: installs itself as a log target and passes all
794// messages to the real log target given to it in the ctor but also forwards
795// them to the previously active one
796//
797// note that you don't have to call SetActiveTarget() with this class, it
798// does it itself in its ctor
799// ----------------------------------------------------------------------------
800
bddd7a8d 801class WXDLLIMPEXP_BASE wxLogChain : public wxLog
03147cd0
VZ
802{
803public:
804 wxLogChain(wxLog *logger);
8b30a4e4 805 virtual ~wxLogChain();
03147cd0
VZ
806
807 // change the new log target
808 void SetLog(wxLog *logger);
809
810 // this can be used to temporarily disable (and then reenable) passing
811 // messages to the old logger (by default we do pass them)
812 void PassMessages(bool bDoPass) { m_bPassMessages = bDoPass; }
813
814 // are we passing the messages to the previous log target?
815 bool IsPassingMessages() const { return m_bPassMessages; }
816
817 // return the previous log target (may be NULL)
818 wxLog *GetOldLog() const { return m_logOld; }
819
820 // override base class version to flush the old logger as well
821 virtual void Flush();
822
47fe7ff3
JS
823 // call to avoid destroying the old log target
824 void DetachOldLog() { m_logOld = NULL; }
825
03147cd0 826protected:
bc73d5ae
VZ
827 // pass the record to the old logger if needed
828 virtual void DoLogRecord(wxLogLevel level,
829 const wxString& msg,
830 const wxLogRecordInfo& info);
b99891b0 831
03147cd0
VZ
832private:
833 // the current log target
834 wxLog *m_logNew;
835
836 // the previous log target
837 wxLog *m_logOld;
838
839 // do we pass the messages to the old logger?
840 bool m_bPassMessages;
22f3361e 841
c0c133e1 842 wxDECLARE_NO_COPY_CLASS(wxLogChain);
03147cd0
VZ
843};
844
845// a chain log target which uses itself as the new logger
47fe7ff3
JS
846
847#define wxLogPassThrough wxLogInterposer
848
849class WXDLLIMPEXP_BASE wxLogInterposer : public wxLogChain
850{
851public:
852 wxLogInterposer();
853
854private:
c0c133e1 855 wxDECLARE_NO_COPY_CLASS(wxLogInterposer);
47fe7ff3
JS
856};
857
858// a temporary interposer which doesn't destroy the old log target
859// (calls DetachOldLog)
860
861class WXDLLIMPEXP_BASE wxLogInterposerTemp : public wxLogChain
03147cd0
VZ
862{
863public:
47fe7ff3 864 wxLogInterposerTemp();
fc7a2a60
VZ
865
866private:
c0c133e1 867 wxDECLARE_NO_COPY_CLASS(wxLogInterposerTemp);
03147cd0
VZ
868};
869
8ca28fb7 870#if wxUSE_GUI
7e8c564c
VS
871 // include GUI log targets:
872 #include "wx/generic/logg.h"
e90c1d2a 873#endif // wxUSE_GUI
03f38c58 874
af588446
VZ
875// ----------------------------------------------------------------------------
876// wxLogger
877// ----------------------------------------------------------------------------
878
879// wxLogger is a helper class used by wxLogXXX() functions implementation,
880// don't use it directly as it's experimental and subject to change (OTOH it
881// might become public in the future if it's deemed to be useful enough)
882
883// contains information about the context from which a log message originates
884// and provides Log() vararg method which forwards to wxLog::OnLog() and passes
885// this context to it
886class wxLogger
887{
888public:
889 // ctor takes the basic information about the log record
890 wxLogger(wxLogLevel level,
891 const char *filename,
892 int line,
c602c59b
VZ
893 const char *func,
894 const char *component)
af588446 895 : m_level(level),
c602c59b 896 m_info(filename, line, func, component)
af588446
VZ
897 {
898 }
899
900 // store extra data in our log record and return this object itself (so
901 // that further calls to its functions could be chained)
902 template <typename T>
903 wxLogger& Store(const wxString& key, T val)
904 {
905 m_info.StoreValue(key, val);
906 return *this;
907 }
908
909 // hack for "overloaded" wxLogXXX() functions: calling this method
910 // indicates that we may have an extra first argument preceding the format
911 // string and that if we do have it, we should store it in m_info using the
912 // given key (while by default 0 value will be used)
b804f992 913 wxLogger& MaybeStore(const wxString& key, wxUIntPtr value = 0)
af588446
VZ
914 {
915 wxASSERT_MSG( m_optKey.empty(), "can only have one optional value" );
916 m_optKey = key;
917
b804f992 918 m_info.StoreValue(key, value);
af588446
VZ
919 return *this;
920 }
921
922
923 // non-vararg function used by wxVLogXXX():
924
925 // log the message at the level specified in the ctor if this log message
926 // is enabled
927 void LogV(const wxString& format, va_list argptr)
928 {
929 // remember that fatal errors can't be disabled
c602c59b
VZ
930 if ( m_level == wxLOG_FatalError ||
931 wxLog::IsLevelEnabled(m_level, m_info.component) )
af588446
VZ
932 DoCallOnLog(format, argptr);
933 }
934
935 // overloads used by functions with optional leading arguments (whose
936 // values are stored in the key passed to MaybeStore())
937 void LogV(long num, const wxString& format, va_list argptr)
938 {
939 Store(m_optKey, num);
940
941 LogV(format, argptr);
942 }
943
944 void LogV(void *ptr, const wxString& format, va_list argptr)
945 {
946 Store(m_optKey, wxPtrToUInt(ptr));
947
948 LogV(format, argptr);
949 }
950
89d62794
VZ
951 void LogVTrace(const wxString& mask, const wxString& format, va_list argptr)
952 {
953 if ( !wxLog::IsAllowedTraceMask(mask) )
954 return;
955
956 Store(wxLOG_KEY_TRACE_MASK, mask);
957
958 LogV(format, argptr);
959 }
960
af588446
VZ
961
962 // vararg functions used by wxLogXXX():
963
964 // will log the message at the level specified in the ctor
965 //
966 // notice that this function supposes that the caller already checked that
967 // the level was enabled and does no checks itself
968 WX_DEFINE_VARARG_FUNC_VOID
969 (
970 Log,
971 1, (const wxFormatString&),
972 DoLog, DoLogUtf8
973 )
974
975 // same as Log() but with an extra numeric or pointer parameters: this is
976 // used to pass an optional value by storing it in m_info under the name
977 // passed to MaybeStore() and is required to support "overloaded" versions
978 // of wxLogStatus() and wxLogSysError()
979 WX_DEFINE_VARARG_FUNC_VOID
980 (
981 Log,
982 2, (long, const wxFormatString&),
983 DoLogWithNum, DoLogWithNumUtf8
984 )
985
c279530b
VZ
986 // unfortunately we can't use "void *" here as we get overload ambiguities
987 // with Log(wxFormatString, ...) when the first argument is a "char *" or
988 // "wchar_t *" then -- so we only allow passing wxObject here, which is
989 // ugly but fine in practice as this overload is only used by wxLogStatus()
990 // whose first argument is a wxFrame
af588446
VZ
991 WX_DEFINE_VARARG_FUNC_VOID
992 (
993 Log,
c279530b 994 2, (wxObject *, const wxFormatString&),
af588446
VZ
995 DoLogWithPtr, DoLogWithPtrUtf8
996 )
997
998 // log the message at the level specified as its first argument
999 //
1000 // as the macros don't have access to the level argument in this case, this
1001 // function does check that the level is enabled itself
1002 WX_DEFINE_VARARG_FUNC_VOID
1003 (
1004 LogAtLevel,
1005 2, (wxLogLevel, const wxFormatString&),
1006 DoLogAtLevel, DoLogAtLevelUtf8
1007 )
1008
1009 // special versions for wxLogTrace() which is passed either string or
ff2e9e2c
VZ
1010 // integer mask as first argument determining whether the message should be
1011 // logged or not
af588446
VZ
1012 WX_DEFINE_VARARG_FUNC_VOID
1013 (
1014 LogTrace,
1015 2, (const wxString&, const wxFormatString&),
1016 DoLogTrace, DoLogTraceUtf8
1017 )
1018
ff2e9e2c
VZ
1019#if WXWIN_COMPATIBILITY_2_8
1020 WX_DEFINE_VARARG_FUNC_VOID
1021 (
1022 LogTrace,
1023 2, (wxTraceMask, const wxFormatString&),
1024 DoLogTraceMask, DoLogTraceMaskUtf8
1025 )
1026#endif // WXWIN_COMPATIBILITY_2_8
1027
af588446
VZ
1028#ifdef __WATCOMC__
1029 // workaround for http://bugzilla.openwatcom.org/show_bug.cgi?id=351
1030 WX_VARARG_WATCOM_WORKAROUND(void, Log,
1031 1, (const wxString&),
1032 (wxFormatString(f1)))
1033 WX_VARARG_WATCOM_WORKAROUND(void, Log,
1034 1, (const wxCStrData&),
1035 (wxFormatString(f1)))
1036 WX_VARARG_WATCOM_WORKAROUND(void, Log,
1037 1, (const char*),
1038 (wxFormatString(f1)))
1039 WX_VARARG_WATCOM_WORKAROUND(void, Log,
1040 1, (const wchar_t*),
1041 (wxFormatString(f1)))
1042
1043 WX_VARARG_WATCOM_WORKAROUND(void, Log,
1044 2, (long, const wxString&),
1045 (f1, wxFormatString(f2)))
1046 WX_VARARG_WATCOM_WORKAROUND(void, Log,
1047 2, (long, const wxCStrData&),
1048 (f1, wxFormatString(f2)))
1049 WX_VARARG_WATCOM_WORKAROUND(void, Log,
1050 2, (long, const char *),
1051 (f1, wxFormatString(f2)))
1052 WX_VARARG_WATCOM_WORKAROUND(void, Log,
1053 2, (long, const wchar_t *),
1054 (f1, wxFormatString(f2)))
1055
1056 WX_VARARG_WATCOM_WORKAROUND(void, Log,
c279530b 1057 2, (wxObject *, const wxString&),
af588446
VZ
1058 (f1, wxFormatString(f2)))
1059 WX_VARARG_WATCOM_WORKAROUND(void, Log,
c279530b 1060 2, (wxObject *, const wxCStrData&),
af588446
VZ
1061 (f1, wxFormatString(f2)))
1062 WX_VARARG_WATCOM_WORKAROUND(void, Log,
c279530b 1063 2, (wxObject *, const char *),
af588446
VZ
1064 (f1, wxFormatString(f2)))
1065 WX_VARARG_WATCOM_WORKAROUND(void, Log,
c279530b 1066 2, (wxObject *, const wchar_t *),
af588446
VZ
1067 (f1, wxFormatString(f2)))
1068
1069 WX_VARARG_WATCOM_WORKAROUND(void, LogAtLevel,
1070 2, (wxLogLevel, const wxString&),
1071 (f1, wxFormatString(f2)))
1072 WX_VARARG_WATCOM_WORKAROUND(void, LogAtLevel,
1073 2, (wxLogLevel, const wxCStrData&),
1074 (f1, wxFormatString(f2)))
1075 WX_VARARG_WATCOM_WORKAROUND(void, LogAtLevel,
1076 2, (wxLogLevel, const char *),
1077 (f1, wxFormatString(f2)))
1078 WX_VARARG_WATCOM_WORKAROUND(void, LogAtLevel,
1079 2, (wxLogLevel, const wchar_t *),
1080 (f1, wxFormatString(f2)))
1081
1082 WX_VARARG_WATCOM_WORKAROUND(void, LogTrace,
1083 2, (const wxString&, const wxString&),
1084 (f1, wxFormatString(f2)))
1085 WX_VARARG_WATCOM_WORKAROUND(void, LogTrace,
1086 2, (const wxString&, const wxCStrData&),
1087 (f1, wxFormatString(f2)))
1088 WX_VARARG_WATCOM_WORKAROUND(void, LogTrace,
1089 2, (const wxString&, const char *),
1090 (f1, wxFormatString(f2)))
1091 WX_VARARG_WATCOM_WORKAROUND(void, LogTrace,
1092 2, (const wxString&, const wchar_t *),
1093 (f1, wxFormatString(f2)))
ff2e9e2c
VZ
1094
1095#if WXWIN_COMPATIBILITY_2_8
1096 WX_VARARG_WATCOM_WORKAROUND(void, LogTrace,
1097 2, (wxTraceMask, wxTraceMask),
1098 (f1, wxFormatString(f2)))
1099 WX_VARARG_WATCOM_WORKAROUND(void, LogTrace,
1100 2, (wxTraceMask, const wxCStrData&),
1101 (f1, wxFormatString(f2)))
1102 WX_VARARG_WATCOM_WORKAROUND(void, LogTrace,
1103 2, (wxTraceMask, const char *),
1104 (f1, wxFormatString(f2)))
1105 WX_VARARG_WATCOM_WORKAROUND(void, LogTrace,
1106 2, (wxTraceMask, const wchar_t *),
1107 (f1, wxFormatString(f2)))
1108#endif // WXWIN_COMPATIBILITY_2_8
af588446
VZ
1109#endif // __WATCOMC__
1110
1111private:
1112#if !wxUSE_UTF8_LOCALE_ONLY
1113 void DoLog(const wxChar *format, ...)
1114 {
1115 va_list argptr;
1116 va_start(argptr, format);
1117 DoCallOnLog(format, argptr);
1118 va_end(argptr);
1119 }
1120
1121 void DoLogWithNum(long num, const wxChar *format, ...)
1122 {
1123 Store(m_optKey, num);
1124
1125 va_list argptr;
1126 va_start(argptr, format);
1127 DoCallOnLog(format, argptr);
1128 va_end(argptr);
1129 }
1130
1131 void DoLogWithPtr(void *ptr, const wxChar *format, ...)
1132 {
1133 Store(m_optKey, wxPtrToUInt(ptr));
1134
1135 va_list argptr;
1136 va_start(argptr, format);
1137 DoCallOnLog(format, argptr);
1138 va_end(argptr);
1139 }
1140
1141 void DoLogAtLevel(wxLogLevel level, const wxChar *format, ...)
1142 {
c602c59b 1143 if ( !wxLog::IsLevelEnabled(level, m_info.component) )
af588446
VZ
1144 return;
1145
1146 va_list argptr;
1147 va_start(argptr, format);
1148 DoCallOnLog(level, format, argptr);
1149 va_end(argptr);
1150 }
1151
1152 void DoLogTrace(const wxString& mask, const wxChar *format, ...)
1153 {
1154 if ( !wxLog::IsAllowedTraceMask(mask) )
1155 return;
1156
1157 Store(wxLOG_KEY_TRACE_MASK, mask);
1158
1159 va_list argptr;
1160 va_start(argptr, format);
1161 DoCallOnLog(format, argptr);
1162 va_end(argptr);
1163 }
ff2e9e2c
VZ
1164
1165#if WXWIN_COMPATIBILITY_2_8
1166 void DoLogTraceMask(wxTraceMask mask, const wxChar *format, ...)
1167 {
1168 if ( (wxLog::GetTraceMask() & mask) != mask )
1169 return;
1170
1171 Store(wxLOG_KEY_TRACE_MASK, mask);
1172
1173 va_list argptr;
1174 va_start(argptr, format);
1175 DoCallOnLog(format, argptr);
1176 va_end(argptr);
1177 }
1178#endif // WXWIN_COMPATIBILITY_2_8
af588446
VZ
1179#endif // !wxUSE_UTF8_LOCALE_ONLY
1180
1181#if wxUSE_UNICODE_UTF8
1182 void DoLogUtf8(const char *format, ...)
1183 {
1184 va_list argptr;
1185 va_start(argptr, format);
1186 DoCallOnLog(format, argptr);
1187 va_end(argptr);
1188 }
1189
1190 void DoLogWithNumUtf8(long num, const char *format, ...)
1191 {
1192 Store(m_optKey, num);
1193
1194 va_list argptr;
1195 va_start(argptr, format);
1196 DoCallOnLog(format, argptr);
1197 va_end(argptr);
1198 }
1199
1200 void DoLogWithPtrUtf8(void *ptr, const char *format, ...)
1201 {
1202 Store(m_optKey, wxPtrToUInt(ptr));
1203
1204 va_list argptr;
1205 va_start(argptr, format);
1206 DoCallOnLog(format, argptr);
1207 va_end(argptr);
1208 }
1209
1210 void DoLogAtLevelUtf8(wxLogLevel level, const char *format, ...)
1211 {
c602c59b 1212 if ( !wxLog::IsLevelEnabled(level, m_info.component) )
af588446
VZ
1213 return;
1214
1215 va_list argptr;
1216 va_start(argptr, format);
1217 DoCallOnLog(level, format, argptr);
1218 va_end(argptr);
1219 }
1220
1221 void DoLogTraceUtf8(const wxString& mask, const char *format, ...)
1222 {
1223 if ( !wxLog::IsAllowedTraceMask(mask) )
1224 return;
1225
1226 Store(wxLOG_KEY_TRACE_MASK, mask);
1227
1228 va_list argptr;
1229 va_start(argptr, format);
1230 DoCallOnLog(format, argptr);
1231 va_end(argptr);
1232 }
ff2e9e2c
VZ
1233
1234#if WXWIN_COMPATIBILITY_2_8
1235 void DoLogTraceMaskUtf8(wxTraceMask mask, const char *format, ...)
1236 {
1237 if ( (wxLog::GetTraceMask() & mask) != mask )
1238 return;
1239
1240 Store(wxLOG_KEY_TRACE_MASK, mask);
1241
1242 va_list argptr;
1243 va_start(argptr, format);
1244 DoCallOnLog(format, argptr);
1245 va_end(argptr);
1246 }
1247#endif // WXWIN_COMPATIBILITY_2_8
af588446
VZ
1248#endif // wxUSE_UNICODE_UTF8
1249
1250 void DoCallOnLog(wxLogLevel level, const wxString& format, va_list argptr)
1251 {
1252 wxLog::OnLog(level, wxString::FormatV(format, argptr), m_info);
1253 }
1254
1255 void DoCallOnLog(const wxString& format, va_list argptr)
1256 {
b804f992 1257 DoCallOnLog(m_level, format, argptr);
af588446
VZ
1258 }
1259
1260
1261 const wxLogLevel m_level;
1262 wxLogRecordInfo m_info;
1263
1264 wxString m_optKey;
1265
1266 wxDECLARE_NO_COPY_CLASS(wxLogger);
1267};
1268
c801d85f
KB
1269// ============================================================================
1270// global functions
1271// ============================================================================
1272
88ac883a
VZ
1273// ----------------------------------------------------------------------------
1274// get error code/error message from system in a portable way
1275// ----------------------------------------------------------------------------
1276
1277// return the last system error code
bddd7a8d 1278WXDLLIMPEXP_BASE unsigned long wxSysErrorCode();
c11d62a6 1279
88ac883a 1280// return the error message for given (or last if 0) error code
bddd7a8d 1281WXDLLIMPEXP_BASE const wxChar* wxSysErrorMsg(unsigned long nErrCode = 0);
88ac883a 1282
c11d62a6 1283// ----------------------------------------------------------------------------
af588446
VZ
1284// define wxLog<level>() functions which can be used by application instead of
1285// stdio, iostream &c for log messages for easy redirection
c11d62a6 1286// ----------------------------------------------------------------------------
c801d85f 1287
af588446
VZ
1288/*
1289 The code below is unreadable because it (unfortunately unavoidably)
1290 contains a lot of macro magic but all it does is to define wxLogXXX() such
1291 that you can call them as vararg functions to log a message at the
1292 corresponding level.
1293
1294 More precisely, it defines:
1295
1296 - wxLog{FatalError,Error,Warning,Message,Verbose,Debug}() functions
1297 taking the format string and additional vararg arguments if needed.
1298 - wxLogGeneric(wxLogLevel level, const wxString& format, ...) which
1299 takes the log level explicitly.
1300 - wxLogSysError(const wxString& format, ...) and wxLogSysError(long
1301 err, const wxString& format, ...) which log a wxLOG_Error severity
1302 message with the error message corresponding to the system error code
1303 err or the last error.
1304 - wxLogStatus(const wxString& format, ...) which logs the message into
1305 the status bar of the main application window and its overload
1306 wxLogStatus(wxFrame *frame, const wxString& format, ...) which logs it
1307 into the status bar of the specified frame.
1308 - wxLogTrace(Mask mask, const wxString& format, ...) which only logs
1309 the message is the specified mask is enabled. This comes in two kinds:
1310 Mask can be a wxString or a long. Both are deprecated.
1311
1312 In addition, wxVLogXXX() versions of all the functions above are also
1313 defined. They take a va_list argument instead of "...".
1314 */
2523e9b7 1315
af588446
VZ
1316// creates wxLogger object for the current location
1317#define wxMAKE_LOGGER(level) \
c602c59b 1318 wxLogger(wxLOG_##level, __FILE__, __LINE__, __WXFUNCTION__, wxLOG_COMPONENT)
2523e9b7 1319
af588446
VZ
1320// this macro generates the expression which logs whatever follows it in
1321// parentheses at the level specified as argument
1322#define wxDO_LOG(level) wxMAKE_LOGGER(level).Log
c9f78968 1323
af588446
VZ
1324// this is the non-vararg equivalent
1325#define wxDO_LOGV(level, format, argptr) \
1326 wxMAKE_LOGGER(level).LogV(format, argptr)
2523e9b7 1327
af588446
VZ
1328// this macro declares wxLog<level>() macro which logs whatever follows it if
1329// logging at specified level is enabled (notice that if it is false, the
1330// following arguments are not even evaluated which is good as it avoids
1331// unnecessary overhead)
1332//
1333// Note: the strange if/else construct is needed to make the following code
1334//
1335// if ( cond )
1336// wxLogError("!!!");
1337// else
1338// ...
1339//
1340// work as expected, without it the second "else" would match the "if"
1341// inside wxLogError(). Unfortunately code like
1342//
1343// if ( cond )
1344// wxLogError("!!!");
1345//
1346// now provokes "suggest explicit braces to avoid ambiguous 'else'"
1347// warnings from g++ 4.3 and later with -Wparentheses on but they can be
1348// easily fixed by adding curly braces around wxLogError() and at least
1349// the code still does do the right thing.
1350#define wxDO_LOG_IF_ENABLED(level) \
c602c59b 1351 if ( !wxLog::IsLevelEnabled(wxLOG_##level, wxLOG_COMPONENT) ) \
af588446
VZ
1352 {} \
1353 else \
1354 wxDO_LOG(level)
1355
1356// wxLogFatalError() is special as it can't be disabled
03647350 1357#define wxLogFatalError wxDO_LOG(FatalError)
af588446
VZ
1358#define wxVLogFatalError(format, argptr) wxDO_LOGV(FatalError, format, argptr)
1359
1360#define wxLogError wxDO_LOG_IF_ENABLED(Error)
1361#define wxVLogError(format, argptr) wxDO_LOGV(Error, format, argptr)
1362
1363#define wxLogWarning wxDO_LOG_IF_ENABLED(Warning)
1364#define wxVLogWarning(format, argptr) wxDO_LOGV(Warning, format, argptr)
1365
1366#define wxLogMessage wxDO_LOG_IF_ENABLED(Message)
1367#define wxVLogMessage(format, argptr) wxDO_LOGV(Message, format, argptr)
1368
1369// this one is special as it only logs if we're in verbose mode
1370#define wxLogVerbose \
c602c59b
VZ
1371 if ( !(wxLog::IsLevelEnabled(wxLOG_Info, wxLOG_COMPONENT) && \
1372 wxLog::GetVerbose()) ) \
af588446
VZ
1373 {} \
1374 else \
1375 wxDO_LOG(Info)
1376#define wxVLogVerbose(format, argptr) \
c602c59b
VZ
1377 if ( !(wxLog::IsLevelEnabled(wxLOG_Info, wxLOG_COMPONENT) && \
1378 wxLog::GetVerbose()) ) \
af588446
VZ
1379 {} \
1380 else \
1381 wxDO_LOGV(Info, format, argptr)
1382
1383// deprecated synonyms for wxLogVerbose() and wxVLogVerbose()
1384#define wxLogInfo wxLogVerbose
1385#define wxVLogInfo wxVLogVerbose
1386
1387
1388// another special case: the level is passed as first argument of the function
1389// and so is not available to the macro
1390//
1391// notice that because of this, arguments of wxLogGeneric() are currently
1392// always evaluated, unlike for the other log functions
1393#define wxLogGeneric wxMAKE_LOGGER(Max).LogAtLevel
1394#define wxVLogGeneric(level, format, argptr) \
c602c59b 1395 if ( !wxLog::IsLevelEnabled(wxLOG_##level, wxLOG_COMPONENT) ) \
af588446
VZ
1396 {} \
1397 else \
1398 wxDO_LOGV(level, format, argptr)
1399
1400
1401// wxLogSysError() needs to stash the error code value in the log record info
1402// so it needs special handling too; additional complications arise because the
1403// error code may or not be present as the first argument
b804f992
VZ
1404//
1405// notice that we unfortunately can't avoid the call to wxSysErrorCode() even
1406// though it may be unneeded if an explicit error code is passed to us because
1407// the message might not be logged immediately (e.g. it could be queued for
1408// logging from the main thread later) and so we can't to wait until it is
1409// logged to determine whether we have last error or not as it will be too late
1410// and it will have changed already by then (in fact it even changes when
1411// wxString::Format() is called because of vsnprintf() inside it so it can
1412// change even much sooner)
af588446
VZ
1413#define wxLOG_KEY_SYS_ERROR_CODE "wx.sys_error"
1414
1415#define wxLogSysError \
c602c59b 1416 if ( !wxLog::IsLevelEnabled(wxLOG_Error, wxLOG_COMPONENT) ) \
af588446
VZ
1417 {} \
1418 else \
b804f992
VZ
1419 wxMAKE_LOGGER(Error).MaybeStore(wxLOG_KEY_SYS_ERROR_CODE, \
1420 wxSysErrorCode()).Log
af588446
VZ
1421
1422// unfortunately we can't have overloaded macros so we can't define versions
1423// both with and without error code argument and have to rely on LogV()
1424// overloads in wxLogger to select between them
1425#define wxVLogSysError \
b804f992
VZ
1426 wxMAKE_LOGGER(Error).MaybeStore(wxLOG_KEY_SYS_ERROR_CODE, \
1427 wxSysErrorCode()).LogV
af588446
VZ
1428
1429#if wxUSE_GUI
1430 // wxLogStatus() is similar to wxLogSysError() as it allows to optionally
1431 // specify the frame to which the message should go
1432 #define wxLOG_KEY_FRAME "wx.frame"
1433
1434 #define wxLogStatus \
c602c59b 1435 if ( !wxLog::IsLevelEnabled(wxLOG_Status, wxLOG_COMPONENT) ) \
af588446
VZ
1436 {} \
1437 else \
1438 wxMAKE_LOGGER(Status).MaybeStore(wxLOG_KEY_FRAME).Log
1439
1440 #define wxVLogStatus(format, argptr) \
1441 wxMAKE_LOGGER(Status).MaybeStore(wxLOG_KEY_FRAME).LogV
1442#endif // wxUSE_GUI
2523e9b7 1443
c9f78968 1444
88ac883a
VZ
1445#else // !wxUSE_LOG
1446
711f12ef
VZ
1447#undef wxUSE_LOG_DEBUG
1448#define wxUSE_LOG_DEBUG 0
1449
1450#undef wxUSE_LOG_TRACE
1451#define wxUSE_LOG_TRACE 0
1452
99fda03a
VS
1453#if defined(__WATCOMC__) || defined(__MINGW32__)
1454 // Mingw has similar problem with wxLogSysError:
1455 #define WX_WATCOM_OR_MINGW_ONLY_CODE( x ) x
1456#else
1457 #define WX_WATCOM_OR_MINGW_ONLY_CODE( x )
1458#endif
1459
af588446
VZ
1460// define macros for defining log functions which do nothing at all
1461//
1462// WX_WATCOM_ONLY_CODE is needed to work around
1463// http://bugzilla.openwatcom.org/show_bug.cgi?id=351
1464#define wxDEFINE_EMPTY_LOG_FUNCTION(level) \
b0d58b0e 1465 WX_DEFINE_VARARG_FUNC_NOP(wxLog##level, 1, (const wxFormatString&)) \
2523e9b7
VS
1466 WX_WATCOM_ONLY_CODE( \
1467 WX_DEFINE_VARARG_FUNC_NOP(wxLog##level, 1, (const char*)) \
1468 WX_DEFINE_VARARG_FUNC_NOP(wxLog##level, 1, (const wchar_t*)) \
1469 WX_DEFINE_VARARG_FUNC_NOP(wxLog##level, 1, (const wxCStrData&)) \
1470 ) \
b0d58b0e 1471 inline void wxVLog##level(const wxFormatString& WXUNUSED(format), \
59a14f69 1472 va_list WXUNUSED(argptr)) { } \
c9f78968 1473
af588446 1474#define wxDEFINE_EMPTY_LOG_FUNCTION2(level, argclass) \
b0d58b0e 1475 WX_DEFINE_VARARG_FUNC_NOP(wxLog##level, 2, (argclass, const wxFormatString&)) \
99fda03a 1476 WX_WATCOM_OR_MINGW_ONLY_CODE( \
2523e9b7
VS
1477 WX_DEFINE_VARARG_FUNC_NOP(wxLog##level, 2, (argclass, const char*)) \
1478 WX_DEFINE_VARARG_FUNC_NOP(wxLog##level, 2, (argclass, const wchar_t*)) \
1479 WX_DEFINE_VARARG_FUNC_NOP(wxLog##level, 2, (argclass, const wxCStrData&)) \
1480 ) \
c9f78968 1481 inline void wxVLog##level(argclass WXUNUSED(arg), \
b0d58b0e 1482 const wxFormatString& WXUNUSED(format), \
59a14f69 1483 va_list WXUNUSED(argptr)) {}
2523e9b7 1484
af588446
VZ
1485wxDEFINE_EMPTY_LOG_FUNCTION(FatalError);
1486wxDEFINE_EMPTY_LOG_FUNCTION(Error);
1487wxDEFINE_EMPTY_LOG_FUNCTION(SysError);
1488wxDEFINE_EMPTY_LOG_FUNCTION2(SysError, long);
1489wxDEFINE_EMPTY_LOG_FUNCTION(Warning);
1490wxDEFINE_EMPTY_LOG_FUNCTION(Message);
1491wxDEFINE_EMPTY_LOG_FUNCTION(Info);
1492wxDEFINE_EMPTY_LOG_FUNCTION(Verbose);
1493
1494wxDEFINE_EMPTY_LOG_FUNCTION2(Generic, wxLogLevel);
1495
1496#if wxUSE_GUI
1497 wxDEFINE_EMPTY_LOG_FUNCTION(Status);
1498 wxDEFINE_EMPTY_LOG_FUNCTION2(Status, wxFrame *);
1499#endif // wxUSE_GUI
1500
e30285ab 1501// Empty Class to fake wxLogNull
bddd7a8d 1502class WXDLLIMPEXP_BASE wxLogNull
e30285ab
VZ
1503{
1504public:
886dd7d2 1505 wxLogNull() { }
e30285ab
VZ
1506};
1507
1508// Dummy macros to replace some functions.
1509#define wxSysErrorCode() (unsigned long)0
1510#define wxSysErrorMsg( X ) (const wxChar*)NULL
1511
1512// Fake symbolic trace masks... for those that are used frequently
fda7962d 1513#define wxTRACE_OleCalls wxEmptyString // OLE interface calls
e30285ab 1514
88ac883a 1515#endif // wxUSE_LOG/!wxUSE_LOG
bdeb1f0d 1516
711f12ef
VZ
1517
1518// debug functions can be completely disabled in optimized builds
1519
1520// if these log functions are disabled, we prefer to define them as (empty)
1521// variadic macros as this completely removes them and their argument
1522// evaluation from the object code but if this is not supported by compiler we
1523// use empty inline functions instead (defining them as nothing would result in
1524// compiler warnings)
1525//
1526// note that making wxVLogDebug/Trace() themselves (empty inline) functions is
1527// a bad idea as some compilers are stupid enough to not inline even empty
1528// functions if their parameters are complicated enough, but by defining them
1529// as an empty inline function we ensure that even dumbest compilers optimise
1530// them away
1531#ifdef __BORLANDC__
1532 // but Borland gives "W8019: Code has no effect" for wxLogNop() so we need
1533 // to define it differently for it to avoid these warnings (same problem as
1534 // with wxUnusedVar())
1535 #define wxLogNop() { }
1536#else
1537 inline void wxLogNop() { }
1538#endif
1539
1540#if wxUSE_LOG_DEBUG
af588446
VZ
1541 #define wxLogDebug wxDO_LOG_IF_ENABLED(Debug)
1542 #define wxVLogDebug(format, argptr) wxDO_LOGV(Debug, format, argptr)
711f12ef
VZ
1543#else // !wxUSE_LOG_DEBUG
1544 #define wxVLogDebug(fmt, valist) wxLogNop()
d6b9496a 1545
711f12ef
VZ
1546 #ifdef HAVE_VARIADIC_MACROS
1547 #define wxLogDebug(fmt, ...) wxLogNop()
1548 #else // !HAVE_VARIADIC_MACROS
b0d58b0e 1549 WX_DEFINE_VARARG_FUNC_NOP(wxLogDebug, 1, (const wxFormatString&))
711f12ef
VZ
1550 #endif
1551#endif // wxUSE_LOG_DEBUG/!wxUSE_LOG_DEBUG
d6b9496a 1552
711f12ef 1553#if wxUSE_LOG_TRACE
af588446 1554 #define wxLogTrace \
c602c59b 1555 if ( !wxLog::IsLevelEnabled(wxLOG_Trace, wxLOG_COMPONENT) ) \
af588446
VZ
1556 {} \
1557 else \
1558 wxMAKE_LOGGER(Trace).LogTrace
89d62794
VZ
1559 #define wxVLogTrace \
1560 if ( !wxLog::IsLevelEnabled(wxLOG_Trace, wxLOG_COMPONENT) ) \
1561 {} \
1562 else \
1563 wxMAKE_LOGGER(Trace).LogVTrace
711f12ef 1564#else // !wxUSE_LOG_TRACE
388a1f66 1565 #define wxVLogTrace(mask, fmt, valist) wxLogNop()
ca766534
VS
1566
1567 #ifdef HAVE_VARIADIC_MACROS
388a1f66 1568 #define wxLogTrace(mask, fmt, ...) wxLogNop()
ca766534 1569 #else // !HAVE_VARIADIC_MACROS
69e3710e 1570 #if WXWIN_COMPATIBILITY_2_8
b0d58b0e 1571 WX_DEFINE_VARARG_FUNC_NOP(wxLogTrace, 2, (wxTraceMask, const wxFormatString&))
69e3710e 1572 #endif
b0d58b0e 1573 WX_DEFINE_VARARG_FUNC_NOP(wxLogTrace, 2, (const wxString&, const wxFormatString&))
44be939a
VS
1574 #ifdef __WATCOMC__
1575 // workaround for http://bugzilla.openwatcom.org/show_bug.cgi?id=351
1576 WX_DEFINE_VARARG_FUNC_NOP(wxLogTrace, 2, (const char*, const char*))
1577 WX_DEFINE_VARARG_FUNC_NOP(wxLogTrace, 2, (const wchar_t*, const wchar_t*))
1578 #endif
ca766534 1579 #endif // HAVE_VARIADIC_MACROS/!HAVE_VARIADIC_MACROS
711f12ef 1580#endif // wxUSE_LOG_TRACE/!wxUSE_LOG_TRACE
c801d85f 1581
c11d62a6
VZ
1582// wxLogFatalError helper: show the (fatal) error to the user in a safe way,
1583// i.e. without using wxMessageBox() for example because it could crash
bddd7a8d 1584void WXDLLIMPEXP_BASE
886dd7d2 1585wxSafeShowMessage(const wxString& title, const wxString& text);
c11d62a6 1586
88ac883a
VZ
1587// ----------------------------------------------------------------------------
1588// debug only logging functions: use them with API name and error code
1589// ----------------------------------------------------------------------------
c801d85f 1590
23fb9bf5 1591#if wxUSE_LOG_DEBUG
42e69d6b
VZ
1592 // make life easier for people using VC++ IDE: clicking on the message
1593 // will take us immediately to the place of the failed API
1594#ifdef __VISUALC__
4b7f2165
VZ
1595 #define wxLogApiError(api, rc) \
1596 wxLogDebug(wxT("%s(%d): '%s' failed with error 0x%08lx (%s)."), \
0accd1cf 1597 __FILE__, __LINE__, api, \
8b94d999 1598 (long)rc, wxSysErrorMsg(rc))
42e69d6b 1599#else // !VC++
4b7f2165 1600 #define wxLogApiError(api, rc) \
18da7cf2
VZ
1601 wxLogDebug(wxT("In file %s at line %d: '%s' failed with ") \
1602 wxT("error 0x%08lx (%s)."), \
0accd1cf 1603 __FILE__, __LINE__, api, \
8b94d999 1604 (long)rc, wxSysErrorMsg(rc))
42e69d6b
VZ
1605#endif // VC++/!VC++
1606
1607 #define wxLogLastError(api) wxLogApiError(api, wxSysErrorCode())
1608
23fb9bf5 1609#else // !wxUSE_LOG_DEBUG
388a1f66
VZ
1610 #define wxLogApiError(api, err) wxLogNop()
1611 #define wxLogLastError(api) wxLogNop()
23fb9bf5 1612#endif // wxUSE_LOG_DEBUG/!wxUSE_LOG_DEBUG
c801d85f 1613
a619fa3f
DE
1614// wxCocoa has additiional trace masks
1615#if defined(__WXCOCOA__)
1616#include "wx/cocoa/log.h"
1617#endif
1618
82e77a80
VS
1619#ifdef WX_WATCOM_ONLY_CODE
1620 #undef WX_WATCOM_ONLY_CODE
1621#endif
1622
7d9550df 1623// macro which disables debug logging in release builds: this is done by
e4431849 1624// default by wxIMPLEMENT_APP() so usually it doesn't need to be used explicitly
ff464152 1625#if defined(NDEBUG) && wxUSE_LOG_DEBUG
7d9550df
VZ
1626 #define wxDISABLE_DEBUG_LOGGING_IN_RELEASE_BUILD() \
1627 wxLog::SetLogLevel(wxLOG_Info)
1628#else // !NDEBUG
1629 #define wxDISABLE_DEBUG_LOGGING_IN_RELEASE_BUILD()
1630#endif // NDEBUG/!NDEBUG
1631
34138703 1632#endif // _WX_LOG_H_
04662def 1633