wxLogTrace documentation updated and expanded, VC++ users note added

git-svn-id: https://svn.wxwidgets.org/svn/wx/wxWidgets/trunk@4612 c3d73ce0-8a6f-49c7-b76d-6d57e0e08775
This commit is contained in:
Vadim Zeitlin
1999-11-18 14:34:13 +00:00
parent 338dd99216
commit ac7f0167aa

View File

@@ -62,30 +62,45 @@ without writing a new log target class (which, aside of being a matter of
several minutes, allows you to do anything you want).
The verbose messages are the trace messages which are not disabled in the
release mode and are generated by {\it wxLogVerbose()}. They are not normally
release mode and are generated by \helpref{wxLogVerbose}{wxlogverbose}. They are not normally
shown to the user because they present little interest, but may be activated,
for example, in order to help the user find some program problem.
As for the (real) trace messages, they come in different kinds:
As for the (real) trace messages, their handling depends on the settings of
the (application global) {\it trace mask}. There are two ways to specify it:
either by using helpref{SetTraceMask}{wxlogsettracemask} and
\helpref{GetTraceMask}{wxloggettracemask} and using
\helpref{wxLogTrace}{wxlogtrace} which takes an integer mask or by using
\helpref{AddTraceMask}{wxlogaddtracemask} for string trace masks.
\begin{itemize}\itemsep=0pt
\item{wxTraceMemAlloc} for the messages about creating and deleting objects
\item{wxTraceMessages} for tracing the windowing system messages/events
\item{wxTraceResAlloc} for allocating and releasing the system ressources
\item{wxTraceRefCount} for reference counting related messages
\item{wxTraceOleCalls} for the OLE (or COM) method invocations (wxMSW only)
\item{other} the remaining bits are free for user-defined trace levels
\end{itemize}
The difference between bit-wise and string trace masks is that a message using
integer trace mask will only be logged if all bits of the mask are set in the
current mask while a message using string mask will be logged simply if the
mask had been added before to the list of allowed ones.
The trace mask is a bit mask which tells which (if any) of these trace
messages are going to be actually logged. For the trace message to appear
somewhere, all the bits in the mask used in the call to {\it wxLogTrace()}
function must be set in the current trace mask. For example,
For example,
\begin{verbatim}
wxLogTrace(wxTraceRefCount | wxTraceOle, "Active object ref count: %d", nRef);
// wxTraceOleCalls is one of standard bit masks
wxLogTrace(wxTraceRefCount | wxTraceOleCalls, "Active object ref count: %d", nRef);
\end{verbatim}
will do something only if the current trace mask contains both wxTraceRefCount
and wxTraceOle.
will do something only if the current trace mask contains both
{\tt wxTraceRefCount} and {\tt wxTraceOle}, but
\begin{verbatim}
// wxTRACE_OleCalls is one of standard string masks
wxLogTrace(wxTACE_OleCalls, "IFoo::Bar() called");
\end{verbatim}
will log the message if it was preceded by
\begin{verbatim}
wxLog::AddTraceMask(wxTRACE_OleCalls);
\end{verbatim}
Using string masks is simpler and allows to easily add custom ones, so this is
the preferred way of working with trace messages. The integer trace mask is
kept for compatibility and for additional (but very rarely needed) flexibility
only.
The standard trace masks are given in \helpref{wxLogTrace}{wxlogtrace}
documentation.
Finally, the {\it wxLog::DoLog()} function automatically prepends a time stamp
to all the messages. The format of the time stamp may be changed: it can be
@@ -95,6 +110,15 @@ standard {\it strftime()} function. For example, the default format is
(without quotes) for the current date. Setting an empty string as the time
format disables timestamping of the messages completely.
{\bf NB:} Timestamping is disabled for Visual C++ users in debug builds by
default because otherwise it would be impossible to directly go to the line
from which the log message was generated by simply clicking in the debugger
window on the corresponding error message. If you wish to enable it, please use
\helpref{SetTimestamp}{wxlogsettimestamp} explicitly.
\helpref{AddTraceMask}{wxlogaddtracemask}\\
\helpref{RemoveTraceMask}{wxlogremovetracemask}\\
\helpref{IsAllowedTraceMask}{wxlogisallowedtracemask}\\
\helpref{SetVerbose}{wxlogsetverbose}\\
\helpref{GetVerbose}{wxloggetverbose}\\
\helpref{SetTimestamp}{wxlogsettimestamp}\\
@@ -109,6 +133,15 @@ format disables timestamping of the messages completely.
}}
\membersection{wxLog::AddTraceMask}\label{wxlogaddtracemask}
\func{static void}{AddTraceMask}{\param{const wxString\& }{mask}}
Add the {\it mask} to the list of allowed masks for
\helpref{wxLogTrace}{wxlogtrace}.
See also: \helpref{RemoveTraceMask}{wxlogremovetracemask}
\membersection{wxLog::OnLog}\label{wxlogonlog}
\func{static void}{OnLog}{\param{wxLogLevel }{ level}, \param{const char * }{ message}}
@@ -200,3 +233,22 @@ section for details.
Returns the current trace mask, see \helpref{Customization}{wxlogcustomization} section
for details.
\membersection{wxLog::IsAllowedTraceMask}\label{wxlogisallowedtracemask}
\func{static bool}{IsAllowedTraceMask}{\param{const wxChar *}{mask}}
Returns TRUE if the {\it mask} is one of allowed masks for
\helpref{wxLogTrace}{wxlogtrace}.
See also: \helpref{AddTraceMask}{wxlogaddtracemask},
\helpref{RemoveTraceMask}{wxlogremovetracemask}
\membersection{wxLog::RemoveTraceMask}\label{wxlogremovetracemask}
\func{static void}{RemoveTraceMask}{\param{const wxString\& }{mask}}
Remove the {\it mask} from the list of allowed masks for
\helpref{wxLogTrace}{wxlogtrace}.
See also: \helpref{AddTraceMask}{wxlogaddtracemask}