X-Git-Url: https://git.saurik.com/wxWidgets.git/blobdiff_plain/30738aae14dfbce0c492d8696c861947228028c2..a25a17732c2d4d34d5d35a5318053dd8c6e29722:/docs/doxygen/overviews/stream.h?ds=sidebyside diff --git a/docs/doxygen/overviews/stream.h b/docs/doxygen/overviews/stream.h index a10b5357ef..a11b266863 100644 --- a/docs/doxygen/overviews/stream.h +++ b/docs/doxygen/overviews/stream.h @@ -1,14 +1,14 @@ ///////////////////////////////////////////////////////////////////////////// // Name: stream.h -// Purpose: topic overview +// Purpose: stream classes overview // Author: wxWidgets team // RCS-ID: $Id$ // Licence: wxWindows license ///////////////////////////////////////////////////////////////////////////// -/*! +/** -@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 @@ -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(); -// 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);