]>
Commit | Line | Data |
---|---|---|
c801d85f KB |
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 | ||
34138703 JS |
12 | #ifndef _WX_LOG_H_ |
13 | #define _WX_LOG_H_ | |
c801d85f KB |
14 | |
15 | #ifdef __GNUG__ | |
0d3820b3 JS |
16 | #pragma interface "log.h" |
17 | #endif | |
c801d85f | 18 | |
9ef3052c VZ |
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 | ||
2049ba38 | 45 | #ifdef __WXMSW__ |
9ef3052c VZ |
46 | #define wxTraceOleCalls 0x0100 // OLE interface calls |
47 | #endif | |
48 | ||
49 | typedef unsigned long wxTraceMask; | |
50 | typedef unsigned long wxLogLevel; | |
51 | ||
470b7da3 VZ |
52 | // ---------------------------------------------------------------------------- |
53 | // forward declarations | |
54 | // ---------------------------------------------------------------------------- | |
55 | class wxTextCtrl; | |
56 | class wxLogFrame; | |
57 | class wxFrame; | |
58 | class ostream; | |
59 | ||
c801d85f KB |
60 | // ---------------------------------------------------------------------------- |
61 | // derive from this class to redirect (or suppress, or ...) log messages | |
62 | // normally, only a single instance of this class exists but it's not enforced | |
c801d85f KB |
63 | // ---------------------------------------------------------------------------- |
64 | class WXDLLEXPORT wxLog | |
65 | { | |
66 | public: | |
c801d85f KB |
67 | // ctor |
68 | wxLog(); | |
69 | ||
70 | // sink function | |
9ef3052c | 71 | static void OnLog(wxLogLevel level, const char *szString) |
c801d85f KB |
72 | { if ( ms_pLogger != 0 ) ms_pLogger->DoLog(level, szString); } |
73 | ||
74 | // message buffering | |
75 | // flush shows all messages if they're not logged immediately | |
76 | // (FILE and iostream logs don't need it, but wxGuiLog does to avoid | |
77 | // showing 17 modal dialogs one after another) | |
78 | virtual void Flush(); | |
06db8ebd | 79 | // call to Flush() may be optimized: call it only if this function |
9ef3052c VZ |
80 | // returns true (although Flush() also returns immediately if there |
81 | // is no messages, this functions is more efficient because inline) | |
c801d85f KB |
82 | bool HasPendingMessages() const { return m_bHasMessages; } |
83 | ||
84 | // only one sink is active at each moment | |
275bf4c1 VZ |
85 | // get current log target, will call wxApp::CreateLogTarget() to create one |
86 | // if | |
c801d85f | 87 | static wxLog *GetActiveTarget(); |
4c84fa8d VZ |
88 | // change log target, pLogger = NULL disables logging. if bNoFlashOld is true, |
89 | // the old log target isn't flashed which might lead to loss of messages! | |
c801d85f | 90 | // returns the previous log target |
4c84fa8d | 91 | static wxLog *SetActiveTarget(wxLog *pLogger, bool bNoFlashOld = FALSE); |
c801d85f KB |
92 | |
93 | // functions controlling the default wxLog behaviour | |
94 | // verbose mode is activated by standard command-line '-verbose' option | |
9ef3052c | 95 | void SetVerbose(bool bVerbose = TRUE) { m_bVerbose = bVerbose; } |
c801d85f KB |
96 | // sets the format for timestamp prepended by wxLog::DoLog(): it's |
97 | // passed to strftime() function, see it's documentation for details. | |
9ef3052c VZ |
98 | // no time stamp at all if szTF is NULL or empty |
99 | // NB: the string is not copied, so it's lifetime must be long enough! | |
100 | void SetTimeStampFormat(const char *szTF) { m_szTimeFormat = szTF; } | |
101 | // trace mask (see wxTraceXXX constants for details) | |
46eaa422 | 102 | static void SetTraceMask(wxTraceMask ulMask) { ms_ulTraceMask = ulMask; } |
275bf4c1 VZ |
103 | // should GetActiveTarget() try to create a new log object if the current |
104 | // is NULL? | |
105 | static void DontCreateOnDemand() { ms_bAutoCreate = FALSE; } | |
c801d85f KB |
106 | |
107 | // accessors | |
108 | // gets the verbose status | |
9ef3052c VZ |
109 | bool GetVerbose() const { return m_bVerbose; } |
110 | // get current time format | |
111 | const char *GetTimeStampFormat() const { return m_szTimeFormat; } | |
112 | // get trace mask | |
46eaa422 | 113 | static wxTraceMask GetTraceMask() { return ms_ulTraceMask; } |
c801d85f KB |
114 | |
115 | // make dtor virtual for all derived classes | |
116 | virtual ~wxLog() { } | |
117 | ||
118 | protected: | |
119 | bool m_bHasMessages; | |
120 | ||
9ef3052c VZ |
121 | bool m_bVerbose; // FALSE => ignore LogInfo messages |
122 | const char *m_szTimeFormat; // format for strftime() | |
c801d85f | 123 | |
c801d85f KB |
124 | // the logging functions that can be overriden |
125 | // default DoLog() prepends the time stamp and a prefix corresponding | |
126 | // to the message to szString and then passes it to DoLogString() | |
9ef3052c | 127 | virtual void DoLog(wxLogLevel level, const char *szString); |
c801d85f KB |
128 | // default DoLogString does nothing but is not pure virtual because if |
129 | // you override DoLog() you might not need it at all | |
130 | virtual void DoLogString(const char *szString); | |
06db8ebd | 131 | |
fe7b1156 VZ |
132 | // helpers |
133 | // put the time stamp in the current format into the string | |
134 | wxString TimeStamp() const; | |
135 | ||
9ef3052c VZ |
136 | private: |
137 | // static variables | |
138 | // ---------------- | |
275bf4c1 VZ |
139 | static wxLog *ms_pLogger; // currently active log sink |
140 | static bool ms_bAutoCreate; // automatically create new log targets? | |
46eaa422 | 141 | static wxTraceMask ms_ulTraceMask; // controls wxLogTrace behaviour |
c801d85f KB |
142 | }; |
143 | ||
144 | // ---------------------------------------------------------------------------- | |
145 | // "trivial" derivations of wxLog | |
146 | // ---------------------------------------------------------------------------- | |
147 | ||
148 | // log everything to a "FILE *", stderr by default | |
149 | class WXDLLEXPORT wxLogStderr : public wxLog | |
150 | { | |
151 | public: | |
152 | // redirect log output to a FILE | |
c67daf87 | 153 | wxLogStderr(FILE *fp = (FILE *) NULL); |
c801d85f KB |
154 | |
155 | private: | |
156 | // implement sink function | |
157 | virtual void DoLogString(const char *szString); | |
158 | ||
159 | FILE *m_fp; | |
160 | }; | |
161 | ||
162 | // log everything to an "ostream", cerr by default | |
34138703 | 163 | class ostream; |
c801d85f KB |
164 | class WXDLLEXPORT wxLogStream : public wxLog |
165 | { | |
166 | public: | |
167 | // redirect log output to an ostream | |
c67daf87 | 168 | wxLogStream(ostream *ostr = (ostream *) NULL); |
c801d85f KB |
169 | |
170 | protected: | |
171 | // implement sink function | |
172 | virtual void DoLogString(const char *szString); | |
173 | ||
174 | // @@ using ptr here to avoid including <iostream.h> from this file | |
175 | ostream *m_ostr; | |
176 | }; | |
177 | ||
c801d85f KB |
178 | // log everything to a text window (GUI only of course) |
179 | class WXDLLEXPORT wxLogTextCtrl : public wxLogStream | |
180 | { | |
181 | public: | |
182 | // we just create an ostream from wxTextCtrl and use it in base class | |
183 | wxLogTextCtrl(wxTextCtrl *pTextCtrl); | |
184 | ~wxLogTextCtrl(); | |
185 | }; | |
c801d85f KB |
186 | |
187 | // ---------------------------------------------------------------------------- | |
188 | // GUI log target, the default one for wxWindows programs | |
189 | // ---------------------------------------------------------------------------- | |
190 | class WXDLLEXPORT wxLogGui : public wxLog | |
191 | { | |
192 | public: | |
193 | // ctor | |
194 | wxLogGui(); | |
195 | ||
196 | // show all messages that were logged since the last Flush() | |
197 | virtual void Flush(); | |
198 | ||
199 | protected: | |
9ef3052c | 200 | virtual void DoLog(wxLogLevel level, const char *szString); |
c801d85f KB |
201 | |
202 | wxArrayString m_aMessages; | |
203 | bool m_bErrors; | |
204 | }; | |
205 | ||
9ef3052c VZ |
206 | // ---------------------------------------------------------------------------- |
207 | // (background) log window: this class forwards all log messages to the log | |
208 | // target which was active when it was instantiated, but also collects them | |
209 | // to the log window. This window has it's own menu which allows the user to | |
210 | // close it, clear the log contents or save it to the file. | |
211 | // ---------------------------------------------------------------------------- | |
9ef3052c VZ |
212 | class WXDLLEXPORT wxLogWindow : public wxLog |
213 | { | |
214 | public: | |
470b7da3 VZ |
215 | wxLogWindow(wxFrame *pParent, // the parent frame (can be NULL) |
216 | const char *szTitle, // the title of the frame | |
a3622daa VZ |
217 | bool bShow = TRUE, // show window immediately? |
218 | bool bPassToOld = TRUE); // pass log messages to the old target? | |
9ef3052c | 219 | ~wxLogWindow(); |
06db8ebd VZ |
220 | |
221 | // window operations | |
222 | // show/hide the log window | |
9ef3052c | 223 | void Show(bool bShow = TRUE); |
fe7b1156 | 224 | // retrieve the pointer to the frame |
06db8ebd | 225 | wxFrame *GetFrame() const; |
9ef3052c | 226 | |
2283a22c | 227 | // accessors |
a3622daa | 228 | // the previous log target (may be NULL) |
2283a22c | 229 | wxLog *GetOldLog() const { return m_pOldLog; } |
a3622daa VZ |
230 | // are we passing the messages to the previous log target? |
231 | bool IsPassingMessages() const { return m_bPassMessages; } | |
232 | ||
233 | // we can pass the messages to the previous log target (we're in this mode by | |
234 | // default: we collect all messages in the window, but also let the default | |
235 | // processing take place) | |
236 | void PassMessages(bool bDoPass) { m_bPassMessages = bDoPass; } | |
2283a22c | 237 | |
fe7b1156 VZ |
238 | // base class virtuals |
239 | // we don't need it ourselves, but we pass it to the previous logger | |
240 | virtual void Flush(); | |
241 | ||
242 | // overridables | |
243 | // called immediately after the log frame creation allowing for | |
244 | // any extra initializations | |
245 | virtual void OnFrameCreate(wxFrame *frame); | |
246 | // called right before the log frame is going to be deleted | |
247 | virtual void OnFrameDelete(wxFrame *frame); | |
248 | ||
9ef3052c VZ |
249 | protected: |
250 | virtual void DoLog(wxLogLevel level, const char *szString); | |
251 | virtual void DoLogString(const char *szString); | |
06db8ebd | 252 | |
9ef3052c | 253 | private: |
a3622daa VZ |
254 | bool m_bPassMessages; // pass messages to m_pOldLog? |
255 | wxLog *m_pOldLog; // previous log target | |
256 | wxLogFrame *m_pLogFrame; // the log frame | |
9ef3052c VZ |
257 | }; |
258 | ||
c801d85f KB |
259 | // ---------------------------------------------------------------------------- |
260 | // /dev/null log target: suppress logging until this object goes out of scope | |
261 | // ---------------------------------------------------------------------------- | |
262 | ||
263 | // example of usage: | |
264 | /* | |
265 | void Foo() { | |
266 | wxFile file; | |
267 | ||
268 | // wxFile.Open() normally complains if file can't be opened, we don't want it | |
269 | wxLogNull logNo; | |
270 | if ( !file.Open("bar") ) | |
271 | ... process error ourselves ... | |
272 | ||
273 | // ~wxLogNull called, old log sink restored | |
274 | } | |
275 | */ | |
276 | class WXDLLEXPORT wxLogNull | |
277 | { | |
278 | public: | |
279 | // ctor saves old log target, dtor restores it | |
4c84fa8d | 280 | wxLogNull() { m_pPrevLogger = wxLog::SetActiveTarget((wxLog *)NULL, TRUE); } |
c801d85f KB |
281 | ~wxLogNull() { (void)wxLog::SetActiveTarget(m_pPrevLogger); } |
282 | ||
283 | private: | |
284 | wxLog *m_pPrevLogger; // old log target | |
285 | }; | |
286 | ||
287 | // ============================================================================ | |
288 | // global functions | |
289 | // ============================================================================ | |
290 | ||
291 | // ---------------------------------------------------------------------------- | |
292 | // Log functions should be used by application instead of stdio, iostream &c | |
293 | // for log messages for easy redirection | |
294 | // ---------------------------------------------------------------------------- | |
295 | ||
296 | // define wxLog<level> | |
297 | // ------------------- | |
298 | ||
c801d85f | 299 | #define DECLARE_LOG_FUNCTION(level) \ |
a1530845 VZ |
300 | extern void WXDLLEXPORT wxLog##level(const char *szFormat, ...) |
301 | #define DECLARE_LOG_FUNCTION2(level, arg1) \ | |
302 | extern void WXDLLEXPORT wxLog##level(arg1, const char *szFormat, ...) | |
303 | ||
304 | // a generic function for all levels (level is passes as parameter) | |
305 | DECLARE_LOG_FUNCTION2(Generic, wxLogLevel level); | |
c801d85f KB |
306 | |
307 | // one function per each level | |
308 | DECLARE_LOG_FUNCTION(FatalError); | |
309 | DECLARE_LOG_FUNCTION(Error); | |
310 | DECLARE_LOG_FUNCTION(Warning); | |
311 | DECLARE_LOG_FUNCTION(Message); | |
312 | DECLARE_LOG_FUNCTION(Info); | |
c801d85f KB |
313 | DECLARE_LOG_FUNCTION(Verbose); |
314 | ||
470b7da3 VZ |
315 | // this function sends the log message to the status line of the top level |
316 | // application frame, if any | |
317 | DECLARE_LOG_FUNCTION(Status); | |
318 | ||
319 | // this one is the same as previous except that it allows to explicitly | |
320 | // specify the frame to which the output should go | |
321 | DECLARE_LOG_FUNCTION2(Status, wxFrame *pFrame); | |
322 | ||
c801d85f KB |
323 | // additional one: as wxLogError, but also logs last system call error code |
324 | // and the corresponding error message if available | |
325 | DECLARE_LOG_FUNCTION(SysError); | |
326 | ||
327 | // and another one which also takes the error code (for those broken APIs | |
328 | // that don't set the errno (like registry APIs in Win32)) | |
a1530845 | 329 | DECLARE_LOG_FUNCTION2(SysError, long lErrCode); |
c801d85f | 330 | |
9ef3052c | 331 | // debug functions do nothing in release mode |
b2aef89b | 332 | #ifdef __WXDEBUG__ |
a1530845 | 333 | DECLARE_LOG_FUNCTION(Debug); |
9ef3052c VZ |
334 | |
335 | // first king of LogTrace is uncoditional: it doesn't check the level, | |
336 | // while the second one does nothing if all of level bits are not set | |
337 | // in wxLog::GetActive()->GetTraceMask(). | |
a1530845 VZ |
338 | DECLARE_LOG_FUNCTION(Trace); |
339 | DECLARE_LOG_FUNCTION2(Trace, wxTraceMask mask); | |
9ef3052c | 340 | #else //!debug |
27c9fe75 VZ |
341 | // these functions do nothing |
342 | inline void wxLogDebug(const char *, ...) { } | |
343 | inline void wxLogTrace(const char *, ...) { } | |
344 | inline void wxLogTrace(wxTraceMask, const char *, ...) { } | |
9ef3052c | 345 | #endif |
c801d85f | 346 | |
c801d85f KB |
347 | |
348 | // are we in 'verbose' mode? | |
349 | // (note that it's often handy to change this var manually from the | |
350 | // debugger, thus enabling/disabling verbose reporting for some | |
351 | // parts of the program only) | |
352 | WXDLLEXPORT_DATA(extern bool) g_bVerbose; | |
353 | ||
354 | // fwd decl to avoid including iostream.h here | |
355 | class ostream; | |
356 | ||
357 | // ---------------------------------------------------------------------------- | |
358 | // get error code/error message from system in a portable way | |
359 | // ---------------------------------------------------------------------------- | |
360 | ||
361 | // return the last system error code | |
362 | unsigned long WXDLLEXPORT wxSysErrorCode(); | |
363 | // return the error message for given (or last if 0) error code | |
364 | const char* WXDLLEXPORT wxSysErrorMsg(unsigned long nErrCode = 0); | |
365 | ||
366 | // ---------------------------------------------------------------------------- | |
367 | // debug only logging functions: use them with API name and error code | |
368 | // ---------------------------------------------------------------------------- | |
369 | ||
b2aef89b | 370 | #ifdef __WXDEBUG__ |
c801d85f KB |
371 | #define wxLogApiError(api, rc) \ |
372 | wxLogDebug("At %s(%d) '%s' failed with error %lx (%s).", \ | |
373 | __FILE__, __LINE__, api, \ | |
374 | rc, wxSysErrorMsg(rc)) | |
9ef3052c | 375 | #define wxLogLastError(api) wxLogApiError(api, wxSysErrorCode()) |
c801d85f | 376 | #else //!debug |
27c9fe75 | 377 | inline void wxLogApiError(const char *, long) { } |
db138a4c | 378 | inline void wxLogLastError(const char *) { } |
c801d85f KB |
379 | #endif //debug/!debug |
380 | ||
34138703 | 381 | #endif // _WX_LOG_H_ |