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
  78   static wxLog *GetActiveTarget();
  79     // change log target, pLogger = NULL disables logging,
  80     // returns the previous log target
  81   static wxLog *SetActiveTarget(wxLog *pLogger);
  82
  83   // functions controlling the default wxLog behaviour
  84     // verbose mode is activated by standard command-line '-verbose' option
  85   void SetVerbose(bool bVerbose = TRUE) { m_bVerbose = bVerbose; }
  86     // sets the format for timestamp prepended by wxLog::DoLog(): it's
  87     // passed to strftime() function, see it's documentation for details.
  88     // no time stamp at all if szTF is NULL or empty
  89     // NB: the string is not copied, so it's lifetime must be long enough!
  90   void SetTimeStampFormat(const char *szTF) { m_szTimeFormat = szTF; }
  91     // trace mask (see wxTraceXXX constants for details)
  92   void SetTraceMask(wxTraceMask ulMask) { m_ulTraceMask = ulMask; }
  93
  94   // accessors
  95     // gets the verbose status
  96   bool GetVerbose() const { return m_bVerbose; }
  97     // get current time format
  98   const char *GetTimeStampFormat() const { return m_szTimeFormat; }
  99     // get trace mask
 100   wxTraceMask GetTraceMask() const { return m_ulTraceMask; }
 101
 102   // make dtor virtual for all derived classes
 103   virtual ~wxLog() { }
 104
 105 protected:
 106   bool m_bHasMessages;
 107
 108   bool          m_bVerbose;     // FALSE => ignore LogInfo messages
 109   const char   *m_szTimeFormat; // format for strftime()
 110   wxTraceMask   m_ulTraceMask;  // controls wxLogTrace behaviour
 111
 112   // the logging functions that can be overriden
 113     // default DoLog() prepends the time stamp and a prefix corresponding
 114     // to the message to szString and then passes it to DoLogString()
 115   virtual void DoLog(wxLogLevel level, const char *szString);
 116     // default DoLogString does nothing but is not pure virtual because if
 117     // you override DoLog() you might not need it at all
 118   virtual void DoLogString(const char *szString);
 119
 120 private:
 121   // static variables
 122   // ----------------
 123   static wxLog *ms_pLogger;       // currently active log sink
 124   static bool   ms_bInitialized;  // any log targets created?
 125 };
 126
 127 // ----------------------------------------------------------------------------
 128 // "trivial" derivations of wxLog
 129 // ----------------------------------------------------------------------------
 130
 131 // log everything to a "FILE *", stderr by default
 132 class WXDLLEXPORT wxLogStderr : public wxLog
 133 {
 134 public:
 135   // redirect log output to a FILE
 136   wxLogStderr(FILE *fp = NULL);
 137
 138 private:
 139   // implement sink function
 140   virtual void DoLogString(const char *szString);
 141
 142   FILE *m_fp;
 143 };
 144
 145 // log everything to an "ostream", cerr by default
 146 class WXDLLEXPORT wxLogStream : public wxLog
 147 {
 148 public:
 149   // redirect log output to an ostream
 150   wxLogStream(ostream *ostr = NULL);
 151
 152 protected:
 153   // implement sink function
 154   virtual void DoLogString(const char *szString);
 155
 156   // @@ using ptr here to avoid including <iostream.h> from this file
 157   ostream *m_ostr;
 158 };
 159
 160 // log everything to a text window (GUI only of course)
 161 class wxTextCtrl;
 162 class WXDLLEXPORT wxLogTextCtrl : public wxLogStream
 163 {
 164 public:
 165   // we just create an ostream from wxTextCtrl and use it in base class
 166   wxLogTextCtrl(wxTextCtrl *pTextCtrl);
 167  ~wxLogTextCtrl();
 168 };
 169
 170 // ----------------------------------------------------------------------------
 171 // GUI log target, the default one for wxWindows programs
 172 // ----------------------------------------------------------------------------
 173 class WXDLLEXPORT wxLogGui : public wxLog
 174 {
 175 public:
 176   // ctor
 177   wxLogGui();
 178
 179   // show all messages that were logged since the last Flush()
 180   virtual void Flush();
 181
 182 protected:
 183   virtual void DoLog(wxLogLevel level, const char *szString);
 184
 185   wxArrayString m_aMessages;
 186   bool          m_bErrors;
 187 };
 188
 189 // ----------------------------------------------------------------------------
 190 // (background) log window: this class forwards all log messages to the log
 191 // target which was active when it was instantiated, but also collects them
 192 // to the log window. This window has it's own menu which allows the user to
 193 // close it, clear the log contents or save it to the file.
 194 // ----------------------------------------------------------------------------
 195 class wxLogFrame;
 196 class WXDLLEXPORT wxLogWindow : public wxLog
 197 {
 198 public:
 199   wxLogWindow(const wxTString& strTitle, bool bShow = TRUE);
 200   ~wxLogWindow();
 201
 202   // show/hide the log window
 203   void Show(bool bShow = TRUE);
 204
 205   // accessors
 206   wxLog *GetOldLog() const { return m_pOldLog; }
 207
 208 protected:
 209   virtual void DoLog(wxLogLevel level, const char *szString);
 210   virtual void DoLogString(const char *szString);
 211
 212 private:
 213   wxLog      *m_pOldLog;    // previous log target
 214   wxLogFrame *m_pLogFrame;  // the log frame
 215 };
 216
 217 // ----------------------------------------------------------------------------
 218 // /dev/null log target: suppress logging until this object goes out of scope
 219 // ----------------------------------------------------------------------------
 220
 221 // example of usage:
 222 /*
 223 void Foo() {
 224   wxFile file;
 225
 226   // wxFile.Open() normally complains if file can't be opened, we don't want it
 227   wxLogNull logNo;
 228   if ( !file.Open("bar") )
 229     ... process error ourselves ...
 230
 231   // ~wxLogNull called, old log sink restored
 232 }
 233 */
 234 class WXDLLEXPORT wxLogNull
 235 {
 236 public:
 237   // ctor saves old log target, dtor restores it
 238   wxLogNull() { m_pPrevLogger = wxLog::SetActiveTarget(NULL); }
 239  ~wxLogNull() { (void)wxLog::SetActiveTarget(m_pPrevLogger);  }
 240
 241 private:
 242   wxLog *m_pPrevLogger; // old log target
 243 };
 244
 245 // ============================================================================
 246 // global functions
 247 // ============================================================================
 248
 249 // ----------------------------------------------------------------------------
 250 // Log functions should be used by application instead of stdio, iostream &c
 251 // for log messages for easy redirection
 252 // ----------------------------------------------------------------------------
 253
 254 // define wxLog<level>
 255 // -------------------
 256
 257 // NB: all these functions take `wxTString' and not
 258 //     `const wxTString&' because according to C++ standard
 259 //     the first argument to a vararg function can not be
 260 //     an array, function or reference :-(
 261
 262 // the most generic log function
 263 void WXDLLEXPORT wxLogGeneric(wxLogLevel level, wxTString strFormat, ...);
 264
 265 #define DECLARE_LOG_FUNCTION(level)                                 \
 266         extern void WXDLLEXPORT wxLog##level(wxTString strFormat, ...)
 267
 268 // one function per each level
 269 DECLARE_LOG_FUNCTION(FatalError);
 270 DECLARE_LOG_FUNCTION(Error);
 271 DECLARE_LOG_FUNCTION(Warning);
 272 DECLARE_LOG_FUNCTION(Message);
 273 DECLARE_LOG_FUNCTION(Info);
 274 DECLARE_LOG_FUNCTION(Status);
 275 DECLARE_LOG_FUNCTION(Verbose);
 276
 277 // additional one: as wxLogError, but also logs last system call error code
 278 // and the corresponding error message if available
 279 DECLARE_LOG_FUNCTION(SysError);
 280
 281 // and another one which also takes the error code (for those broken APIs
 282 // that don't set the errno (like registry APIs in Win32))
 283 void WXDLLEXPORT wxLogSysError(long lErrCode, wxTString strFormat, ...);
 284
 285 // debug functions do nothing in release mode
 286 #ifdef  __WXDEBUG__
 287   // NB: debug functions don't translate their arguments
 288   extern void WXDLLEXPORT wxLogDebug(const char *szFormat, ...);
 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   extern void WXDLLEXPORT wxLogTrace(const char *szFormat, ...);
 294   extern void WXDLLEXPORT wxLogTrace(wxTraceMask mask,
 295                                      const char *szFormat, ...);
 296 #else   //!debug
 297   #define wxLogDebug
 298   #define wxLogTrace
 299 #endif
 300
 301
 302 // are we in 'verbose' mode?
 303 // (note that it's often handy to change this var manually from the
 304 //  debugger, thus enabling/disabling verbose reporting for some
 305 //  parts of the program only)
 306 WXDLLEXPORT_DATA(extern bool) g_bVerbose;
 307
 308 // fwd decl to avoid including iostream.h here
 309 class ostream;
 310
 311 // ----------------------------------------------------------------------------
 312 // get error code/error message from system in a portable way
 313 // ----------------------------------------------------------------------------
 314
 315 // return the last system error code
 316 unsigned long WXDLLEXPORT wxSysErrorCode();
 317 // return the error message for given (or last if 0) error code
 318 const char* WXDLLEXPORT wxSysErrorMsg(unsigned long nErrCode = 0);
 319
 320 // ----------------------------------------------------------------------------
 321 // debug only logging functions: use them with API name and error code
 322 // ----------------------------------------------------------------------------
 323
 324 #ifdef  __WXDEBUG__
 325   #define wxLogApiError(api, rc)                                              \
 326                     wxLogDebug("At %s(%d) '%s' failed with error %lx (%s).",  \
 327                                __FILE__, __LINE__, api,                       \
 328                                rc, wxSysErrorMsg(rc))
 329   #define wxLogLastError(api) wxLogApiError(api, wxSysErrorCode())
 330 #else   //!debug
 331   #define wxLogApiError(api, rc)
 332   #define wxLogLastError(api)
 333 #endif  //debug/!debug
 334
 335 #endif  //__LOGH__