X-Git-Url: https://git.saurik.com/wxWidgets.git/blobdiff_plain/42ff6409d9aff9ba1b771842a256feaeb40e28cd..402dfce7b324c977a5b396b07cd36835d5514e52:/docs/latex/wx/log.tex?ds=inline

diff --git a/docs/latex/wx/log.tex b/docs/latex/wx/log.tex
index bab8c50278..f96989dde2 100644
--- a/docs/latex/wx/log.tex
+++ b/docs/latex/wx/log.tex
@@ -1,6 +1,17 @@
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+%% Name:        log.tex
+%% Purpose:     wxLog and related classes documentation
+%% Author:      Vadim Zeitlin
+%% Modified by:
+%% Created:     some time ago
+%% RCS-ID:      $Id$
+%% Copyright:   (c) 1997-2001 Vadim Zeitlin
+%% License:     wxWindows license
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+
 \section{\class{wxLog}}\label{wxlog}
 
-wxLog class defines the interface for the {\it log targets} used by wxWindows
+wxLog class defines the interface for the {\it log targets} used by wxWidgets
 logging functions as explained in the \helpref{wxLog overview}{wxlogoverview}.
 The only situations when you need to directly use this class is when you want
 to derive your own log target because the existing ones don't satisfy your
@@ -12,43 +23,61 @@ completely) the timestamp on the messages.
 Otherwise, it is completely hidden behind the {\it wxLogXXX()} functions and
 you may not even know about its existence.
 
-See \helpref{log overview}{wxlogoverview} for the descriptions of wxWindows
+See \helpref{log overview}{wxlogoverview} for the descriptions of wxWidgets
 logging facilities.
 
 \wxheading{Derived from}
 
 No base class
 
+\wxheading{Include files}
+
+<wx/log.h>
+
 \latexignore{\rtfignore{\wxheading{Function groups}}}
 
-\membersection{Static functions}
+\membersection{Static functions}\label{staticlogfunctions}
 
 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
-{\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
-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.
+The \helpref{OnLog()}{wxlogonlog} is called by the {\it wxLogXXX()} functions
+and invokes the \helpref{DoLog()}{wxlogdolog} of the active log target if any.
+Get/Set methods are used to 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}{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
-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
-empty, {\it HasPendingMessages()} is also provided which allows to explicitly
-verify it.
+\helpref{DontCreateOnDemand}{wxlogdontcreateondemand}\\
+\helpref{Suspend}{wxlogsuspend}\\
+\helpref{Resume}{wxlogresume}
+
+\membersection{Logging functions}\label{loggingfunctions}
+
+There are two functions which must be implemented by any derived class to
+actually process the log messages: \helpref{DoLog}{wxlogdolog} and
+\helpref{DoLogString}{wxlogdologstring}. The second function receives a string
+which just has to be output in some way and the easiest way to write a new log
+target is to override just this function in the derived class. If more control
+over the output format is needed, then the first function must be overridden
+which allows to construct custom messages depending on the log level or even
+do completely different things depending on the message severity (for example,
+throw away all messages except warnings and errors, show warnings on the
+screen and forward the error messages to the user's (or programmer's) cell
+phone - maybe depending on whether the timestamp tells us if it is day or
+night in the current time zone).
+
+There also functions to support message buffering. Why are they needed?
+Some of wxLog implementations, most notably the standard 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).
+\helpref{Flush()}{wxlogflush} shows them all and clears the buffer contents.
+This function doesn't do anything if the buffer is already empty.
 
 \helpref{Flush}{wxlogflush}\\
-\helpref{HasPendingMessages}{haspendingmessages}
+\helpref{FlushActive}{wxlogflushactive}
 
 \membersection{Customization}\label{wxlogcustomization}
 
