Use UTF16 for text data object on Mac. Fixes #10902

[wxWidgets.git] / docs / doxygen / overviews / stream.h

diff --git a/docs/doxygen/overviews/stream.h b/docs/doxygen/overviews/stream.h
index a10b5357efeec370384f8d3e8bb26d39f5a9fabc..a11b2668637f19d7800e47f9fd57f10210831e02 100644 (file)
--- a/docs/doxygen/overviews/stream.h
+++ b/docs/doxygen/overviews/stream.h
@@ -1,14 +1,14 @@
 /////////////////////////////////////////////////////////////////////////////
 // Name:        stream.h
 /////////////////////////////////////////////////////////////////////////////
 // Name:        stream.h

-// Purpose:     topic overview
+// Purpose:     stream classes overview

 // Author:      wxWidgets team
 // RCS-ID:      $Id$
 // Licence:     wxWindows license
 /////////////////////////////////////////////////////////////////////////////
 
 // Author:      wxWidgets team
 // RCS-ID:      $Id$
 // Licence:     wxWindows license
 /////////////////////////////////////////////////////////////////////////////
 

-/*!
+/**

 
 

-@page overview_stream wxStreams Overview
+@page overview_stream Stream classes overview

 
 Classes:
 @li wxStreamBase
 
 Classes:
 @li wxStreamBase


@@ -17,6 +17,12 @@ Classes:
 @li wxOutputStream
 @li wxFilterInputStream
 @li wxFilterOutputStream
 @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
 
 @li @ref overview_stream_intro
 @li @ref overview_stream_example


@@ -27,45 +33,60 @@ Classes:
 
 @section overview_stream_intro Introduction
 
 
 @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,
 
 @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
 
 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
 
 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
 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
 
 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
 
 
 @section overview_stream_example Example


@@ -94,7 +115,7 @@ if (in_stream.Read(data, nb_datas).LastError() != wxSTREAM_NOERROR) {
 // You can also get the last number of bytes REALLY put into the buffer.
 size_t really_read = in_stream.LastRead();
 
 // 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 
+// 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);
 
 // in the stream counted from the beginning.
 off_t old_position = in_stream.SeekI(0, wxFromBeginning);