]>
Commit | Line | Data |
---|---|---|
1 | \section{\class{wxLog}}\label{wxlog} | |
2 | ||
3 | wxLog class defines the interface for the {\it log targets} used by wxWindows | |
4 | logging functions as explained in the \helpref{wxLog overview}{wxlogoverview}. | |
5 | The only situations when you need to directly use this class is when you want | |
6 | to derive your own log target because the existing ones don't satisfy your | |
7 | needs. Another case is if you wish to customize the behaviour of the standard | |
8 | logging classes (all of which respect the wxLog settings): for example, set | |
9 | which trace messages are logged and which are not or change (or even remove | |
10 | completely) the timestamp on the messages. | |
11 | ||
12 | Otherwise, it is completely hidden behind the {\it wxLogXXX()} functions and | |
13 | you may not even know about its existence. | |
14 | ||
15 | See \helpref{log overview}{wxlogoverview} for the descriptions of wxWindows | |
16 | logging facilities. | |
17 | ||
18 | \wxheading{Derived from} | |
19 | ||
20 | No base class | |
21 | ||
22 | \wxheading{Include files} | |
23 | ||
24 | <wx/log.h> | |
25 | ||
26 | \latexignore{\rtfignore{\wxheading{Function groups}}} | |
27 | ||
28 | \membersection{Static functions} | |
29 | ||
30 | The functions in this section work with and manipulate the active log target. | |
31 | The {\it OnLog()} is called by the {\it wxLogXXX()} functions and invokes the | |
32 | {\it DoLog()} of the active log target if any. Get/Set methods are used to | |
33 | install/query the current active target and, finally, {\it | |
34 | DontCreateOnDemand()} disables the automatic creation of a standard log target | |
35 | if none actually exists. It is only useful when the application is terminating | |
36 | and shouldn't be used in other situations because it may easily lead to a loss | |
37 | of messages. | |
38 | ||
39 | \helpref{OnLog}{wxlogonlog}\\ | |
40 | \helpref{GetActiveTarget}{wxloggetactivetarget}\\ | |
41 | \helpref{SetActiveTarget}{wxlogsetactivetarget}\\ | |
42 | \helpref{DontCreateOnDemand}{wxlogdontcreateondemand} | |
43 | ||
44 | \membersection{Message buffering} | |
45 | ||
46 | Some of wxLog implementations, most notably the standard | |
47 | wxLogGui class, buffer the messages (for example, to avoid | |
48 | showing the user a zillion of modal message boxes one after another - which | |
49 | would be really annoying). {\it Flush()} shows them all and clears the buffer | |
50 | contents. Although this function doesn't do anything if the buffer is already | |
51 | empty, {\it HasPendingMessages()} is also provided which allows to explicitly | |
52 | verify it. | |
53 | ||
54 | \helpref{Flush}{wxlogflush}\\ | |
55 | \helpref{FlushActive}{wxlogflushactive}\\ | |
56 | \helpref{HasPendingMessages}{haspendingmessages} | |
57 | ||
58 | \membersection{Customization}\label{wxlogcustomization} | |
59 | ||
60 | The functions below allow some limited customization of wxLog behaviour | |
61 | without writing a new log target class (which, aside of being a matter of | |
62 | several minutes, allows you to do anything you want). | |
63 | ||
64 | The verbose messages are the trace messages which are not disabled in the | |
65 | release mode and are generated by \helpref{wxLogVerbose}{wxlogverbose}. They | |
66 | are not normally shown to the user because they present little interest, but | |
67 | may be activated, for example, in order to help the user find some program | |
68 | problem. | |
69 | ||
70 | As for the (real) trace messages, their handling depends on the settings of | |
71 | the (application global) {\it trace mask}. There are two ways to specify it: | |
72 | either by using \helpref{SetTraceMask}{wxlogsettracemask} and | |
73 | \helpref{GetTraceMask}{wxloggettracemask} and using | |
74 | \helpref{wxLogTrace}{wxlogtrace} which takes an integer mask or by using | |
75 | \helpref{AddTraceMask}{wxlogaddtracemask} for string trace masks. | |
76 | ||
77 | The difference between bit-wise and string trace masks is that a message using | |
78 | integer trace mask will only be logged if all bits of the mask are set in the | |
79 | current mask while a message using string mask will be logged simply if the | |
80 | mask had been added before to the list of allowed ones. | |
81 | ||
82 | For example, | |
83 | \begin{verbatim} | |
84 | // wxTraceOleCalls is one of standard bit masks | |
85 | wxLogTrace(wxTraceRefCount | wxTraceOleCalls, "Active object ref count: %d", nRef); | |
86 | \end{verbatim} | |
87 | will do something only if the current trace mask contains both | |
88 | {\tt wxTraceRefCount} and {\tt wxTraceOle}, but | |
89 | \begin{verbatim} | |
90 | // wxTRACE_OleCalls is one of standard string masks | |
91 | wxLogTrace(wxTRACE_OleCalls, "IFoo::Bar() called"); | |
92 | \end{verbatim} | |
93 | will log the message if it was preceded by | |
94 | \begin{verbatim} | |
95 | wxLog::AddTraceMask(wxTRACE_OleCalls); | |
96 | \end{verbatim} | |
97 | ||
98 | Using string masks is simpler and allows to easily add custom ones, so this is | |
99 | the preferred way of working with trace messages. The integer trace mask is | |
100 | kept for compatibility and for additional (but very rarely needed) flexibility | |
101 | only. | |
102 | ||
103 | The standard trace masks are given in \helpref{wxLogTrace}{wxlogtrace} | |
104 | documentation. | |
105 | ||
106 | Finally, the {\it wxLog::DoLog()} function automatically prepends a time stamp | |
107 | to all the messages. The format of the time stamp may be changed: it can be | |
108 | any string with \% specificators fully described in the documentation of the | |
109 | standard {\it strftime()} function. For example, the default format is | |
110 | "[\%d/\%b/\%y \%H:\%M:\%S] " which gives something like "[17/Sep/98 22:10:16] " | |
111 | (without quotes) for the current date. Setting an empty string as the time | |
112 | format disables timestamping of the messages completely. | |
113 | ||
114 | {\bf NB:} Timestamping is disabled for Visual C++ users in debug builds by | |
115 | default because otherwise it would be impossible to directly go to the line | |
116 | from which the log message was generated by simply clicking in the debugger | |
117 | window on the corresponding error message. If you wish to enable it, please use | |
118 | \helpref{SetTimestamp}{wxlogsettimestamp} explicitly. | |
119 | ||
120 | \helpref{AddTraceMask}{wxlogaddtracemask}\\ | |
121 | \helpref{RemoveTraceMask}{wxlogremovetracemask}\\ | |
122 | \helpref{IsAllowedTraceMask}{wxlogisallowedtracemask}\\ | |
123 | \helpref{SetVerbose}{wxlogsetverbose}\\ | |
124 | \helpref{GetVerbose}{wxloggetverbose}\\ | |
125 | \helpref{SetTimestamp}{wxlogsettimestamp}\\ | |
126 | \helpref{GetTimestamp}{wxloggettimestamp}\\ | |
127 | \helpref{SetTraceMask}{wxlogsettracemask}\\ | |
128 | \helpref{GetTraceMask}{wxloggettracemask} | |
129 | ||
130 | %%%%% MEMBERS HERE %%%%% | |
131 | \helponly{\insertatlevel{2}{ | |
132 | ||
133 | \wxheading{Members} | |
134 | ||
135 | }} | |
136 | ||
137 | \membersection{wxLog::AddTraceMask}\label{wxlogaddtracemask} | |
138 | ||
139 | \func{static void}{AddTraceMask}{\param{const wxString\& }{mask}} | |
140 | ||
141 | Add the {\it mask} to the list of allowed masks for | |
142 | \helpref{wxLogTrace}{wxlogtrace}. | |
143 | ||
144 | See also: \helpref{RemoveTraceMask}{wxlogremovetracemask} | |
145 | ||
146 | \membersection{wxLog::OnLog}\label{wxlogonlog} | |
147 | ||
148 | \func{static void}{OnLog}{\param{wxLogLevel }{ level}, \param{const char * }{ message}} | |
149 | ||
150 | Forwards the message at specified level to the {\it DoLog()} function of the | |
151 | active log target if there is any, does nothing otherwise. | |
152 | ||
153 | \membersection{wxLog::GetActiveTarget}\label{wxloggetactivetarget} | |
154 | ||
155 | \func{static wxLog *}{GetActiveTarget}{\void} | |
156 | ||
157 | Returns the pointer to the active log target (may be NULL). | |
158 | ||
159 | \membersection{wxLog::SetActiveTarget}\label{wxlogsetactivetarget} | |
160 | ||
161 | \func{static wxLog *}{SetActiveTarget}{\param{wxLog * }{ logtarget}} | |
162 | ||
163 | Sets the specified log target as the active one. Returns the pointer to the | |
164 | previous active log target (may be NULL). | |
165 | ||
166 | \membersection{wxLog::DontCreateOnDemand}\label{wxlogdontcreateondemand} | |
167 | ||
168 | \func{static void}{DontCreateOnDemand}{\void} | |
169 | ||
170 | Instructs wxLog to not create new log targets on the fly if there is none | |
171 | currently. (Almost) for internal use only. | |
172 | ||
173 | \membersection{wxLog::Flush}\label{wxlogflush} | |
174 | ||
175 | \func{virtual void}{Flush}{\void} | |
176 | ||
177 | Shows all the messages currently in buffer and clears it. If the buffer | |
178 | is already empty, nothing happens. | |
179 | ||
180 | \membersection{wxLog::FlushActive}\label{wxlogflushactive} | |
181 | ||
182 | \func{static void}{FlushActive}{\void} | |
183 | ||
184 | Flushes the current log target if any, does nothing if there is none. | |
185 | ||
186 | See also: | |
187 | ||
188 | \helpref{Flush}{wxlogflush} | |
189 | ||
190 | \membersection{wxLog::HasPendingMessages}\label{haspendingmessages} | |
191 | ||
192 | \constfunc{bool}{HasPendingMessages}{\void} | |
193 | ||
194 | Returns true if there are any messages in the buffer (not yet shown to the | |
195 | user). (Almost) for internal use only. | |
196 | ||
197 | \membersection{wxLog::SetVerbose}\label{wxlogsetverbose} | |
198 | ||
199 | \func{void}{SetVerbose}{\param{bool }{ verbose = TRUE}} | |
200 | ||
201 | Activates or desactivates verbose mode in which the verbose messages are | |
202 | logged as the normal ones instead of being silently dropped. | |
203 | ||
204 | \membersection{wxLog::GetVerbose}\label{wxloggetverbose} | |
205 | ||
206 | \constfunc{bool}{GetVerbose}{\void} | |
207 | ||
208 | Returns whether the verbose mode is currently active. | |
209 | ||
210 | \membersection{wxLog::SetTimestamp}\label{wxlogsettimestamp} | |
211 | ||
212 | \func{void}{SetTimestamp}{\param{const char * }{ format}} | |
213 | ||
214 | Sets the timestamp format prepended by the default log targets to all | |
215 | messages. The string may contain any normal characters as well as \% | |
216 | prefixed format specificators, see {\it strftime()} manual for details. | |
217 | Passing a NULL value (not empty string) to this function disables message timestamping. | |
218 | ||
219 | \membersection{wxLog::GetTimestamp}\label{wxloggettimestamp} | |
220 | ||
221 | \constfunc{const char *}{GetTimestamp}{\void} | |
222 | ||
223 | Returns the current timestamp format string. | |
224 | ||
225 | \membersection{wxLog::SetTraceMask}\label{wxlogsettracemask} | |
226 | ||
227 | \func{static void}{SetTraceMask}{\param{wxTraceMask }{ mask}} | |
228 | ||
229 | Sets the trace mask, see \helpref{Customization}{wxlogcustomization} | |
230 | section for details. | |
231 | ||
232 | \membersection{wxLog::GetTraceMask}\label{wxloggettracemask} | |
233 | ||
234 | Returns the current trace mask, see \helpref{Customization}{wxlogcustomization} section | |
235 | for details. | |
236 | ||
237 | \membersection{wxLog::IsAllowedTraceMask}\label{wxlogisallowedtracemask} | |
238 | ||
239 | \func{static bool}{IsAllowedTraceMask}{\param{const wxChar *}{mask}} | |
240 | ||
241 | Returns TRUE if the {\it mask} is one of allowed masks for | |
242 | \helpref{wxLogTrace}{wxlogtrace}. | |
243 | ||
244 | See also: \helpref{AddTraceMask}{wxlogaddtracemask}, | |
245 | \helpref{RemoveTraceMask}{wxlogremovetracemask} | |
246 | ||
247 | \membersection{wxLog::RemoveTraceMask}\label{wxlogremovetracemask} | |
248 | ||
249 | \func{static void}{RemoveTraceMask}{\param{const wxString\& }{mask}} | |
250 | ||
251 | Remove the {\it mask} from the list of allowed masks for | |
252 | \helpref{wxLogTrace}{wxlogtrace}. | |
253 | ||
254 | See also: \helpref{AddTraceMask}{wxlogaddtracemask} | |
255 |