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