No base class
+\wxheading{Include files}
+
+<wx/log.h>
+
\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
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
(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}
}}
+\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}}
\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.
projects / wxWidgets.git / blobdiff