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

docs/latex/wx/log.tex

@@ -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}
+