]>
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 | ||
84 | \begin{verbatim} | |
85 | // wxTraceOleCalls is one of standard bit masks | |
86 | wxLogTrace(wxTraceRefCount | wxTraceOleCalls, "Active object ref count: %d", nRef); | |
87 | \end{verbatim} | |
88 | will do something only if the current trace mask contains both | |
89 | {\tt wxTraceRefCount} and {\tt wxTraceOle}, but | |
90 | ||
91 | \begin{verbatim} | |
92 | // wxTRACE_OleCalls is one of standard string masks | |
93 | wxLogTrace(wxTRACE_OleCalls, "IFoo::Bar() called"); | |
94 | \end{verbatim} | |
95 | ||
96 | will log the message if it was preceded by | |
97 | ||
98 | \begin{verbatim} | |
99 | wxLog::AddTraceMask(wxTRACE_OleCalls); | |
100 | \end{verbatim} | |
101 | ||
102 | Using string masks is simpler and allows to easily add custom ones, so this is | |
103 | the preferred way of working with trace messages. The integer trace mask is | |
104 | kept for compatibility and for additional (but very rarely needed) flexibility | |
105 | only. | |
106 | ||
107 | The standard trace masks are given in \helpref{wxLogTrace}{wxlogtrace} | |
108 | documentation. | |
109 | ||
110 | Finally, the {\it wxLog::DoLog()} function automatically prepends a time stamp | |
111 | to all the messages. The format of the time stamp may be changed: it can be | |
112 | any string with \% specificators fully described in the documentation of the | |
113 | standard {\it strftime()} function. For example, the default format is | |
114 | "[\%d/\%b/\%y \%H:\%M:\%S] " which gives something like "[17/Sep/98 22:10:16] " | |
115 | (without quotes) for the current date. Setting an empty string as the time | |
116 | format disables timestamping of the messages completely. | |
117 | ||
118 | {\bf NB:} Timestamping is disabled for Visual C++ users in debug builds by | |
119 | default because otherwise it would be impossible to directly go to the line | |
120 | from which the log message was generated by simply clicking in the debugger | |
121 | window on the corresponding error message. If you wish to enable it, please use | |
122 | \helpref{SetTimestamp}{wxlogsettimestamp} explicitly. | |
123 | ||
124 | \helpref{AddTraceMask}{wxlogaddtracemask}\\ | |
125 | \helpref{RemoveTraceMask}{wxlogremovetracemask}\\ | |
126 | \helpref{IsAllowedTraceMask}{wxlogisallowedtracemask}\\ | |
127 | \helpref{SetVerbose}{wxlogsetverbose}\\ | |
128 | \helpref{GetVerbose}{wxloggetverbose}\\ | |
129 | \helpref{SetTimestamp}{wxlogsettimestamp}\\ | |
130 | \helpref{GetTimestamp}{wxloggettimestamp}\\ | |
131 | \helpref{SetTraceMask}{wxlogsettracemask}\\ | |
132 | \helpref{GetTraceMask}{wxloggettracemask} | |
133 | ||
134 | %%%%% MEMBERS HERE %%%%% | |
135 | \helponly{\insertatlevel{2}{ | |
136 | ||
137 | \wxheading{Members} | |
138 | ||
139 | }} | |
140 | ||
141 | \membersection{wxLog::AddTraceMask}\label{wxlogaddtracemask} | |
142 | ||
143 | \func{static void}{AddTraceMask}{\param{const wxString\& }{mask}} | |
144 | ||
145 | Add the {\it mask} to the list of allowed masks for | |
146 | \helpref{wxLogTrace}{wxlogtrace}. | |
147 | ||
148 | See also: \helpref{RemoveTraceMask}{wxlogremovetracemask} | |
149 | ||
150 | \membersection{wxLog::OnLog}\label{wxlogonlog} | |
151 | ||
152 | \func{static void}{OnLog}{\param{wxLogLevel }{ level}, \param{const char * }{ message}} | |
153 | ||
154 | Forwards the message at specified level to the {\it DoLog()} function of the | |
155 | active log target if there is any, does nothing otherwise. | |
156 | ||
157 | \membersection{wxLog::GetActiveTarget}\label{wxloggetactivetarget} | |
158 | ||
159 | \func{static wxLog *}{GetActiveTarget}{\void} | |
160 | ||
161 | Returns the pointer to the active log target (may be NULL). | |
162 | ||
163 | \membersection{wxLog::SetActiveTarget}\label{wxlogsetactivetarget} | |
164 | ||
165 | \func{static wxLog *}{SetActiveTarget}{\param{wxLog * }{ logtarget}} | |
166 | ||
167 | Sets the specified log target as the active one. Returns the pointer to the | |
168 | previous active log target (may be NULL). | |
169 | ||
170 | \membersection{wxLog::DontCreateOnDemand}\label{wxlogdontcreateondemand} | |
171 | ||
172 | \func{static void}{DontCreateOnDemand}{\void} | |
173 | ||
174 | Instructs wxLog to not create new log targets on the fly if there is none | |
175 | currently. (Almost) for internal use only. | |
176 | ||
177 | \membersection{wxLog::Flush}\label{wxlogflush} | |
178 | ||
179 | \func{virtual void}{Flush}{\void} | |
180 | ||
181 | Shows all the messages currently in buffer and clears it. If the buffer | |
182 | is already empty, nothing happens. | |
183 | ||
184 | \membersection{wxLog::FlushActive}\label{wxlogflushactive} | |
185 | ||
186 | \func{static void}{FlushActive}{\void} | |
187 | ||
188 | Flushes the current log target if any, does nothing if there is none. | |
189 | ||
190 | See also: | |
191 | ||
192 | \helpref{Flush}{wxlogflush} | |
193 | ||
194 | \membersection{wxLog::HasPendingMessages}\label{haspendingmessages} | |
195 | ||
196 | \constfunc{bool}{HasPendingMessages}{\void} | |
197 | ||
198 | Returns true if there are any messages in the buffer (not yet shown to the | |
199 | user). (Almost) for internal use only. | |
200 | ||
201 | \membersection{wxLog::SetVerbose}\label{wxlogsetverbose} | |
202 | ||
203 | \func{void}{SetVerbose}{\param{bool }{ verbose = TRUE}} | |
204 | ||
205 | Activates or desactivates verbose mode in which the verbose messages are | |
206 | logged as the normal ones instead of being silently dropped. | |
207 | ||
208 | \membersection{wxLog::GetVerbose}\label{wxloggetverbose} | |
209 | ||
210 | \constfunc{bool}{GetVerbose}{\void} | |
211 | ||
212 | Returns whether the verbose mode is currently active. | |
213 | ||
214 | \membersection{wxLog::SetTimestamp}\label{wxlogsettimestamp} | |
215 | ||
216 | \func{void}{SetTimestamp}{\param{const char * }{ format}} | |
217 | ||
218 | Sets the timestamp format prepended by the default log targets to all | |
219 | messages. The string may contain any normal characters as well as \% | |
220 | prefixed format specificators, see {\it strftime()} manual for details. | |
221 | Passing a NULL value (not empty string) to this function disables message timestamping. | |
222 | ||
223 | \membersection{wxLog::GetTimestamp}\label{wxloggettimestamp} | |
224 | ||
225 | \constfunc{const char *}{GetTimestamp}{\void} | |
226 | ||
227 | Returns the current timestamp format string. | |
228 | ||
229 | \membersection{wxLog::SetTraceMask}\label{wxlogsettracemask} | |
230 | ||
231 | \func{static void}{SetTraceMask}{\param{wxTraceMask }{ mask}} | |
232 | ||
233 | Sets the trace mask, see \helpref{Customization}{wxlogcustomization} | |
234 | section for details. | |
235 | ||
236 | \membersection{wxLog::GetTraceMask}\label{wxloggettracemask} | |
237 | ||
238 | Returns the current trace mask, see \helpref{Customization}{wxlogcustomization} section | |
239 | for details. | |
240 | ||
241 | \membersection{wxLog::IsAllowedTraceMask}\label{wxlogisallowedtracemask} | |
242 | ||
243 | \func{static bool}{IsAllowedTraceMask}{\param{const wxChar *}{mask}} | |
244 | ||
245 | Returns TRUE if the {\it mask} is one of allowed masks for | |
246 | \helpref{wxLogTrace}{wxlogtrace}. | |
247 | ||
248 | See also: \helpref{AddTraceMask}{wxlogaddtracemask}, | |
249 | \helpref{RemoveTraceMask}{wxlogremovetracemask} | |
250 | ||
251 | \membersection{wxLog::RemoveTraceMask}\label{wxlogremovetracemask} | |
252 | ||
253 | \func{static void}{RemoveTraceMask}{\param{const wxString\& }{mask}} | |
254 | ||
255 | Remove the {\it mask} from the list of allowed masks for | |
256 | \helpref{wxLogTrace}{wxlogtrace}. | |
257 | ||
258 | See also: \helpref{AddTraceMask}{wxlogaddtracemask} | |
259 |