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