include/wx/log.h

   1 /////////////////////////////////////////////////////////////////////////////
   2 // Name:        log.h
   3 // Purpose:     Assorted wxLogXXX functions, and wxLog (sink for logs)
   4 // Author:      Vadim Zeitlin
   5 // Modified by:
   6 // Created:     29/01/98
   7 // RCS-ID:      $Id$
   8 // Copyright:   (c) 1998 Vadim Zeitlin <zeitlin@dptmaths.ens-cachan.fr>
   9 // Licence:     wxWindows license
  10 /////////////////////////////////////////////////////////////////////////////
  11
  12 #ifndef   __LOGH__
  13 #define   __LOGH__
  14
  15 #ifdef    __GNUG__
  16 #pragma interface "log.h"
  17 #endif
  18
  19 #include "wx/intl.h"
  20
  21 // ----------------------------------------------------------------------------
  22 // constants
  23 // ----------------------------------------------------------------------------
  24
  25 // different standard log levels (you may also define your own)
  26 enum
  27 {
  28   wxLOG_FatalError, // program can't continue, abort immediately
  29   wxLOG_Error,      // a serious error, user must be informed about it
  30   wxLOG_Warning,    // user is normally informed about it but may be ignored
  31   wxLOG_Message,    // normal message (i.e. normal output of a non GUI app)
  32   wxLOG_Info,       // informational message (a.k.a. 'Verbose')
  33   wxLOG_Status,     // informational: might go to the status line of GUI app
  34   wxLOG_Debug,      // never shown to the user, disabled in release mode
  35   wxLOG_Trace,      // trace messages are also only enabled in debug mode
  36   wxLOG_Progress,   // used for progress indicator (not yet)
  37   wxLOG_User = 100  // user defined levels start here
  38 };
  39
  40 // meaning of different bits of the trace mask (which allows selectively
  41 // enable/disable some trace messages)
  42 #define wxTraceMemAlloc 0x0001  // trace memory allocation (new/delete)
  43 #define wxTraceMessages 0x0002  // trace window messages/X callbacks
  44 #define wxTraceResAlloc 0x0004  // trace GDI resource allocation
  45 #define wxTraceRefCount 0x0008  // trace various ref counting operations
  46
  47 #ifdef  __WXMSW__
  48   #define wxTraceOleCalls 0x0100  // OLE interface calls
  49 #endif
  50
  51 typedef unsigned long wxTraceMask;
  52 typedef unsigned long wxLogLevel;
  53
  54 // ----------------------------------------------------------------------------
  55 // derive from this class to redirect (or suppress, or ...) log messages
  56 // normally, only a single instance of this class exists but it's not enforced
  57 // ----------------------------------------------------------------------------
  58 class WXDLLEXPORT wxLog
  59 {
  60 public:
  61   // ctor
  62   wxLog();
  63
  64   // sink function
  65   static void OnLog(wxLogLevel level, const char *szString)
  66     { if ( ms_pLogger != 0 ) ms_pLogger->DoLog(level, szString); }
  67
  68   // message buffering
  69     // flush shows all messages if they're not logged immediately
  70     // (FILE and iostream logs don't need it, but wxGuiLog does to avoid
  71     //  showing 17 modal dialogs one after another)
  72   virtual void Flush();
  73     // call to Flush() may be optimized: call it only if this function
  74     // returns true (although Flush() also returns immediately if there
  75     // is no messages, this functions is more efficient because inline)
  76   bool HasPendingMessages() const { return m_bHasMessages; }
  77
  78   // only one sink is active at each moment
  79     // get current log target, will call wxApp::CreateLogTarget() to create one
  80     // if
  81   static wxLog *GetActiveTarget();
  82     // change log target, pLogger = NULL disables logging,
  83     // returns the previous log target
  84   static wxLog *SetActiveTarget(wxLog *pLogger);
  85
  86   // functions controlling the default wxLog behaviour
  87     // verbose mode is activated by standard command-line '-verbose' option
  88   void SetVerbose(bool bVerbose = TRUE) { m_bVerbose = bVerbose; }
  89     // sets the format for timestamp prepended by wxLog::DoLog(): it's
  90     // passed to strftime() function, see it's documentation for details.
  91     // no time stamp at all if szTF is NULL or empty
  92     // NB: the string is not copied, so it's lifetime must be long enough!
  93   void SetTimeStampFormat(const char *szTF) { m_szTimeFormat = szTF; }
  94     // trace mask (see wxTraceXXX constants for details)
  95   static void SetTraceMask(wxTraceMask ulMask) { ms_ulTraceMask = ulMask; }
  96     // should GetActiveTarget() try to create a new log object if the current
  97     // is NULL?
  98   static void DontCreateOnDemand() { ms_bAutoCreate = FALSE; }
  99
 100   // accessors
 101     // gets the verbose status
 102   bool GetVerbose() const { return m_bVerbose; }
 103     // get current time format
 104   const char *GetTimeStampFormat() const { return m_szTimeFormat; }
 105     // get trace mask
 106   static wxTraceMask GetTraceMask() { return ms_ulTraceMask; }
 107
 108   // make dtor virtual for all derived classes
 109   virtual ~wxLog() { }
 110
 111 protected:
 112   bool m_bHasMessages;
 113
 114   bool          m_bVerbose;     // FALSE => ignore LogInfo messages
 115   const char   *m_szTimeFormat; // format for strftime()
 116
 117   // the logging functions that can be overriden
 118     // default DoLog() prepends the time stamp and a prefix corresponding
 119     // to the message to szString and then passes it to DoLogString()
 120   virtual void DoLog(wxLogLevel level, const char *szString);
 121     // default DoLogString does nothing but is not pure virtual because if
 122     // you override DoLog() you might not need it at all
 123   virtual void DoLogString(const char *szString);
 124
 125 private:
 126   // static variables
 127   // ----------------
 128   static wxLog      *ms_pLogger;      // currently active log sink
 129   static bool        ms_bAutoCreate;  // automatically create new log targets?
 130   static wxTraceMask ms_ulTraceMask;  // controls wxLogTrace behaviour
 131 };
 132
 133 // ----------------------------------------------------------------------------
 134 // "trivial" derivations of wxLog
 135 // ----------------------------------------------------------------------------
 136
 137 // log everything to a "FILE *", stderr by default
 138 class WXDLLEXPORT wxLogStderr : public wxLog
 139 {
 140 public:
 141   // redirect log output to a FILE
 142   wxLogStderr(FILE *fp = NULL);
 143
 144 private:
 145   // implement sink function
 146   virtual void DoLogString(const char *szString);
 147
 148   FILE *m_fp;
 149 };
 150
 151 // log everything to an "ostream", cerr by default
 152 class WXDLLEXPORT wxLogStream : public wxLog
 153 {
 154 public:
 155   // redirect log output to an ostream
 156   wxLogStream(ostream *ostr = NULL);
 157
 158 protected:
 159   // implement sink function
 160   virtual void DoLogString(const char *szString);
 161
 162   // @@ using ptr here to avoid including <iostream.h> from this file
 163   ostream *m_ostr;
 164 };
 165
 166 // log everything to a text window (GUI only of course)
 167 class wxTextCtrl;
 168 class WXDLLEXPORT wxLogTextCtrl : public wxLogStream
 169 {
 170 public:
 171   // we just create an ostream from wxTextCtrl and use it in base class
 172   wxLogTextCtrl(wxTextCtrl *pTextCtrl);
 173  ~wxLogTextCtrl();
 174 };
 175
 176 // ----------------------------------------------------------------------------
 177 // GUI log target, the default one for wxWindows programs
 178 // ----------------------------------------------------------------------------
 179 class WXDLLEXPORT wxLogGui : public wxLog
 180 {
 181 public:
 182   // ctor
 183   wxLogGui();
 184
 185   // show all messages that were logged since the last Flush()
 186   virtual void Flush();
 187
 188 protected:
 189   virtual void DoLog(wxLogLevel level, const char *szString);
 190
 191   wxArrayString m_aMessages;
 192   bool          m_bErrors;
 193 };
 194
 195 // ----------------------------------------------------------------------------
 196 // (background) log window: this class forwards all log messages to the log
 197 // target which was active when it was instantiated, but also collects them
 198 // to the log window. This window has it's own menu which allows the user to
 199 // close it, clear the log contents or save it to the file.
 200 // ----------------------------------------------------------------------------
 201 class wxLogFrame;
 202 class wxFrame;
 203 class WXDLLEXPORT wxLogWindow : public wxLog
 204 {
 205 public:
 206   wxLogWindow(const char *szTitle, bool bShow = TRUE);
 207   ~wxLogWindow();
 208
 209   // window operations
 210     // show/hide the log window
 211   void Show(bool bShow = TRUE);
 212     // get the frame pointer (you shouldn't close it!)
 213   wxFrame *GetFrame() const;
 214
 215   // accessors
 216   wxLog *GetOldLog() const { return m_pOldLog; }
 217
 218 protected:
 219   virtual void DoLog(wxLogLevel level, const char *szString);
 220   virtual void DoLogString(const char *szString);
 221
 222 private:
 223   wxLog      *m_pOldLog;    // previous log target
 224   wxLogFrame *m_pLogFrame;  // the log frame
 225 };
 226
 227 // ----------------------------------------------------------------------------
 228 // /dev/null log target: suppress logging until this object goes out of scope
 229 // ----------------------------------------------------------------------------
 230
 231 // example of usage:
 232 /*
 233 void Foo() {
 234   wxFile file;
 235
 236   // wxFile.Open() normally complains if file can't be opened, we don't want it
 237   wxLogNull logNo;
 238   if ( !file.Open("bar") )
 239     ... process error ourselves ...
 240
 241   // ~wxLogNull called, old log sink restored
 242 }
 243 */
 244 class WXDLLEXPORT wxLogNull
 245 {
 246 public:
 247   // ctor saves old log target, dtor restores it
 248   wxLogNull() { m_pPrevLogger = wxLog::SetActiveTarget(NULL); }
 249  ~wxLogNull() { (void)wxLog::SetActiveTarget(m_pPrevLogger);  }
 250
 251 private:
 252   wxLog *m_pPrevLogger; // old log target
 253 };
 254
 255 // ============================================================================
 256 // global functions
 257 // ============================================================================
 258
 259 // ----------------------------------------------------------------------------
 260 // Log functions should be used by application instead of stdio, iostream &c
 261 // for log messages for easy redirection
 262 // ----------------------------------------------------------------------------
 263
 264 // define wxLog<level>
 265 // -------------------
 266
 267 #define DECLARE_LOG_FUNCTION(level)                                 \
 268         extern void WXDLLEXPORT wxLog##level(const char *szFormat, ...)
 269 #define DECLARE_LOG_FUNCTION2(level, arg1)                          \
 270         extern void WXDLLEXPORT wxLog##level(arg1, const char *szFormat, ...)
 271
 272 // a generic function for all levels (level is passes as parameter)
 273 DECLARE_LOG_FUNCTION2(Generic, wxLogLevel level);
 274
 275 // one function per each level
 276 DECLARE_LOG_FUNCTION(FatalError);
 277 DECLARE_LOG_FUNCTION(Error);
 278 DECLARE_LOG_FUNCTION(Warning);
 279 DECLARE_LOG_FUNCTION(Message);
 280 DECLARE_LOG_FUNCTION(Info);
 281 DECLARE_LOG_FUNCTION(Status);
 282 DECLARE_LOG_FUNCTION(Verbose);
 283
 284 // additional one: as wxLogError, but also logs last system call error code
 285 // and the corresponding error message if available
 286 DECLARE_LOG_FUNCTION(SysError);
 287
 288 // and another one which also takes the error code (for those broken APIs
 289 // that don't set the errno (like registry APIs in Win32))
 290 DECLARE_LOG_FUNCTION2(SysError, long lErrCode);
 291
 292 // debug functions do nothing in release mode
 293 #ifdef  __WXDEBUG__
 294   DECLARE_LOG_FUNCTION(Debug);
 295
 296   // first king of LogTrace is uncoditional: it doesn't check the level,
 297   // while the second one does nothing if all of level bits are not set
 298   // in wxLog::GetActive()->GetTraceMask().
 299   DECLARE_LOG_FUNCTION(Trace);
 300   DECLARE_LOG_FUNCTION2(Trace, wxTraceMask mask);
 301 #else   //!debug
 302   // these functions do nothing
 303   inline void wxLogDebug(const char *, ...) { }
 304   inline void wxLogTrace(const char *, ...) { }
 305   inline void wxLogTrace(wxTraceMask, const char *, ...) { }
 306 #endif
 307
 308
 309 // are we in 'verbose' mode?
 310 // (note that it's often handy to change this var manually from the
 311 //  debugger, thus enabling/disabling verbose reporting for some
 312 //  parts of the program only)
 313 WXDLLEXPORT_DATA(extern bool) g_bVerbose;
 314
 315 // fwd decl to avoid including iostream.h here
 316 class ostream;
 317
 318 // ----------------------------------------------------------------------------
 319 // get error code/error message from system in a portable way
 320 // ----------------------------------------------------------------------------
 321
 322 // return the last system error code
 323 unsigned long WXDLLEXPORT wxSysErrorCode();
 324 // return the error message for given (or last if 0) error code
 325 const char* WXDLLEXPORT wxSysErrorMsg(unsigned long nErrCode = 0);
 326
 327 // ----------------------------------------------------------------------------
 328 // debug only logging functions: use them with API name and error code
 329 // ----------------------------------------------------------------------------
 330
 331 #ifdef  __WXDEBUG__
 332   #define wxLogApiError(api, rc)                                              \
 333                     wxLogDebug("At %s(%d) '%s' failed with error %lx (%s).",  \
 334                                __FILE__, __LINE__, api,                       \
 335                                rc, wxSysErrorMsg(rc))
 336   #define wxLogLastError(api) wxLogApiError(api, wxSysErrorCode())
 337 #else   //!debug
 338   inline void wxLogApiError(const char *, long) { }
 339   inline void wxLogLastError(const char *) { }
 340 #endif  //debug/!debug
 341
 342 #endif  //__LOGH__