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