X-Git-Url: https://git.saurik.com/wxWidgets.git/blobdiff_plain/3c4f71cc3d63fb7bdfbd6cec3e39c8a8679f3e60..a25a17732c2d4d34d5d35a5318053dd8c6e29722:/docs/doxygen/overviews/stream.h

diff --git a/docs/doxygen/overviews/stream.h b/docs/doxygen/overviews/stream.h
index 6a52ffd6e9..a11b266863 100644
--- a/docs/doxygen/overviews/stream.h
+++ b/docs/doxygen/overviews/stream.h
@@ -1,6 +1,6 @@
 /////////////////////////////////////////////////////////////////////////////
 // Name:        stream.h
-// Purpose:     topic overview
+// Purpose:     stream classes overview
 // Author:      wxWidgets team
 // RCS-ID:      $Id$
 // Licence:     wxWindows license
@@ -8,7 +8,7 @@
 
 /**
 
-@page overview_stream wxStreams Overview
+@page overview_stream Stream classes overview
 
 Classes:
 @li wxStreamBase
@@ -17,6 +17,12 @@ Classes:
 @li wxOutputStream
 @li wxFilterInputStream
 @li wxFilterOutputStream
+@li wxFileInputStream
+@li wxFileOutputStream
+@li wxTextInputStream
+@li wxTextOutputStream
+@li wxDataInputStream
+@li wxDataOutputStream
 
 @li @ref overview_stream_intro
 @li @ref overview_stream_example
@@ -27,45 +33,60 @@ Classes:
 
 @section overview_stream_intro Introduction
 
-Standard C++ streams can cause problems on several platforms: they work quite
-well in most cases, but in the multi-threaded case, for example, they have many
-problems. Some Borland compilers refuse to work at all with them and using
-iostreams on Linux makes writing programs that are binary compatible across
-different Linux distributions, impossible.
+@subsection overview_stream_intro_std wxWidgets and Standard Streams
 
-Therefore, wxStreams have been added to wxWidgets so that applications can
-reliably compile and run on all supported platforms without dependence on a
-particular release of libg++.
+wxWidgets provides its own set of stream classes in order to support platforms
+not providing standard C++ streams implementation and also to make it possible
+to provide binary versions of wxWidgets application not depending on any
+particular standard library version. The wxWidgets stream classes also provide
+some functionality not available in the standard library such as support for
+several compression formats and possibility to work with sockets or text
+controls (for output only in the latter case).
 
-wxStreams is divided in two main parts:
+Nevertheless wxWidgets programs can also use standard stream classes and are
+encouraged to do so if the above considerations don't apply. Moreover,
+wxStdInputStream and wxStdOutputStream classes are provided to provide a degree
+of interoperability between the two and make it possible to use any wxWidgets
+stream as a standard stream (the converse possibility to use a standard stream
+as a wxWidgets stream is planned for a future release).
+
+
+@subsection overview_stream_intro_overview Stream Classes
+
+wxStream classes are divided in two main groups:
 
 @li The core: wxStreamBase, wxStreamBuffer, wxInputStream, wxOutputStream,
-    wxFilterIn/OutputStream
-@li The "IO" classes: wxSocketIn/OutputStream, wxDataIn/OutputStream,
-    wxFileIn/OutputStream, ...
+    wxFilterInputStream, wxFilterOutputStream
+@li The "IO" classes: wxSocketInputStream, wxSocketOutputStream,
+    wxFileInputStream, wxFileOutputStream, ...
+@li Classes for reading text or binary data from a particular stream
+    such as wxTextInputStream, wxTextOutputStream, wxDataInputStream
+    and wxDataOutputStream
 
 wxStreamBase is the base definition of a stream. It defines, for example, the
-API of OnSysRead, OnSysWrite, OnSysSeek and OnSysTell. These functions are
-really implemented by the "IO" classes. wxInputStream and wxOutputStream
-inherit from it.
+API of OnSysRead(), OnSysWrite(), OnSysSeek() and OnSysTell(). These functions are
+really implemented by the "IO" classes.
+wxInputStream and wxOutputStream classes inherit from wxStreamBase and provide
+specialized methods for input and output.
 
 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.
+linked to a stream. One stream can have multiple stream buffers but one stream
+has 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.
+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 for write-only streams.
 
-wxFilterIn/OutputStream is the base class definition for stream filtering.
+wxFilterInputStream and wxFileterOutputStream are the base class definitions for
+stream filtering.
 Stream filtering means a stream which does no syscall but filters data which
-are passed to it and then pass them to another stream. For example,
-wxZLibInputStream is an inline stream decompressor.
+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(...)).
+nothing in the case of wxMemoryInputStream and wxMemoryOutputStream which base
+themselves on wxStreamBuffer.
+This could also be a simple link to the true syscall (for example read(...), write(...)).
 
 
 @section overview_stream_example Example