1 \section{\class{wxLog
}}\label{wxlog
}
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.
12 Otherwise, it is completely hidden behind the
{\it wxLogXXX()
} functions and
13 you may not even know about its existence.
15 See
\helpref{log overview
}{wxlogoverview
} for the descriptions of wxWindows
18 \wxheading{Derived from
}
22 \wxheading{Include files
}
26 \latexignore{\rtfignore{\wxheading{Function groups
}}}
28 \membersection{Static functions
}
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,
34 \helpref{DontCreateOnDemand()
}{wxlogdontcreateondemand
}
35 disables the automatic creation of a standard log target
36 if none actually exists. It is only useful when the application is terminating
37 and shouldn't be used in other situations because it may easily lead to a loss
40 \helpref{OnLog
}{wxlogonlog
}\\
41 \helpref{GetActiveTarget
}{wxloggetactivetarget
}\\
42 \helpref{SetActiveTarget
}{wxlogsetactivetarget
}\\
43 \helpref{DontCreateOnDemand
}{wxlogdontcreateondemand
}\\
44 \helpref{Suspend
}{wxlogsuspend
}\\
45 \helpref{Resume
}{wxlogresume
}
47 \membersection{Message buffering
}
49 Some of wxLog implementations, most notably the standard
50 wxLogGui class, buffer the messages (for example, to avoid
51 showing the user a zillion of modal message boxes one after another - which
52 would be really annoying).
{\it Flush()
} shows them all and clears the buffer
53 contents. Although this function doesn't do anything if the buffer is already
54 empty,
{\it HasPendingMessages()
} is also provided which allows to explicitly
57 \helpref{Flush
}{wxlogflush
}\\
58 \helpref{FlushActive
}{wxlogflushactive
}\\
59 \helpref{HasPendingMessages
}{haspendingmessages
}
61 \membersection{Customization
}\label{wxlogcustomization
}
63 The functions below allow some limited customization of wxLog behaviour
64 without writing a new log target class (which, aside of being a matter of
65 several minutes, allows you to do anything you want).
67 The verbose messages are the trace messages which are not disabled in the
68 release mode and are generated by
\helpref{wxLogVerbose
}{wxlogverbose
}. They
69 are not normally shown to the user because they present little interest, but
70 may be activated, for example, in order to help the user find some program
73 As for the (real) trace messages, their handling depends on the settings of
74 the (application global)
{\it trace mask
}. There are two ways to specify it:
75 either by using
\helpref{SetTraceMask
}{wxlogsettracemask
} and
76 \helpref{GetTraceMask
}{wxloggettracemask
} and using
77 \helpref{wxLogTrace
}{wxlogtrace
} which takes an integer mask or by using
78 \helpref{AddTraceMask
}{wxlogaddtracemask
} for string trace masks.
80 The difference between bit-wise and string trace masks is that a message using
81 integer trace mask will only be logged if all bits of the mask are set in the
82 current mask while a message using string mask will be logged simply if the
83 mask had been added before to the list of allowed ones.
88 // wxTraceOleCalls is one of standard bit masks
89 wxLogTrace(wxTraceRefCount | wxTraceOleCalls, "Active object ref count:
%d", nRef);
91 will do something only if the current trace mask contains both
92 {\tt wxTraceRefCount
} and
{\tt wxTraceOle
}, but
95 // wxTRACE_OleCalls is one of standard string masks
96 wxLogTrace(wxTRACE_OleCalls, "IFoo::Bar() called");
99 will log the message if it was preceded by
102 wxLog::AddTraceMask(wxTRACE_OleCalls);
105 Using string masks is simpler and allows to easily add custom ones, so this is
106 the preferred way of working with trace messages. The integer trace mask is
107 kept for compatibility and for additional (but very rarely needed) flexibility
110 The standard trace masks are given in
\helpref{wxLogTrace
}{wxlogtrace
}
113 Finally, the
{\it wxLog::DoLog()
} function automatically prepends a time stamp
114 to all the messages. The format of the time stamp may be changed: it can be
115 any string with \% specificators fully described in the documentation of the
116 standard
{\it strftime()
} function. For example, the default format is
117 "
[\%d/\%b/\%y \%H:\%M:\%S
] " which gives something like "
[17/Sep/
98 22:
10:
16] "
118 (without quotes) for the current date. Setting an empty string as the time
119 format disables timestamping of the messages completely.
121 {\bf NB:
} Timestamping is disabled for Visual C++ users in debug builds by
122 default because otherwise it would be impossible to directly go to the line
123 from which the log message was generated by simply clicking in the debugger
124 window on the corresponding error message. If you wish to enable it, please use
125 \helpref{SetTimestamp
}{wxlogsettimestamp
} explicitly.
127 \helpref{AddTraceMask
}{wxlogaddtracemask
}\\
128 \helpref{RemoveTraceMask
}{wxlogremovetracemask
}\\
129 \helpref{ClearTraceMasks
}{wxlogcleartracemasks
}\\
130 \helpref{IsAllowedTraceMask
}{wxlogisallowedtracemask
}\\
131 \helpref{SetVerbose
}{wxlogsetverbose
}\\
132 \helpref{GetVerbose
}{wxloggetverbose
}\\
133 \helpref{SetTimestamp
}{wxlogsettimestamp
}\\
134 \helpref{GetTimestamp
}{wxloggettimestamp
}\\
135 \helpref{SetTraceMask
}{wxlogsettracemask
}\\
136 \helpref{GetTraceMask
}{wxloggettracemask
}
138 %%%%% MEMBERS HERE %%%%%
139 \helponly{\insertatlevel{2}{
145 \membersection{wxLog::AddTraceMask
}\label{wxlogaddtracemask
}
147 \func{static void
}{AddTraceMask
}{\param{const wxString\&
}{mask
}}
149 Add the
{\it mask
} to the list of allowed masks for
150 \helpref{wxLogTrace
}{wxlogtrace
}.
152 See also:
\helpref{RemoveTraceMask
}{wxlogremovetracemask
}
154 \membersection{wxLog::ClearTraceMasks
}\label{wxlogcleartracemasks
}
156 \func{static void
}{ClearTraceMasks
}{\void}
158 Removes all trace masks previously set with
159 \helpref{AddTraceMask
}{wxlogaddtracemask
}.
161 See also:
\helpref{RemoveTraceMask
}{wxlogremovetracemask
}
163 \membersection{wxLog::OnLog
}\label{wxlogonlog
}
165 \func{static void
}{OnLog
}{\param{wxLogLevel
}{ level
},
\param{const char *
}{ message
}}
167 Forwards the message at specified level to the
{\it DoLog()
} function of the
168 active log target if there is any, does nothing otherwise.
170 \membersection{wxLog::GetActiveTarget
}\label{wxloggetactivetarget
}
172 \func{static wxLog *
}{GetActiveTarget
}{\void}
174 Returns the pointer to the active log target (may be NULL).
176 \membersection{wxLog::SetActiveTarget
}\label{wxlogsetactivetarget
}
178 \func{static wxLog *
}{SetActiveTarget
}{\param{wxLog *
}{ logtarget
}}
180 Sets the specified log target as the active one. Returns the pointer to the
181 previous active log target (may be NULL).
183 \membersection{wxLog::Suspend
}\label{wxlogsuspend
}
185 \func{static void
}{Suspend
}{\void}
187 Suspends the logging until
\helpref{Resume
}{wxlogresume
} is called. Note that
188 the latter must be called the same number of times as the former to undo it,
189 i.e. if you call Suspend() twice you must call Resume() twice as well.
191 Note that suspending the logging means that the log sink won't be be flushed
192 periodically, it doesn't have any effect if the current log target does the
193 logging immediately without waiting for
\helpref{Flush
}{wxlogflush
} to be
194 called (the standard GUI log target only shows the log dialog when it is
195 flushed, so Suspend() works as expected with it).
197 \wxheading{See also:
}
199 \helpref{Resume
}{wxlogresume
},\\
200 \helpref{wxLogNull
}{wxlogoverview
}
202 \membersection{wxLog::Resume
}\label{wxlogresume
}
204 \func{static void
}{Resume
}{\void}
206 Resumes logging previously suspended by a call to
207 \helpref{Suspend
}{wxlogsuspend
}. All messages logged in the meanwhile will be
210 \membersection{wxLog::DontCreateOnDemand
}\label{wxlogdontcreateondemand
}
212 \func{static void
}{DontCreateOnDemand
}{\void}
214 Instructs wxLog to not create new log targets on the fly if there is none
215 currently. (Almost) for internal use only: it is supposed to be called by the
216 application shutdown code.
218 Note that this function also calls
219 \helpref{ClearTraceMasks
}{wxlogcleartracemasks
}.
221 \membersection{wxLog::Flush
}\label{wxlogflush
}
223 \func{virtual void
}{Flush
}{\void}
225 Shows all the messages currently in buffer and clears it. If the buffer
226 is already empty, nothing happens.
228 \membersection{wxLog::FlushActive
}\label{wxlogflushactive
}
230 \func{static void
}{FlushActive
}{\void}
232 Flushes the current log target if any, does nothing if there is none.
236 \helpref{Flush
}{wxlogflush
}
238 \membersection{wxLog::HasPendingMessages
}\label{haspendingmessages
}
240 \constfunc{bool
}{HasPendingMessages
}{\void}
242 Returns true if there are any messages in the buffer (not yet shown to the
243 user). (Almost) for internal use only.
245 \membersection{wxLog::SetVerbose
}\label{wxlogsetverbose
}
247 \func{void
}{SetVerbose
}{\param{bool
}{ verbose = TRUE
}}
249 Activates or desactivates verbose mode in which the verbose messages are
250 logged as the normal ones instead of being silently dropped.
252 \membersection{wxLog::GetVerbose
}\label{wxloggetverbose
}
254 \constfunc{bool
}{GetVerbose
}{\void}
256 Returns whether the verbose mode is currently active.
258 \membersection{wxLog::SetTimestamp
}\label{wxlogsettimestamp
}
260 \func{void
}{SetTimestamp
}{\param{const char *
}{ format
}}
262 Sets the timestamp format prepended by the default log targets to all
263 messages. The string may contain any normal characters as well as \%
264 prefixed format specificators, see
{\it strftime()
} manual for details.
265 Passing a NULL value (not empty string) to this function disables message timestamping.
267 \membersection{wxLog::GetTimestamp
}\label{wxloggettimestamp
}
269 \constfunc{const char *
}{GetTimestamp
}{\void}
271 Returns the current timestamp format string.
273 \membersection{wxLog::SetTraceMask
}\label{wxlogsettracemask
}
275 \func{static void
}{SetTraceMask
}{\param{wxTraceMask
}{ mask
}}
277 Sets the trace mask, see
\helpref{Customization
}{wxlogcustomization
}
280 \membersection{wxLog::GetTraceMask
}\label{wxloggettracemask
}
282 Returns the current trace mask, see
\helpref{Customization
}{wxlogcustomization
} section
285 \membersection{wxLog::IsAllowedTraceMask
}\label{wxlogisallowedtracemask
}
287 \func{static bool
}{IsAllowedTraceMask
}{\param{const wxChar *
}{mask
}}
289 Returns TRUE if the
{\it mask
} is one of allowed masks for
290 \helpref{wxLogTrace
}{wxlogtrace
}.
292 See also:
\helpref{AddTraceMask
}{wxlogaddtracemask
},
293 \helpref{RemoveTraceMask
}{wxlogremovetracemask
}
295 \membersection{wxLog::RemoveTraceMask
}\label{wxlogremovetracemask
}
297 \func{static void
}{RemoveTraceMask
}{\param{const wxString\&
}{mask
}}
299 Remove the
{\it mask
} from the list of allowed masks for
300 \helpref{wxLogTrace
}{wxlogtrace
}.
302 See also:
\helpref{AddTraceMask
}{wxlogaddtracemask
}
projects / wxWidgets.git / blob