From: Vadim Zeitlin Date: Thu, 18 Nov 1999 14:34:13 +0000 (+0000) Subject: wxLogTrace documentation updated and expanded, VC++ users note added X-Git-Url: https://git.saurik.com/wxWidgets.git/commitdiff_plain/ac7f0167aaced8162b8f40725102b5900681ce23?ds=sidebyside 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 --- diff --git a/docs/latex/wx/log.tex b/docs/latex/wx/log.tex index 0e2604ace6..3c8d763200 100644 --- a/docs/latex/wx/log.tex +++ b/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: - -\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 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, +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. + +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. + +For example, +\begin{verbatim} +// 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 +{\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} -wxLogTrace(wxTraceRefCount | wxTraceOle, "Active object ref count: %d", nRef); +wxLog::AddTraceMask(wxTRACE_OleCalls); \end{verbatim} -will do something only if the current trace mask contains both wxTraceRefCount -and wxTraceOle. + +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} +