added wxStreamToTextRedirector

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

docs/changes.txt

@@ -4,6 +4,11 @@ wxWindows 2 Change Log
 INCOMPATIBLE CHANGES SINCE 2.2.x
 ================================
 
+All (GUI):
+
+- wxGridCellAttrProvider class API changed, you will need to update your code
+  if you derived any classes from it
+
 wxMSW:
 
 - child frames appear in the taskbar by default now, use wxFRAME_NO_TASKBAR
@@ -27,6 +32,7 @@ All (GUI):
 - wxFindReplaceDialog added (based on work of Markus Greither)
 - wxTextCtrl::SetMaxLength() added (wxMSW/wxGTK)
 - polygon support in wxRegion (Klaas Holwerda)
+- wxStreamToTextRedirector to allow easily redirect cout to wxTextCtrl added
 - fixed bug with using wxExecute() to capture huge amounts of output
 
 wxHTML:

docs/latex/wx/classes.tex

@@ -279,6 +279,7 @@
 \input stopwtch.tex
 \input strmbase.tex
 \input stream.tex
+\input strtotxt.tex
 \input wxstring.tex
 \input propstfv.tex
 \input strlist.tex

docs/latex/wx/strtotxt.tex

@@ -0,0 +1,76 @@
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+%% Name:        strtotxt.tex
+%% Purpose:     wxStreamToTextRedirector documentation
+%% Author:      Vadim Zeitlin
+%% Modified by:
+%% Created:     19.10.01
+%% RCS-ID:      $Id$
+%% Copyright:   (c) 2001 Vadim Zeitlin <vadim@wxwindows.org>
+%% License:     wxWindows license
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+
+\section{\class{wxStreamToTextRedirector}}\label{wxstreamtotextredirector}
+
+This class can be used to (temporarily) redirect all output sent to a C++
+ostream object to a \helpref{wxTextCtrl}{wxtextctrl} instead.
+
+{\bf NB:} Some compilers and/or build configurations don't support multiply
+inheriting \helpref{wxTextCtrl}{wxtextctrl} from {\tt std::streambuf} in which
+case this class is not compiled in. You also must have {\tt wxUSE\_STD\_IOSTREAM} 
+option on (i.e. set to $1$) in your setup.h to be able to use it. Under Unix,
+specify {\tt --enable-std\_iostreams} switch when running configure for this.
+
+Example of usage:
+{\small%
+\begin{verbatim}
+  using namespace std;
+
+  wxTextCtrl *text = new wxTextCtrl(...);
+
+  {
+    wxStreamToTextRedirector redirect(text);
+
+    // this goes to the text control
+    cout << "Hello, text!" << endl;
+  }
+
+  // this goes soemwhere else, presumably to stdout
+  cout << "Hello, console!" << endl;
+\end{verbatim}
+}%
+
+\wxheading{Derived from}
+
+No base class
+
+\wxheading{Include files}
+
+<wx/textctrl.h>
+
+\wxheading{See also}
+
+\helpref{wxTextCtrl}{wxtextctrl}
+
+\latexignore{\rtfignore{\wxheading{Members}}}
+
+\membersection{wxStreamToTextRedirector::wxStreamToTextRedirector}\label{wxstreamtotextredirectorctor}
+
+\func{}{wxStreamToTextRedirector}{\param{wxTextCtrl }{*text}, \param{ostream *ostr = NULL}}
+
+The constructor starts redirecting output sent to {\it ostr} or {\it cout} for
+the default parameter value to the text control {\it text}.
+
+\wxheading{Parameters}
+
+\docparam{text}{The text control to append output too, must be non NULL}
+
+\docparam{ostr}{The C++ stream to redirect, {\it cout} is used if it is NULL}
+
+\membersection{wxStreamToTextRedirector::\destruct{wxStreamToTextRedirector}}
+
+\func{}{\destruct{wxStreamToTextRedirector}}{\void}
+
+When a wxStreamToTextRedirector object is destroyed, the redirection is ended
+and any output sent to the C++ ostream which had been specified at the time of
+the object construction will go to its original destination.
+

docs/latex/wx/text.tex

@@ -45,10 +45,10 @@ it to always show it. It doesn't do anything under other platforms.}
 See also \helpref{window styles overview}{windowstyles} and 
 \helpref{wxTextCtrl::wxTextCtrl}{wxtextctrlconstr}.
 
-\wxheading{Remarks}
+\wxheading{wxTextCtrl and C++ streams}
 
-This class multiply-inherits from {\bf streambuf} where compilers allow, allowing code such as 
-the following:
+This class multiply-inherits from {\bf streambuf} where compilers allow,
+allowing code such as the following:
 
 {\small%
 \begin{verbatim}
@@ -61,13 +61,62 @@ the following:
 \end{verbatim}
 }%
 
-If your compiler does not support derivation from {\bf streambuf} and gives a compile error, define the symbol 
-{\bf NO\_TEXT\_WINDOW\_STREAM} in the wxTextCtrl header file.
+If your compiler does not support derivation from {\bf streambuf} and gives a
+compile error, define the symbol {\bf NO\_TEXT\_WINDOW\_STREAM} in the
+wxTextCtrl header file.
 
-% VZ: it is wrong to say that C++ iostreams are deprecated, we need a better
-%     wording here - disabling this for now
-%Note that any use of C++ iostreams (including this one) is deprecated and might
-%get completely removed in the future.
+Note that independently of this setting you can always use wxTextCtrl itself
+in a stream-like manner:
+
+{\small%
+\begin{verbatim}
+  wxTextCtrl *control = new wxTextCtrl(...);
+
+  *control << 123.456 << " some text\n";
+\end{verbatim}
+}%
+
+always works. However the possibility to create an ostream associated with
+wxTextCtrl may be useful if you need to redirect the output of a function
+taking an ostream as parameter to a text control.
+
+Another commonly requested need is to redirect {\bf std::cout} to the text
+control. This could be done in the following way:
+
+{\small%
+\begin{verbatim}
+  #include <iostream>
+
+  wxTextCtrl *control = new wxTextCtrl(...);
+
+  std::streambuf *sbOld = std::cout.rdbuf();
+  std::cout.rdbuf(*control);
+
+  // use cout as usual, the output appears in the text control
+  ...
+
+  std::cout.rdbuf(sbOld);
+\end{verbatim}
+}%
+
+But wxWindows provides a convenient class to make it even simpler so instead
+you may just do
+
+{\small%
+\begin{verbatim}
+  #include <iostream>
+
+  wxTextCtrl *control = new wxTextCtrl(...);
+
+  wxStreamToTextRedirector redirect(control);
+
+  // all output to cout goes into the text control until the exit from current
+  // scope
+\end{verbatim}
+}%
+
+See \helpref{wxStreamToTextRedirector}{wxstreamtotextredirector} for more
+details.
 
 \wxheading{Event handling}
 
@@ -93,10 +142,6 @@ into the control than the limit set by
 \helpref{SetMaxLength}{wxtextctrlsetmaxlength}.}
 \end{twocollist}%
 
-%\wxheading{See also}
-%
-%\helpref{wxRichTextCtrl}{wxrichtextctrl}
-%
 \latexignore{\rtfignore{\wxheading{Members}}}
 
 \membersection{wxTextCtrl::wxTextCtrl}\label{wxtextctrlconstr}