]> git.saurik.com Git - wxWidgets.git/blame - docs/latex/wx/tstream.tex
Always draw the selection of selected items, not just when they have
[wxWidgets.git] / docs / latex / wx / tstream.tex
CommitLineData
20e05ffb 1\section{wxStreams overview}\label{wxstreamoverview}
55b7bba1
GL
2
3Classes: \helpref{wxStreamBase}{wxstreambase},
4 \helpref{wxStreamBuffer}{wxstreambuffer}, \helpref{wxInputStream}{wxinputstream},
5 \helpref{wxOutputStream}{wxoutputstream},
6 \helpref{wxFilterInputStream}{wxfilterinputstream},
7 \helpref{wxFilterOutputStream}{wxfilteroutputstream}
8
9\wxheading{Purpose of wxStream}
10
aea22172
JS
11Standard C++ streams can cause problems on several platforms:
12they work quite well in most cases, but in the multi-threaded case, for example,
13they have many problems. Some Borland compilers refuse to work at all
14with them and using iostreams on Linux makes writing programs that are
4130b487 15binary compatible across different Linux distributions, impossible.
55b7bba1 16
aea22172
JS
17Therefore, wxStreams have been added to wxWidgets so that applications can
18reliably compile and run on all supported platforms without dependence on a
19particular release of libg++.
55b7bba1
GL
20
21wxStreams is divided in two main parts:
2723cfeb 22
55b7bba1
GL
23\begin{enumerate}\itemsep=0pt
24\item the core: wxStreamBase, wxStreamBuffer, wxInputStream, wxOutputStream,
25wxFilterIn/OutputStream
26\item the "IO" classes: wxSocketIn/OutputStream, wxDataIn/OutputStream, wxFileIn/OutputStream, ...
27\end{enumerate}
28
29wxStreamBase is the base definition of a stream. It defines, for example,
f6bcfd97 30the API of OnSysRead, OnSysWrite, OnSysSeek and OnSysTell. These functions
55b7bba1
GL
31are really implemented by the "IO" classes.
32wxInputStream and wxOutputStream inherit from it.
33
aea22172
JS
34wxStreamBuffer is a cache manager for wxStreamBase: it manages a stream buffer
35linked to a stream. One stream can have multiple stream buffers but one stream
55b7bba1
GL
36have always one autoinitialized stream buffer.
37
38wxInputStream is the base class for read-only streams. It implements Read,
39SeekI (I for Input), and all read or IO generic related functions.
40wxOutputStream does the same thing but it is for write-only streams.
41
f6bcfd97
BP
42wxFilterIn/OutputStream is the base class definition for stream filtering.
43Stream filtering means a stream which does no syscall but filters data
55b7bba1
GL
44which are passed to it and then pass them to another stream.
45For example, wxZLibInputStream is an inline stream decompressor.
46
47The "IO" classes implements the specific parts of the stream. This could be
48nothing in the case of wxMemoryIn/OutputStream which bases itself on
49wxStreamBuffer. This could also be a simple link to the a true syscall
50(for example read(...), write(...)).
51
52\wxheading{Generic usage: an example}
53
2723cfeb 54Usage is simple. We can take the example of wxFileInputStream and here is some sample
55b7bba1
GL
55code:
56
57\begin{verbatim}
58 ...
59 // The constructor initializes the stream buffer and open the file descriptor
60 // associated to the name of the file.
4130b487 61 wxFileInputStream in_stream("the_file_to_be_read");
55b7bba1 62
4130b487
RR
63 // Ok, read some bytes ... nb_datas is expressed in bytes.
64 in_stream.Read(data, nb_datas);
20e05ffb 65 if (in_stream.LastError() != wxSTREAM_NOERROR) {
55b7bba1
GL
66 // Oh oh, something bad happens.
67 // For a complete list, look into the documentation at wxStreamBase.
68 }
69
70 // You can also inline all like this.
20e05ffb 71 if (in_stream.Read(data, nb_datas).LastError() != wxSTREAM_NOERROR) {
55b7bba1
GL
72 // Do something.
73 }
74
75 // You can also get the last number of bytes REALLY put into the buffer.
4130b487 76 size_t really_read = in_stream.LastRead();
55b7bba1
GL
77
78 // Ok, moves to the beginning of the stream. SeekI returns the last position
79 // in the stream counted from the beginning.
4130b487 80 off_t old_position = in_stream.SeekI(0, wxFromBeginning);
55b7bba1
GL
81
82 // What is my current position ?
4130b487 83 off_t position = in_stream.TellI();
55b7bba1 84
aea22172 85 // wxFileInputStream will close the file descriptor on destruction.
55b7bba1
GL
86\end{verbatim}
87