X-Git-Url: https://git.saurik.com/wxWidgets.git/blobdiff_plain/9ee2d31ccc6741b8af6b30fb2ca8992699d3a2ed..bf7945cef10c0844a32e95695c544d829da9293a:/docs/latex/wx/log.tex diff --git a/docs/latex/wx/log.tex b/docs/latex/wx/log.tex index f6d877de56..7de410ebbd 100644 --- a/docs/latex/wx/log.tex +++ b/docs/latex/wx/log.tex @@ -19,28 +19,33 @@ logging facilities. No base class +\wxheading{Include files} + + + \latexignore{\rtfignore{\wxheading{Function groups}}} \membersection{Static functions} The functions in this section work with and manipulate the active log target. -The {\it OnLog()} is called by the {\it wxLogXXX()} functions and invokes the +The {\it OnLog()} is called by the {\it wxLogXXX()} functions and invokes the {\it DoLog()} of the active log target if any. Get/Set methods are used to -install/query the current active target and, finally, {\it -DontCreateOnDemand()} disables the automatic creation of a standard log target +install/query the current active target and, finally, +\helpref{DontCreateOnDemand()}{wxlogdontcreateondemand} +disables the automatic creation of a standard log target if none actually exists. It is only useful when the application is terminating and shouldn't be used in other situations because it may easily lead to a loss of messages. \helpref{OnLog}{wxlogonlog}\\ \helpref{GetActiveTarget}{wxloggetactivetarget}\\ -\helpref{SetActiveTarget}{wxsetactivetarget}\\ +\helpref{SetActiveTarget}{wxlogsetactivetarget}\\ \helpref{DontCreateOnDemand}{wxlogdontcreateondemand} \membersection{Message buffering} Some of wxLog implementations, most notably the standard -\helpref{wxLogGui}{wxloggui} class, buffer the messages (for example, to avoid +wxLogGui class, buffer the messages (for example, to avoid showing the user a zillion of modal message boxes one after another - which would be really annoying). {\it Flush()} shows them all and clears the buffer contents. Although this function doesn't do anything if the buffer is already @@ -48,38 +53,60 @@ empty, {\it HasPendingMessages()} is also provided which allows to explicitly verify it. \helpref{Flush}{wxlogflush}\\ +\helpref{FlushActive}{wxlogflushactive}\\ \helpref{HasPendingMessages}{haspendingmessages} -\membersection{Customization}{wxlogcustomization} +\membersection{Customization}\label{wxlogcustomization} The functions below allow some limited customization of wxLog behaviour 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 -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, +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, 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(wxTRACE_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 @@ -89,10 +116,20 @@ 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{ClearTraceMasks}{wxlogcleartracemasks}\\ +\helpref{IsAllowedTraceMask}{wxlogisallowedtracemask}\\ \helpref{SetVerbose}{wxlogsetverbose}\\ \helpref{GetVerbose}{wxloggetverbose}\\ -\helpref{SetTimeStampFormat}{wxlogsettimestampformat}\\ -\helpref{GetTimeStampFormat}{wxloggettimestampformat}\\ +\helpref{SetTimestamp}{wxlogsettimestamp}\\ +\helpref{GetTimestamp}{wxloggettimestamp}\\ \helpref{SetTraceMask}{wxlogsettracemask}\\ \helpref{GetTraceMask}{wxloggettracemask} @@ -103,6 +140,24 @@ 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::ClearTraceMasks}\label{wxlogcleartracemasks} + +\func{static void}{ClearTraceMasks}{\void} + +Removes all trace masks previously set with +\helpref{AddTraceMask}{wxlogaddtracemask}. + +See also: \helpref{RemoveTraceMask}{wxlogremovetracemask} + \membersection{wxLog::OnLog}\label{wxlogonlog} \func{static void}{OnLog}{\param{wxLogLevel }{ level}, \param{const char * }{ message}} @@ -128,58 +183,92 @@ previous active log target (may be NULL). \func{static void}{DontCreateOnDemand}{\void} Instructs wxLog to not create new log targets on the fly if there is none -currently. (Almost) for internal use only. +currently. (Almost) for internal use only: it is supposed to be called by the +application shutdown code. + +Note that this function also calls +\helpref{ClearTraceMasks}{wxlogcleartracemasks}. -\membersection{wxLog::Flush}{wxlogflush} +\membersection{wxLog::Flush}\label{wxlogflush} \func{virtual void}{Flush}{\void} Shows all the messages currently in buffer and clears it. If the buffer is already empty, nothing happens. -\membersection{wxLog::HasPendingMessages}{haspendingmessages} +\membersection{wxLog::FlushActive}\label{wxlogflushactive} + +\func{static void}{FlushActive}{\void} + +Flushes the current log target if any, does nothing if there is none. + +See also: + +\helpref{Flush}{wxlogflush} + +\membersection{wxLog::HasPendingMessages}\label{haspendingmessages} \constfunc{bool}{HasPendingMessages}{\void} Returns true if there are any messages in the buffer (not yet shown to the user). (Almost) for internal use only. -\membersection{wxLog::SetVerbose}{wxlogsetverbose} +\membersection{wxLog::SetVerbose}\label{wxlogsetverbose} \func{void}{SetVerbose}{\param{bool }{ verbose = TRUE}} Activates or desactivates verbose mode in which the verbose messages are logged as the normal ones instead of being silently dropped. -\membersection{wxLog::GetVerbose}{wxloggetverbose} +\membersection{wxLog::GetVerbose}\label{wxloggetverbose} \constfunc{bool}{GetVerbose}{\void} Returns whether the verbose mode is currently active. -\membersection{wxLog::SetTimeStampFormat}{wxlogsettimestampformat} +\membersection{wxLog::SetTimestamp}\label{wxlogsettimestamp} -\func{void}{SetTimeStampFormat}{\param{const char * }{ format}} +\func{void}{SetTimestamp}{\param{const char * }{ format}} Sets the timestamp format prepended by the default log targets to all messages. The string may contain any normal characters as well as \% prefixed format specificators, see {\it strftime()} manual for details. -Passing an empty string to this function disables message timestamping. +Passing a NULL value (not empty string) to this function disables message timestamping. -\membersection{wxLog::GetTimeStampFormat}{wxloggettimestampformat} +\membersection{wxLog::GetTimestamp}\label{wxloggettimestamp} -\constfunc{const char *}{GetTimeStampFormat}{\void} +\constfunc{const char *}{GetTimestamp}{\void} Returns the current timestamp format string. -\membersection{wxLog::SetTraceMask}{wxlogsettracemask} +\membersection{wxLog::SetTraceMask}\label{wxlogsettracemask} \func{static void}{SetTraceMask}{\param{wxTraceMask }{ mask}} Sets the trace mask, see \helpref{Customization}{wxlogcustomization} section for details. -\membersection{wxLog::GetTraceMask}{wxloggettracemask} +\membersection{wxLog::GetTraceMask}\label{wxloggettracemask} + +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} -Returns the current trace mask, see \helpref{Customization}{wxlogcustomization} -section for details.