updated and expanded wxLog docs

git-svn-id: https://svn.wxwidgets.org/svn/wx/wxWidgets/trunk@12613 c3d73ce0-8a6f-49c7-b76d-6d57e0e08775

docs/latex/wx/log.tex

@@ -431,7 +431,275 @@ 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.
 
-%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% wxLogChain %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% wxLogGui %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+
+\section{\class{wxLogGui}}\label{wxloggui}
+
+This is the default log target for the GUI wxWindows applications. It is passed
+to \helpref{wxLog::SetActiveTarget}{wxlogsetactivetarget} at the program
+startup and is deleted by wxWindows during the program shut down.
+
+\wxheading{Derived from}
+
+\helpref{wxLog}{wxlog}
+
+\wxheading{Include files}
+
+<wx/log.h>
+
+\latexignore{\rtfignore{\wxheading{Members}}}
+
+\membersection{wxLogGui::wxLogGui}
+
+\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 wxWindows
+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}
+
+\func{}{wxLogNull}{\void}
+
+Suspends logging.
+
+\membersection{wxLogNull::\destruct{wxLogNull}}
+
+Resumes logging.
+
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% 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
+wxWindows 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}
+
+\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 wxWindows 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}
+
+\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}
+
+\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}
+
+\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}
+
+\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}
+
+\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 void}{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}.
+
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% wxLogPassThrough %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
 
 \section{\class{wxLogPassThrough}}\label{wxlogpassthrough}
 

docs/latex/wx/tlog.tex

@@ -1,7 +1,15 @@
 \section{wxLog classes overview}\label{wxlogoverview}
 
-Classes: \helpref{wxLog}{wxlog}, wxLogStderr,
+Classes: \helpref{wxLog}{wxlog},\\
-wxLogOstream, wxLogTextCtrl, wxLogWindow, wxLogGui, wxLogNull
+\helpref{wxLogStderr}{wxlogstderr},\\
+\helpref{wxLogStream}{wxlogstream},\\
+\helpref{wxLogTextCtrl}{wxlogtextctrl},\\
+\helpref{wxLogWindow}{wxlogwindow},\\
+\helpref{wxLogGui}{wxloggui},\\
+\helpref{wxLogNull}{wxlognull},\\
+\helpref{wxLogChain}{wxlogchain},\\
+\helpref{wxLogPassThrough}{wxlogpassthrough},\\
+\helpref{wxStreamToTextRedirector}{wxstreamtotextredirector}
 
 This is a general overview of logging classes provided by wxWindows. The word
 logging here has a broad sense, including all of the program output, not only
@@ -69,25 +77,18 @@ under Windows where the stdout of GUI programs is not assigned to anything.
 Thus, you might view {\it wxLogMessage()} as a simple substitute for {\it
 printf()}.
 
-Moreover {\it wxMSW} doesn't have a {\bf console} as you may have with {\it
+You can also redirect the {\it wxLogXXX} calls to {\it cout} by just writing:
-  wxGTK}. Under {\it wxMSW}, a call using {\it cout} just goes nowhere. To
-cope with this problem, {\it wxWindows} provides a way to redirect {\it cout}
-calls to \helpref{wxTextCtrl}{wxtextctrl}, {\it i.e.}:
-{\small
-\begin{verbatim}
-  wxLogWindow *logger=new wxLogWindow(your_frame,"Logger");
-  cout=*new ostream(logger->GetTextCtrl());
-  wxLog::SetActiveTarget(logger);
-\end{verbatim}
-}
-On the opposite, if you like your {\it wxLogXXX} calls to behave as a {\it cout} 
-call does, just write :
 {\small
 \begin{verbatim}
   wxLog *logger=new wxLogStream(&cout);
   wxLog::SetActiveTarget(logger);
 \end{verbatim}
 }
+
+Finally, there is also a possibility to redirect the output sent to {\it cout} 
+to a \helpref{wxTextCtrl}{wxtextctrl} by using the 
+\helpref{wxStreamToTextRedirector}{wxstreamtotextredirector} class.
+
 \item{\bf Flexibility} The output of wxLog functions can be redirected or
 suppressed entirely based on their importance, which is either impossible or
 difficult to do with traditional methods. For example, only error messages, or
@@ -164,3 +165,8 @@ reasons it is unwanted, just use this construction:
 }
 \end{itemize}
 
+The log targets can also be combined: for example you may wish to redirect the
+messages somewhere else (for example, to a log file) but also process them as
+normally. For this the \helpful{wxLogChain}{wxlogchain} and 
+\helpful{wxLogPassThrough}{wxlogpassthrough} can be used.
+