@@ -57,43 +86,74 @@ 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
-any string with \% specificators fully described in the documentation of the
+any string with \% specifications fully described in the documentation of the
 standard {\it strftime()} function. For example, the default format is
 "[\%d/\%b/\%y \%H:\%M:\%S] " which gives something like "[17/Sep/98 22:10:16] "
 (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{GetTraceMasks}{wxloggettracemasks}\\
+\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}
 
@@ -104,6 +164,39 @@ 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}.
+
+\wxheading{See also}
+
+\helpref{RemoveTraceMask}{wxlogremovetracemask}
+\helpref{GetTraceMasks}{wxloggettracemasks}
+
+\membersection{wxLog::ClearTraceMasks}\label{wxlogcleartracemasks}
+
+\func{static void}{ClearTraceMasks}{\void}
+
+Removes all trace masks previously set with
+\helpref{AddTraceMask}{wxlogaddtracemask}.
+
+\wxheading{See also}
+
+\helpref{RemoveTraceMask}{wxlogremovetracemask}
+
+\membersection{wxLog::GetTraceMasks}\label{wxloggettracemasks}
+
+\func{static const wxArrayString \&}{GetTraceMasks}{\void}
+
+Returns the currently allowed list of string trace masks.
+
+\wxheading{See also}
+
+\helpref{AddTraceMask}{wxlogaddtracemask}.
+
 \membersection{wxLog::OnLog}\label{wxlogonlog}
 
 \func{static void}{OnLog}{\param{wxLogLevel }{ level}, \param{const char * }{ message}}
@@ -122,14 +215,69 @@ Returns the pointer to the active log target (may be NULL).
 \func{static wxLog *}{SetActiveTarget}{\param{wxLog * }{ logtarget}}
 
 Sets the specified log target as the active one. Returns the pointer to the
-previous active log target (may be NULL).
+previous active log target (may be NULL).  To supress logging use a new
+instance of wxLogNull not NULL.  If the active log target is set to NULL a
+new default log target will be created when logging occurs.
+
+\membersection{wxLog::Suspend}\label{wxlogsuspend}
+
+\func{static void}{Suspend}{\void}
+
+Suspends the logging until \helpref{Resume}{wxlogresume} is called. Note that
+the latter must be called the same number of times as the former to undo it,
+i.e. if you call Suspend() twice you must call Resume() twice as well.
+
+Note that suspending the logging means that the log sink won't be be flushed
+periodically, it doesn't have any effect if the current log target does the
+logging immediately without waiting for \helpref{Flush}{wxlogflush} to be
+called (the standard GUI log target only shows the log dialog when it is
+flushed, so Suspend() works as expected with it).
+
+\wxheading{See also}
+
+\helpref{Resume}{wxlogresume},\\
+\helpref{wxLogNull}{wxlogoverview}
+
+\membersection{wxLog::Resume}\label{wxlogresume}
+
+\func{static void}{Resume}{\void}
+
+Resumes logging previously suspended by a call to
+\helpref{Suspend}{wxlogsuspend}. All messages logged in the meanwhile will be
+flushed soon.
+
+\membersection{wxLog::DoLog}\label{wxlogdolog}
+
+\func{virtual void}{DoLog}{\param{wxLogLevel }{level}, \param{const wxChar }{*msg}, \param{time\_t }{timestamp}}
+
+Called to process the message of the specified severity. {\it msg} is the text
+of the message as specified in the call of {\it wxLogXXX()} function which
+generated it and {\it timestamp} is the moment when the message was generated.
+
+The base class version prepends the timestamp to the message, adds a prefix
+corresponding to the log level and then calls
+\helpref{DoLogString}{wxlogdologstring} with the resulting string.
+
+\membersection{wxLog::DoLogString}\label{wxlogdologstring}
+
+\func{virtual void}{DoLogString}{\param{const wxChar }{*msg}, \param{time\_t }{timestamp}}
+
+Called to log the specified string. The timestamp is already included into the
+string but still passed to this function.
+
+A simple implementation may just send the string to {\tt stdout} or, better,
+{\tt stderr}.
 
 \membersection{wxLog::DontCreateOnDemand}\label{wxlogdontcreateondemand}
 
 \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}\label{wxlogflush}
 
