* wxStreams overview added to the documentation. I didn't yet tested it

  so I didn't activate it ...

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

diff --git a/docs/latex/wx/tstream.tex b/docs/latex/wx/tstream.tex
new file mode 100644 (file)
index 0000000..5c4bc5c
--- /dev/null
+++ b/docs/latex/wx/tstream.tex
@@ -0,0 +1,89 @@
+\section{Streams in wxWindows overview}\label{wxstreamoverview}
+
+Classes: \helpref{wxStreamBase}{wxstreambase},
+ \helpref{wxStreamBuffer}{wxstreambuffer}, \helpref{wxInputStream}{wxinputstream},
+ \helpref{wxOutputStream}{wxoutputstream},
+ \helpref{wxFilterInputStream}{wxfilterinputstream},
+ \helpref{wxFilterOutputStream}{wxfilteroutputstream}
+
+\wxheading{Purpose of wxStream}
+
+We went into troubles with c++ std streams on some platform:
+they react quite well in most cases, but in multi-threaded case, for example,
+they have a LOT of problems.
+
+Then, wxStreams have been built in wxWindows because an application should compile
+and run on all supported platforms and we don't want users depend on release
+X.XX of libg++ or some other compiler to run the program.
+
+wxStreams is divided in two main parts:
+\begin{enumerate}\itemsep=0pt
+\item the core: wxStreamBase, wxStreamBuffer, wxInputStream, wxOutputStream,
+wxFilterIn/OutputStream
+\item the "IO" classes: wxSocketIn/OutputStream, wxDataIn/OutputStream, wxFileIn/OutputStream, ...
+\end{enumerate}
+
+wxStreamBase is the base definition of a stream. It defines, for example,
+the API of OnSysRead, OnSysWrite, OnSysSeek and OnSysTell. These functions are
+are really implemented by the "IO" classes.
+wxInputStream and wxOutputStream inherit from it.
+
+wxStreamBuffer is a cache manager for wxStreamBase (it manages a stream buffer
+linked to a stream). One stream can have multiple stream buffers  but one stream
+have always one autoinitialized stream buffer.
+
+wxInputStream is the base class for read-only streams. It implements Read,
+SeekI (I for Input), and all read or IO generic related functions.
+wxOutputStream does the same thing but it is for write-only streams.
+
+wxFilterIn/OutputStream is base class definition for stream filtering.
+I mean by stream filtering, a stream which does no syscall but filter datas
+which are passed to it and then pass them to another stream.
+For example, wxZLibInputStream is an inline stream decompressor.
+
+The "IO" classes implements the specific parts of the stream. This could be
+nothing in the case of wxMemoryIn/OutputStream which bases itself on
+wxStreamBuffer. This could also be a simple link to the a true syscall
+(for example read(...), write(...)).
+
+\wxheading{Generic usage: an example}
+
+About its usage, it's simple. We can take the example of wxFileInputStream and here is a sample
+code:
+
+\begin{verbatim}
+ ...
+ // The constructor initializes the stream buffer and open the file descriptor
+ // associated to the name of the file.
+ wxFileInputStream in\_stream("the\_file\_to\_be\_read");
+
+ // Ok, read some bytes ... nb\_datas is expressed in bytes.
+ in\_stream.Read(data, nb\_datas);
+ if (in\_stream.LastError() != wxStream\_NOERROR) {
+   // Oh oh, something bad happens.
+   // For a complete list, look into the documentation at wxStreamBase.
+ }
+
+ // You can also inline all like this.
+ if (in\_stream.Read(data, nb\_datas).LastError() != wxStream\_NOERROR) {
+   // Do something.
+ }
+
+ // You can also get the last number of bytes REALLY put into the buffer.
+ size\_t really\_read = in\_stream.LastRead();
+
+ // Ok, moves to the beginning of the stream. SeekI returns the last position 
+ // in the stream counted from the beginning.
+ off\_t old_position = in\_stream.SeekI(0, wxFromBeginning);
+ 
+ // What is my current position ?
+ off\_t position = in\_stream.TellI();
+
+ // wxFileInputStream will close the file descriptor on the destruction.
+\end{verbatim}
+
+\wxheading{Compatibility with c++ stream}
+
+As I said previously, we could add a filter stream so it takes an istream
+argument and builds a wxInputStream from it: I don't think it should 
+be difficult to implement it and it may be available in the fix of wxWindows 2.0.