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