@@ -138,38 +286,54 @@ currently. (Almost) for internal use only.
 Shows all the messages currently in buffer and clears it. If the buffer
 is already empty, nothing happens.
 
-\membersection{wxLog::HasPendingMessages}\label{haspendingmessages}
+\membersection{wxLog::FlushActive}\label{wxlogflushactive}
+
+\func{static void}{FlushActive}{\void}
 
-\constfunc{bool}{HasPendingMessages}{\void}
+Flushes the current log target if any, does nothing if there is none.
 
-Returns true if there are any messages in the buffer (not yet shown to the
-user). (Almost) for internal use only.
+\wxheading{See also}
+
+\helpref{Flush}{wxlogflush}
 
 \membersection{wxLog::SetVerbose}\label{wxlogsetverbose}
 
-\func{void}{SetVerbose}{\param{bool }{ verbose = TRUE}}
+\func{static void}{SetVerbose}{\param{bool }{ verbose = true}}
 
-Activates or desactivates verbose mode in which the verbose messages are
+Activates or deactivates verbose mode in which the verbose messages are
 logged as the normal ones instead of being silently dropped.
 
 \membersection{wxLog::GetVerbose}\label{wxloggetverbose}
 
-\constfunc{bool}{GetVerbose}{\void}
+\func{static bool}{GetVerbose}{\void}
 
 Returns whether the verbose mode is currently active.
 
-\membersection{wxLog::SetTimeStampFormat}\label{wxlogsettimestampformat}
+\membersection{wxLog::SetLogLevel}\label{wxlogsetloglevel}
+
+\func{static void}{SetLogLevel}{\param{wxLogLevel }{ logLevel}}
+
+Specifies that log messages with $level > logLevel$ should be ignored
+and not sent to the active log target.
+
+\membersection{wxLog::GetLogLevel}\label{wxloggetloglevel}
+
+\func{static wxLogLevel}{GetLogLevel}{\void}
+
+Returns the current log level limit.
+
+\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}\label{wxloggettimestampformat}
+\membersection{wxLog::GetTimestamp}\label{wxloggettimestamp}
 
-\constfunc{const char *}{GetTimeStampFormat}{\void}
+\constfunc{const char *}{GetTimestamp}{\void}
 
 Returns the current timestamp format string.
 
