include/wx/log.h

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