]>
Commit | Line | Data |
---|---|---|
5f3cd8a2 VZ |
1 | \section{Log classes overview}\label{wxlogoverview} |
2 | ||
dface61c JS |
3 | Classes: \helpref{wxLog}{wxlog}, wxLogStderr, |
4 | wxLogOstream, wxLogTextCtrl, wxLogWindow, wxLogGui, wxLogNull | |
5f3cd8a2 VZ |
5 | |
6 | This is a general overview of logging classes provided by wxWindows. The word | |
7 | logging here has a broad sense, including all of the program output, not only | |
8 | non interactive messages. The logging facilities included in wxWindows provide | |
9 | the base {\it wxLog} class which defines the standard interface for a {\it log | |
10 | target} as well as several standard implementations of it and a family of | |
11 | functions to use with them. | |
12 | ||
13 | First of all, no knowledge of {\it wxLog} classes is needed to use them. For | |
14 | this, you should only know about {\it wxLogXXX()} functions. All of them have | |
15 | the same syntax as {\it printf()}, i.e. they take the format string as the | |
16 | first argument and a variable number of arguments. Here are all of them: | |
2319d2b0 | 17 | |
5f3cd8a2 VZ |
18 | \begin{itemize}\itemsep=0pt |
19 | \item{\bf wxLogFatalError} which is like {\it wxLogError}, but also | |
20 | terminates the program with the exit code 3 (using {\it abort()} standard | |
21 | function also terminates the program with this exit code). | |
5f3cd8a2 VZ |
22 | \item{\bf wxLogError} is the function to use for error messages, i.e. the |
23 | messages that must be shown to the user. The default processing is to pop up a | |
24 | message box to inform the user about it. | |
5f3cd8a2 VZ |
25 | \item{\bf wxLogWarning} for warnings - they are also normally shown to the |
26 | user, but don't interrupt the program work. | |
5f3cd8a2 VZ |
27 | \item{\bf wxLogMessage} is for all normal, informational messages. They also |
28 | appear in a message box by default (but it can be changed, see below). Notice | |
29 | that the standard behaviour is to not show informational messages if there are | |
30 | any errors later - the logic being that the later error messages make the | |
31 | informational messages preceding them meaningless. | |
5f3cd8a2 VZ |
32 | \item{\bf wxLogVerbose} is for verbose output. Normally, it's suppressed, but |
33 | might be activated if the user wishes to know more details about the program | |
34 | progress (another, but possibly confusing name for the same function is {\bf | |
0f358732 | 35 | wxLogInfo}). |
5f3cd8a2 | 36 | \item{\bf wxLogStatus} is for status messages - they will go into the status |
42ff6409 | 37 | bar of the active or specified (as the first argument) \helpref{wxFrame}{wxframe} if it has one. |
5f3cd8a2 VZ |
38 | \item{\bf wxLogSysError} is mostly used by wxWindows itself, but might be |
39 | handy for logging errors after system call (API function) failure. It logs the | |
6fb26ea3 JS |
40 | specified message text as well as the last system error |
41 | code ({\it errno} or {\it ::GetLastError()} depending on the platform) and the corresponding error | |
5f3cd8a2 VZ |
42 | message. The second form of this function takes the error code explitly as the |
43 | first argument. | |
5f3cd8a2 VZ |
44 | \item{\bf wxLogDebug} is {\bf the} right function for debug output. It only |
45 | does anything at all in the debug mode (when the preprocessor symbol | |
46 | \_\_WXDEBUG\_\_ is defined) and expands to nothing in release mode (otherwise). | |
de6019fb | 47 | {\bf Tip:} under Windows, you must either run the program under debugger or |
47f7a3a7 VZ |
48 | use a 3rd party program such as \urlref{DbgView}{http://www.sysinternals.com} |
49 | to actually see the debug output. | |
5f3cd8a2 VZ |
50 | \item{\bf wxLogTrace} as {\bf wxLogDebug} only does something in debug |
51 | build. The reason for making it a separate function from it is that usually | |
52 | there are a lot of trace messages, so it might make sense to separate them | |
53 | from other debug messages which would be flooded in them. Moreover, the second | |
54 | version of this function takes a trace mask as the first argument which allows | |
55 | to further restrict the amount of messages generated. | |
5f3cd8a2 VZ |
56 | \end{itemize} |
57 | ||
5f3cd8a2 VZ |
58 | The usage of these functions should be fairly straightforward, however it may |
59 | be asked why not use the other logging facilities, such as C standard stdio | |
60 | functions or C++ streams. The short answer is that they're all very good | |
61 | generic mechanisms, but are not really adapted for wxWindows, while the log | |
62 | classes are. Some of advantages in using wxWindows log functions are: | |
5f3cd8a2 | 63 | |
2319d2b0 | 64 | \begin{itemize}\itemsep=0pt |
42ff6409 | 65 | \item{\bf Portability} It's a common practice to use {\it printf()} statements or |
5f3cd8a2 | 66 | cout/cerr C++ streams for writing out some (debug or otherwise) information. |
0f358732 | 67 | Although it works just fine under Unix, these messages go strictly nowhere |
5f3cd8a2 VZ |
68 | under Windows where the stdout of GUI programs is not assigned to anything. |
69 | Thus, you might view {\it wxLogMessage()} as a simple substitute for {\it | |
70 | printf()}. | |
42ff6409 | 71 | \item{\bf Flexibility} The output of wxLog functions can be redirected or |
5f3cd8a2 VZ |
72 | suppressed entirely based on their importance, which is either impossible or |
73 | difficult to do with traditional methods. For example, only error messages, or | |
74 | only error messages and warnings might be logged, filtering out all | |
75 | informational messages. | |
42ff6409 | 76 | \item{\bf Completeness} Usually, an error message should be presented to the user |
5f3cd8a2 VZ |
77 | when some operation fails. Let's take a quite simple but common case of a file |
78 | error: suppose that you're writing your data file on disk and there is not | |
79 | enough space. The actual error might have been detected inside wxWindows code | |
80 | (say, in {\it wxFile::Write}), so the calling function doesn't really know the | |
81 | exact reason of the failure, it only knows that the data file couldn't be | |
82 | written to the disk. However, as wxWindows uses {\it wxLogError()} in this | |
83 | situation, the exact error code (and the corresponding error message) will be | |
84 | given to the user together with "high level" message about data file writing | |
85 | error. | |
5f3cd8a2 VZ |
86 | \end{itemize} |
87 | ||
88 | After having enumerated all the functions which are normally used to log the | |
89 | messages, and why would you want to use them we now describe how all this | |
90 | works. | |
91 | ||
92 | wxWindows has the notion of a {\it log target}: it's just a class deriving | |
93 | from \helpref{wxLog}{wxlog}. As such, it implements the virtual functions of | |
94 | the base class which are called when a message is logged. Only one log target | |
95 | is {\it active} at any moment, this is the one used by \it{wxLogXXX()} | |
96 | functions. The normal usage of a log object (i.e. object of a class derived | |
97 | from wxLog) is to install it as the active target with a call to {\it | |
98 | SetActiveTarget()} and it will be used automatically by all subsequent calls | |
99 | to {\it wxLogXXX()} functions. | |
100 | ||
101 | To create a new log target class you only need to derive it from wxLog and | |
102 | implement one (or both) of {\it DoLog()} and {\it DoLogString()} in it. The | |
103 | second one is enough if you're happy with the standard wxLog message | |
104 | formatting (prepending "Error:" or "Warning:", timestamping \&c) but just want | |
105 | to send the messages somewhere else. The first one may be overridden to do | |
106 | whatever you want but you have to distinguish between the different message | |
107 | types yourself. | |
108 | ||
109 | There are some predefined classes deriving from wxLog and which might be | |
110 | helpful to see how you can create a new log target class and, of course, may | |
111 | also be used without any change. There are: | |
2319d2b0 | 112 | |
5f3cd8a2 VZ |
113 | \begin{itemize}\itemsep=0pt |
114 | \item{\bf wxLogStderr} This class logs messages to a {\it FILE *}, using | |
115 | stderr by default as its name suggests. | |
5f3cd8a2 VZ |
116 | \item{\bf wxLogStream} This class has the same functionality as wxLogStderr, |
117 | but uses {\it ostream} and cerr instead of {\it FILE *} and stderr. | |
5f3cd8a2 VZ |
118 | \item{\bf wxLogGui} This is the standard log target for wxWindows |
119 | applications (it's used by default if you don't do anything) and provides the | |
120 | most reasonable handling of all types of messages for given platform. | |
5f3cd8a2 VZ |
121 | \item{\bf wxLogWindow} This log target provides a "log console" which |
122 | collects all messages generated by the application and also passes them to the | |
123 | previous active log target. The log window frame has a menu allowing user to | |
124 | clear the log, close it completely or save all messages to file. | |
5f3cd8a2 VZ |
125 | \item{\bf wxLogNull} The last log class is quite particular: it doesn't do |
126 | anything. The objects of this class may be instantiated to (temporarily) | |
127 | suppress output of {\it wxLogXXX()} functions. As an example, trying to open a | |
09914df7 VZ |
128 | non-existing file will usually provoke an error message, but if for some |
129 | reasons it's unwanted, just use this construction: | |
2319d2b0 JS |
130 | |
131 | {\small | |
5f3cd8a2 VZ |
132 | \begin{verbatim} |
133 | wxFile file; | |
134 | ||
135 | // wxFile.Open() normally complains if file can't be opened, we don't want it | |
136 | { | |
137 | wxLogNull logNo; | |
138 | if ( !file.Open("bar") ) | |
139 | ... process error ourselves ... | |
140 | } // ~wxLogNull called, old log sink restored | |
141 | ||
142 | wxLogMessage("..."); // ok | |
143 | \end{verbatim} | |
2319d2b0 | 144 | } |
5f3cd8a2 | 145 | \end{itemize} |
2319d2b0 | 146 |