@@ -184,3 +348,404 @@ 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}
+
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% wxLogChain %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+
+\section{\class{wxLogChain}}\label{wxlogchain}
+
+This simple class allows to chain log sinks, that is to install a new sink but
+keep passing log messages to the old one instead of replacing it completely as
+\helpref{SetActiveTarget}{wxlogsetactivetarget} does.
+
+It is especially useful when you want to divert the logs somewhere (for
+example to a file or a log window) but also keep showing the error messages
+using the standard dialogs as \helpref{wxLogGui}{wxlogoverview} does by default.
+
+Example of usage:
+
+\begin{verbatim}
+wxLogChain *logChain = new wxLogChain(new wxLogStderr);
+
+// all the log messages are sent to stderr and also processed as usually
+...
+
+// don't delete logChain directly as this would leave a dangling
+// pointer as active log target, use SetActiveTarget() instead
+delete wxLog::SetActiveTarget(...something else or NULL...);
+
+\end{verbatim}
+
+\wxheading{Derived from}
+
+\helpref{wxLog}{wxlog}
+
+\wxheading{Include files}
+
+<wx/log.h>
+
+\latexignore{\rtfignore{\wxheading{Members}}}
+
+\membersection{wxLogChain::wxLogChain}\label{wxlogchainctor}
+
+\func{}{wxLogChain}{\param{wxLog *}{logger}}
+
+Sets the specified {\tt logger} (which may be {\tt NULL}) as the default log
+target but the log messages are also passed to the previous log target if any.
+
+\membersection{wxLogChain::\destruct{wxLogChain}}\label{wxlogchaindtor}
+
+\func{}{\destruct{wxLogChain}}{\void}
+
+Destroys the previous log target.
+
+\membersection{wxLogChain::GetOldLog}\label{wxlogchaingetoldlog}
+
+\constfunc{wxLog *}{GetOldLog}{\void}
+
+Returns the pointer to the previously active log target (which may be {\tt
+NULL}).
+
+\membersection{wxLogChain::IsPassingMessages}\label{wxlogchainispassingmessages}
+
+\constfunc{bool}{IsPassingMessages}{\void}
+
+Returns {\tt true} if the messages are passed to the previously active log
+target (default) or {\tt false} if \helpref{PassMessages}{wxlogchainpassmessages}
+had been called.
+
+\membersection{wxLogChain::PassMessages}\label{wxlogchainpassmessages}
+
+\func{void}{PassMessages}{\param{bool }{passMessages}}
+
+By default, the log messages are passed to the previously active log target.
+Calling this function with {\tt false} parameter disables this behaviour
+(presumably temporarily, as you shouldn't use wxLogChain at all otherwise) and
+it can be reenabled by calling it again with {\it passMessages} set to {\tt
+true}.
+
+\membersection{wxLogChain::SetLog}\label{wxlogchainsetlog}
+
+\func{void}{SetLog}{\param{wxLog *}{logger}}
+
+Sets another log target to use (may be {\tt NULL}). The log target specified
+in the \helpref{constructor}{wxlogchainctor} or in a previous call to
+this function is deleted.
+
+This doesn't change the old log target value (the one the messages are
+forwarded to) which still remains the same as was active when wxLogChain
+object was created.
+
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% wxLogGui %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+
+\section{\class{wxLogGui}}\label{wxloggui}
+
+This is the default log target for the GUI wxWidgets applications. It is passed
+to \helpref{wxLog::SetActiveTarget}{wxlogsetactivetarget} at the program
+startup and is deleted by wxWidgets during the program shut down.
+
+\wxheading{Derived from}
+
+\helpref{wxLog}{wxlog}
+
+\wxheading{Include files}
+
+<wx/log.h>
+
+\latexignore{\rtfignore{\wxheading{Members}}}
+
+\membersection{wxLogGui::wxLogGui}\label{wxlogguictor}
+
+\func{}{wxLogGui}{\void}
+
+Default constructor.
+
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% wxLogNull %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+
+\section{\class{wxLogNull}}\label{wxlognull}
+
+This class allows to temporarily suspend logging. All calls to the log
+functions during the life time of an object of this class are just ignored.
+
+In particular, it can be used to suppress the log messages given by wxWidgets
+itself but it should be noted that it is rarely the best way to cope with this
+problem as {\bf all} log messages are suppressed, even if they indicate a
+completely different error than the one the programmer wanted to suppress.
+
+For instance, the example of the overview:
+
+{\small
+\begin{verbatim}
+  wxFile file;
+
+  // wxFile.Open() normally complains if file can't be opened, we don't want it
+  {
+    wxLogNull logNo;
+    if ( !file.Open("bar") )
+      ... process error ourselves ...
+  } // ~wxLogNull called, old log sink restored
+
+  wxLogMessage("..."); // ok
+\end{verbatim}
+}%
+
+would be better written as:
+
+{\small
+\begin{verbatim}
+  wxFile file;
+
+  // don't try to open file if it doesn't exist, we are prepared to deal with
+  // this ourselves - but all other errors are not expected
+  if ( wxFile::Exists("bar") )
+  {
+      // gives an error message if the file couldn't be opened
+      file.Open("bar");
+  }
+  else
+  {
+      ...
+  }
+\end{verbatim}
+}%
+
+\wxheading{Derived from}
+
+\helpref{wxLog}{wxlog}
+
+\wxheading{Include files}
+
+<wx/log.h>
+
+\latexignore{\rtfignore{\wxheading{Members}}}
+
+\membersection{wxLogNull::wxLogNull}\label{wxlognullctor}
+
+\func{}{wxLogNull}{\void}
+
+Suspends logging.
+
+\membersection{wxLogNull::\destruct{wxLogNull}}\label{wxlognulldtor}
+
+Resumes logging.
+
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% wxLogPassThrough %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+
+\section{\class{wxLogPassThrough}}\label{wxlogpassthrough}
+
+A special version of \helpref{wxLogChain}{wxlogchain} which uses itself as the
+new log target. Maybe more clearly, it means that this is a log target which
+forwards the log messages to the previously installed one in addition to
+processing them itself.
+
+Unlike \helpref{wxLogChain}{wxlogchain} which is usually used directly as is,
+this class must be derived from to implement \helpref{DoLog}{wxlogdolog}
+and/or \helpref{DoLogString}{wxlogdologstring} methods.
+
+\wxheading{Derived from}
+
+\helpref{wxLogChain}{wxlogchain}
+
+\wxheading{Include files}
+
+<wx/log.h>
+
+\latexignore{\rtfignore{\wxheading{Members}}}
+
+\membersection{wxLogPassThrough::wxLogPassThrough}\label{wxlogpassthroughctor}
+
+Default ctor installs this object as the current active log target.
+
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% wxLogStderr %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+
+\section{\class{wxLogStderr}}\label{wxlogstderr}
+
+This class can be used to redirect the log messages to a C file stream (not to
+be confused with C++ streams). It is the default log target for the non-GUI
+wxWidgets applications which send all the output to {\tt stderr}.
+
+\wxheading{Derived from}
+
+\helpref{wxLog}{wxlog}
+
+\wxheading{Include files}
+
+<wx/log.h>
+
+\wxheading{See also}
+
+\helpref{wxLogStream}{wxlogstream}
+
+\latexignore{\rtfignore{\wxheading{Members}}}
+
+\membersection{wxLogStderr::wxLogStderr}\label{wxlogstderrctor}
+
+\func{}{wxLogStderr}{\param{FILE }{*fp = NULL}}
+
+Constructs a log target which sends all the log messages to the given
+{\tt FILE}. If it is {\tt NULL}, the messages are sent to {\tt stderr}.
+
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% wxLogStream %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+
+\section{\class{wxLogStream}}\label{wxlogstream}
+
+This class can be used to redirect the log messages to a C++ stream.
+
+Please note that this class is only available if wxWidgets was compiled with
+the standard iostream library support ({\tt wxUSE\_STD\_IOSTREAM} must be on).
+
+\wxheading{Derived from}
+
+\helpref{wxLog}{wxlog}
+
+\wxheading{Include files}
+
+<wx/log.h>
+
+\wxheading{See also}
+
+\helpref{wxLogStderr}{wxlogstderr},\\
+\helpref{wxStreamToTextRedirector}{wxstreamtotextredirector}
+
+\latexignore{\rtfignore{\wxheading{Members}}}
+
+\membersection{wxLogStream::wxLogStream}\label{wxlogstreamctor}
+
+\func{}{wxLogStream}{\param{std::ostream }{*ostr = NULL}}
+
+Constructs a log target which sends all the log messages to the given
+output stream. If it is {\tt NULL}, the messages are sent to {\tt cerr}.
+
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% wxLogTextCtrl %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+
+\section{\class{wxLogTextCtrl}}\label{wxlogtextctrl}
+
+Using these target all the log messages can be redirected to a text control.
+The text control must have been created with {\tt wxTE\_MULTILINE} style by the
+caller previously.
+
+\wxheading{Derived from}
+
+\helpref{wxLog}{wxlog}
+
+\wxheading{Include files}
+
+<wx/log.h>
+
+\wxheading{See also}
+
+\helpref{wxLogTextCtrl}{wxlogtextctrl},\\
+\helpref{wxStreamToTextRedirector}{wxstreamtotextredirector}
+
+\latexignore{\rtfignore{\wxheading{Members}}}
+
+\membersection{wxLogTextCtrl::wxLogTextCtrl}\label{wxlogtextctrlctor}
+
+\func{}{wxLogTextCtrl}{\param{wxTextCtrl }{*textctrl}}
+
+Constructs a log target which sends all the log messages to the given text
+control. The {\it textctrl} parameter cannot be {\tt NULL}.
+
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% wxLogWindow %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+
+\section{\class{wxLogWindow}}\label{wxlogwindow}
+
+This class represents a background log window: to be precise, it collects all
+log messages in the log frame which it manages but also passes them on to the
+log target which was active at the moment of its creation. This allows, for
+example, to show all the log messages in a frame but still continue to process
+them normally by showing the standard log dialog.
+
+\wxheading{Derived from}
+
+\helpref{wxLogPassThrough}{wxlogpassthrough}
+
+\wxheading{Include files}
+
+<wx/log.h>
+
+\wxheading{See also}
+
+\helpref{wxLogTextCtrl}{wxlogtextctrl}
+
+\latexignore{\rtfignore{\wxheading{Members}}}
+
+\membersection{wxLogWindow::wxLogWindow}\label{wxlogwindowctor}
+
+\func{}{wxLogWindow}{\param{wxFrame }{*parent}, \param{const wxChar }{*title}, \param{bool }{show = {\tt true}}, \param{bool }{passToOld = {\tt true}}}
+
+Creates the log frame window and starts collecting the messages in it.
+
+\wxheading{Parameters}
+
+\docparam{parent}{The parent window for the log frame, may be {\tt NULL}}
+
+\docparam{title}{The title for the log frame}
+
+\docparam{show}{{\tt true} to show the frame initially (default), otherwise
+\helpref{wxLogWindow::Show}{wxlogwindowshow} must be called later.}
+
+\docparam{passToOld}{{\tt true} to process the log messages normally in addition to
+logging them in the log frame (default), {\tt false} to only log them in the
+log frame.}
+
+\membersection{wxLogWindow::Show}\label{wxlogwindowshow}
+
+\func{void}{Show}{\param{bool }{show = {\tt true}}}
+
+Shows or hides the frame.
+
+\membersection{wxLogWindow::GetFrame}\label{wxlogwindowgetframe}
+
+\constfunc{wxFrame *}{GetFrame}{\void}
+
+Returns the associated log frame window. This may be used to position or resize
+it but use \helpref{wxLogWindow::Show}{wxlogwindowshow} to show or hide it.
+
+\membersection{wxLogWindow::OnFrameCreate}\label{wxlogwindowonframecreate}
+
+\func{virtual void}{OnFrameCreate}{\param{wxFrame }{*frame}}
+
+Called immediately after the log frame creation allowing for
+any extra initializations.
+
+\membersection{wxLogWindow::OnFrameClose}\label{wxlogwindowonframeclose}
+
+\func{virtual bool}{OnFrameClose}{\param{wxFrame }{*frame}}
+
+Called if the user closes the window interactively, will not be
+called if it is destroyed for another reason (such as when program
+exits).
+
+Return {\tt true} from here to allow the frame to close, {\tt false} to
+prevent this from happening.
+
+\wxheading{See also}
+
+\helpref{wxLogWindow::OnFrameDelete}{wxlogwindowonframedelete}
+
+\membersection{wxLogWindow::OnFrameDelete}\label{wxlogwindowonframedelete}
+
+\func{virtual void}{OnFrameDelete}{\param{wxFrame }{*frame}}
+
+Called right before the log frame is going to be deleted: will
+always be called unlike \helpref{OnFrameClose()}{wxlogwindowonframeclose}.
+
