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