fix LaTeX error (escape underscores); don't abuse bold face

[wxWidgets.git] / docs / latex / wx / stream.tex

diff --git a/docs/latex/wx/stream.tex b/docs/latex/wx/stream.tex
index 2715542dddcdaa59afb472740aed676f4e3c9752..420a2c04db2921672986daa7638f560758b1a3b9 100644 (file)
--- a/docs/latex/wx/stream.tex
+++ b/docs/latex/wx/stream.tex
@@ -4,215 +4,338 @@
 
 None
 
 
 None
 

+\wxheading{Include files}
+
+<wx/stream.h>
+
+\wxheading{Library}
+
+\helpref{wxBase}{librarieslist}
+

 \wxheading{See also}
 
 \helpref{wxStreamBase}{wxstreambase}
 
 \wxheading{See also}
 
 \helpref{wxStreamBase}{wxstreambase}
 

-% ---------------------------------------------------------------------------
-% Members
-% ---------------------------------------------------------------------------

 \latexignore{\rtfignore{\wxheading{Members}}}
 
 \latexignore{\rtfignore{\wxheading{Members}}}
 

-% -----------
-% ctor & dtor
-% -----------
-\membersection{wxStreamBuffer::wxStreamBuffer}
+
+\membersection{wxStreamBuffer::wxStreamBuffer}\label{wxstreambufferctor}

 
 \func{}{wxStreamBuffer}{\param{wxStreamBase\&}{ stream}, \param{BufMode}{ mode}}
 
 
 \func{}{wxStreamBuffer}{\param{wxStreamBase\&}{ stream}, \param{BufMode}{ mode}}
 

-Constructor, creates a new stream buffer using \it{stream} as a parent stream
-and \it{mode} as the IO mode. \it{mode} can be: wxStreamBuffer::read,
+Constructor, creates a new stream buffer using {\it stream} as a parent stream
+and {\it mode} as the IO mode. {\it mode} can be: wxStreamBuffer::read,

 wxStreamBuffer::write, wxStreamBuffer::read\_write.
 
 wxStreamBuffer::write, wxStreamBuffer::read\_write.
 

-\membersection{wxStreamBuffer::wxStreamBuffer}
+One stream can have many stream buffers but only one is used internally to
+pass IO call (e.g. wxInputStream::Read() -> wxStreamBuffer::Read()), but you
+can call directly wxStreamBuffer::Read without any problems. Note that
+all errors and messages linked to the stream are stored in the stream, not
+the stream buffers:
+
+\begin{verbatim}
+  streambuffer.Read(...);
+  streambuffer2.Read(...); /* This call erases previous error messages set by 
+                              ``streambuffer'' */
+\end{verbatim}

 
 \func{}{wxStreamBuffer}{\param{BufMode}{ mode}}
 
 Constructor, creates a new empty stream buffer which won't flush any data
 
 \func{}{wxStreamBuffer}{\param{BufMode}{ mode}}
 
 Constructor, creates a new empty stream buffer which won't flush any data

-to a stream. \it{mode} specifies the type of the buffer (read, write, read\_write).
+to a stream. {\it mode} specifies the type of the buffer (read, write, read\_write).
+This stream buffer has the advantage to be stream independent and to
+work only on memory buffers but it is still compatible with the rest of the
+wxStream classes. You can write, read to this special stream and it will
+grow (if it is allowed by the user) its internal buffer. Briefly, it has all
+functionality of a ``normal'' stream.

 
 

-\membersection{wxStreamBuffer::wxStreamBuffer}
+\wxheading{Warning}

 
 

-\func{}{wxStreamBuffer}{\param{const wxStreamBase\&}{ buffer}}
+The "read\_write" mode doesn't currently work for standalone stream buffers.

 
 

-Constructor, creates a new stream buffer from the specified stream \it{buffer}.
+\func{}{wxStreamBuffer}{\param{const wxStreamBuffer\&}{buffer}}

 
 

-\membersection{wxStreamBuffer::\destruct{wxStreamBuffer}}
+Constructor. It initializes the stream buffer with the data of the specified
+stream buffer. The new stream buffer has the same attributes, size, position
+and they share the same buffer. This will cause problems if the stream to
+which the stream buffer belong is destroyed and the newly cloned stream
+buffer continues to be used, trying to call functions in the (destroyed)
+stream. It is advised to use this feature only in very local area of the
+program.
+
+\wxheading{See also}
+
+\helpref{wxStreamBuffer:SetBufferIO}{wxstreambuffersetbufferio}
+
+
+\membersection{wxStreamBuffer::\destruct{wxStreamBuffer}}\label{wxstreambufferdtor}

 
 \func{}{wxStreamBuffer}{\destruct{wxStreamBuffer}}
 
 
 \func{}{wxStreamBuffer}{\destruct{wxStreamBuffer}}
 

-Destructor, destroys the stream buffer.
+Destructor. It finalizes all IO calls and frees all internal buffers if
+necessary.

 
 

-% -----------
-% Filtered IO
-% -----------
-\membersection{wxStreamBuffer::Read}\label{wxstreambufread}

 
 

-\func{size\_t}{Read}{\param{void *}{buffer}, \param{size\_t }{size}}
+\membersection{wxStreamBuffer::FillBuffer}\label{wxstreambufferfillbuffer}

 
 

-Reads a block of the specified \it{size} and stores datas in \it{buffer}.
+\func{bool}{FillBuffer}{\void}

 
 

-\wxheading{Return value}
+Fill the IO buffer.

 
 

-It returns the real read size. If returned size is different of the specified 
-\it{size}, an error occured and should be tested using 
-\helpref{LastError}{wxstreambaselasterror}.

 
 

-\membersection{wxStreamBuffer::Read}\label{wxstreambufreadbuf}
+\membersection{wxStreamBuffer::Fixed}\label{wxstreambufferfixed}

 
 

-\func{size\_t}{Read}{\param{wxStreamBuffer *}{buffer}}
+\func{void}{Fixed}{\param{bool}{ fixed}}

 
 

-Reads a \it{buffer}. The function returns when \it{buffer} is full or
-when there aren't datas anymore in the current buffer.
+Toggles the fixed flag. Usually this flag is toggled at the same time as 
+{\it flushable}. This flag allows (when it has the false value) or forbids
+(when it has the true value) the stream buffer to resize dynamically the IO buffer.

 
 

-\membersection{wxStreamBuffer::Write}
+\wxheading{See also}

 
 

-\func{size\_t}{Write}{\param{const void *}{buffer}, \param{size\_t }{size}}
+\helpref{wxStreamBuffer::SetBufferIO}{wxstreambuffersetbufferio}

 
 

-Writes a block of the specified \it{size} using datas of \it{buffer}.

 
 

-\membersection{wxStreamBuffer::Write}
+\membersection{wxStreamBuffer::Flushable}\label{wxstreambufferflushable}

 
 

-\func{size\_t}{Write}{\param{wxStreamBuffer *}{buffer}}
+\func{void}{Flushable}{\param{bool}{ flushable}}

 
 

-See \helpref{Read}{wxstreambufreadbuf}
+Toggles the flushable flag. If {\it flushable} is disabled, no data are sent
+to the parent stream.

 
 

-\membersection{wxStreamBuffer::WriteBack}

 
 

-\func{size\_t}{WriteBack}{\param{const char*}{ buffer}, \param{size\_t}{ size}}
+\membersection{wxStreamBuffer::FlushBuffer}\label{wxstreambufferflushbuffer}
+
+\func{bool}{FlushBuffer}{\void}
+
+Flushes the IO buffer.

 
 

-This function is only useful in ``read'' mode. It puts the specified \it{buffer}
-in the input queue of the stream buf. By this way, the next
-\helpref{Read}{wxstreambufread} call will first use these datas.

 
 

-\membersection{wxStreamBuffer::WriteBack}
+\membersection{wxStreamBuffer::GetBufferEnd}\label{wxstreambuffergetbufferend}
+
+\constfunc{void *}{GetBufferEnd}{\void}
+
+Returns a pointer on the end of the stream buffer.

 
 

-\func{size\_t}{WriteBack}{\param{char }{c}}

 
 

-As for the previous function, it puts the specified byte in the input queue of the
-stream buffer.
+\membersection{wxStreamBuffer::GetBufferPos}\label{wxstreambuffergetbufferpos}

 
 

-\membersection{wxStreamBuffer::GetChar}
+\constfunc{void *}{GetBufferPos}{\void}
+
+Returns a pointer on the current position of the stream buffer.
+
+
+\membersection{wxStreamBuffer::GetBufferSize}\label{wxstreambuffergetbuffersize}
+
+\constfunc{size\_t}{GetBufferSize}{\void}
+
+Returns the size of the buffer.
+
+
+\membersection{wxStreamBuffer::GetBufferStart}\label{wxstreambuffergetbufferstart}
+
+\constfunc{void *}{GetBufferStart}{\void}
+
+Returns a pointer on the start of the stream buffer.
+
+
+\membersection{wxStreamBuffer::GetChar}\label{wxstreambuffergetchar}

 
 \func{char}{GetChar}{\void}
 
 
 \func{char}{GetChar}{\void}
 

-Gets a single char from the stream buffer.
+Gets a single char from the stream buffer. It acts like the Read call.
+
+\wxheading{Problem}
+
+You aren't directly notified if an error occurred during the IO call.
+
+\wxheading{See also}
+
+\helpref{wxStreamBuffer::Read}{wxstreambufferread}
+
+
+\membersection{wxStreamBuffer::GetDataLeft}\label{wxstreambuffergetdataleft}
+
+\func{size\_t}{GetDataLeft}{\void}
+
+Returns the amount of available data in the buffer.
+
+
+\membersection{wxStreamBuffer::GetIntPosition}\label{wxstreambuffergetintposition}
+
+\constfunc{off\_t}{GetIntPosition}{\void}
+
+Returns the current position (counted in bytes) in the stream buffer.
+

 
 

-\membersection{wxStreamBuffer::PutChar}
+\membersection{wxStreamBuffer::GetLastAccess}\label{wxstreambuffergetlastaccess}
+
+\constfunc{size\_t}{GetLastAccess}{\void}
+
+Returns the amount of bytes read during the last IO call to the parent stream.
+
+
+\membersection{wxStreamBuffer::PutChar}\label{wxstreambufferputchar}

 
 \func{void}{PutChar}{\param{char }{c}}
 
 Puts a single char to the stream buffer.
 
 
 \func{void}{PutChar}{\param{char }{c}}
 
 Puts a single char to the stream buffer.
 

-\membersection{wxStreamBuffer::Tell}
+\wxheading{Problem}

 
 

-\constfunc{off\_t}{Tell}{\void}
+You aren't directly notified if an error occurred during the IO call.
+
+\wxheading{See also}
+
+\helpref{wxStreamBuffer::Read}{wxstreambufferwrite}
+
+
+\membersection{wxStreamBuffer::Read}\label{wxstreambufferread}
+
+\func{size\_t}{Read}{\param{void *}{buffer}, \param{size\_t }{size}}
+
+Reads a block of the specified {\it size} and stores the data in {\it buffer}.
+This function tries to read from the buffer first and if more data has been
+requested, reads more data from the associated stream and updates the buffer
+accordingly until all requested data is read.
+
+\wxheading{Return value}
+
+It returns the size of the data read. If the returned size is different of the specified 
+{\it size}, an error has occurred and should be tested using 
+\helpref{GetLastError}{wxstreambasegetlasterror}.
+
+\func{size\_t}{Read}{\param{wxStreamBuffer *}{buffer}}
+
+Copies data to {\it buffer}. The function returns when {\it buffer} is full or when there isn't
+any more data in the current buffer.
+
+\wxheading{See also}
+
+\helpref{wxStreamBuffer::Write}{wxstreambufferwrite}
+
+
+\membersection{wxStreamBuffer::ResetBuffer}\label{wxstreambufferresetbuffer}
+
+\func{void}{ResetBuffer}{\void}
+
+Resets to the initial state variables concerning the buffer.

 
 

-Gets the current position in the \it{stream}.

 
 \membersection{wxStreamBuffer::Seek}\label{wxstreambufferseek}
 
 \func{off\_t}{Seek}{\param{off\_t }{pos}, \param{wxSeekMode }{mode}}
 
 
 \membersection{wxStreamBuffer::Seek}\label{wxstreambufferseek}
 
 \func{off\_t}{Seek}{\param{off\_t }{pos}, \param{wxSeekMode }{mode}}
 

-Changes the current position. (TODO)
+Changes the current position.

 
 

-% --------------
-% Buffer control
-% --------------
-\membersection{wxStreamBuffer::ResetBuffer}
+{\it mode} may be one of the following:

 
 

-\func{void}{ResetBuffer}{\void}
+\twocolwidtha{5cm}
+\begin{twocollist}\itemsep=0pt
+\twocolitem{{\bf wxFromStart}}{The position is counted from the start of the stream.}
+\twocolitem{{\bf wxFromCurrent}}{The position is counted from the current position of the stream.}
+\twocolitem{{\bf wxFromEnd}}{The position is counted from the end of the stream.}
+\end{twocollist}
+
+\wxheading{Return value}
+
+Upon successful completion, it returns the new offset as measured in bytes from
+the beginning of the stream. Otherwise, it returns wxInvalidOffset.

 
 

-Frees all internal buffers and resets to initial state all variables.

 
 

-\membersection{wxStreamBuffer::SetBufferIO}
+\membersection{wxStreamBuffer::SetBufferIO}\label{wxstreambuffersetbufferio}

 
 \func{void}{SetBufferIO}{\param{char*}{ buffer\_start}, \param{char*}{ buffer\_end}}
 
 Specifies which pointers to use for stream buffering. You need to pass a pointer on the
 
 \func{void}{SetBufferIO}{\param{char*}{ buffer\_start}, \param{char*}{ buffer\_end}}
 
 Specifies which pointers to use for stream buffering. You need to pass a pointer on the

-start of the buffer end and another on the end.
+start of the buffer end and another on the end. The object will use this buffer
+to cache stream data. It may be used also as a source/destination buffer when
+you create an empty stream buffer (See \helpref{wxStreamBuffer::wxStreamBuffer}{wxstreambufferctor}).

 
 

-\membersection{wxStreamBuffer::SetBufferIO}
+\wxheading{Remarks}

 
 

-\func{void}{SetBufferIO}{\param{size\_t}{ bufsize}}
+When you use this function, you will have to destroy the IO buffers yourself
+after the stream buffer is destroyed or don't use it anymore.
+In the case you use it with an empty buffer, the stream buffer will not resize
+it when it is full.

 
 

-Changes the size of the current IO buffer.
+\wxheading{See also}

 
 

-\membersection{wxStreamBuffer::GetBufferStart}
+\helpref{wxStreamBuffer constructor}{wxstreambufferctor}\\
+\helpref{wxStreamBuffer::Fixed}{wxstreambufferfixed}\\
+\helpref{wxStreamBuffer::Flushable}{wxstreambufferflushable}

 
 

-\constfunc{char *}{GetBufferStart}{\void}
+\func{void}{SetBufferIO}{\param{size\_t}{ bufsize}}

 
 

-Returns a pointer on the start of the stream buffer.
+Destroys or invalidates the previous IO buffer and allocates a new one of the
+specified size.

 
 

-\membersection{wxStreamBuffer::GetBufferEnd}
+\wxheading{Warning}

 
 

-\constfunc{char *}{GetBufferEnd}{\void}
+All previous pointers aren't valid anymore.

 
 

-Returns a pointer on the end of the stream buffer.
+\wxheading{Remark}

 
 

-\membersection{wxStreamBuffer::GetBufferPos}
+The created IO buffer is growable by the object.

 
 

-\constfunc{char *}{GetBufferPos}{\void}
+\wxheading{See also}

 
 

-Returns a pointer on the current position of the stream buffer.
+\helpref{wxStreamBuffer::Fixed}{wxstreambufferfixed}\\
+\helpref{wxStreamBuffer::Flushable}{wxstreambufferflushable}

 
 

-\membersection{wxStreamBuffer::GetIntPosition}

 
 

-\constfunc{off\_t}{GetIntPosition}{\void}
+\membersection{wxStreamBuffer::SetIntPosition}\label{wxstreambuffersetintposition}

 
 

-Returns the current position in the stream buffer.
+\func{void}{SetIntPosition}{\param{size\_t}{ pos}}

 
 

-\membersection{wxStreamBuffer::SetIntPosition}
+Sets the current position (in bytes) in the stream buffer.

 
 

-\func{void}{SetIntPosition}{\void}
+\wxheading{Warning}

 
 

-Sets the current position in the stream buffer.
+Since it is a very low-level function, there is no check on the position:
+specifying an invalid position can induce unexpected results.

 
 

-\membersection{wxStreamBuffer::GetLastAccess}

 
 

-\constfunc{size\_t}{GetLastAccess}{\void}
+\membersection{wxStreamBuffer::Stream}\label{wxstreambufferstream}

 
 

-Returns the amount of bytes read during the last IO call to the parent stream.
+\func{wxStreamBase*}{Stream}{\void}

 
 

-\membersection{wxStreamBuffer::Fixed}
+Returns the parent stream of the stream buffer.

 
 

-\func{void}{Fixed}{\param{bool}{ fixed}}

 
 

-Toggles the fixed flag. Usually this flag is toggled at the same time as 
-\it{flushable}. This flag allows (when it is FALSE) or forbids (when it is TRUE)
-the stream buffer to resize dynamically the IO buffer.
+\membersection{wxStreamBuffer::Tell}\label{wxstreambuffertell}

 
 

-\membersection{wxStreamBuffer::Flushable}
+\constfunc{off\_t}{Tell}{\void}

 
 

-\func{void}{Flushable}{\param{bool}{ flushable}}
+Gets the current position in the stream. This position is calculated from
+the {\it real} position in the stream and from the internal buffer position: so
+it gives you the position in the {\it real} stream counted from the start of
+the stream.

 
 

-Toggles the flushable flag. If \it{flushable} is disabled, no datas are sent
-to the parent stream.
+\wxheading{Return value}

 
 

-\membersection{wxStreamBuffer::FlushBuffer}
+Returns the current position in the stream if possible, wxInvalidOffset in the
+other case.

 
 

-\func{bool}{FlushBuffer}{\void}

 
 

-Flushes the IO buffer.
+\membersection{wxStreamBuffer::Truncate}\label{wxstreambuffertruncate}

 
 

-\membersection{wxStreamBuffer::FillBuffer}
+\func{void}{Truncate}{\void}

 
 

-\func{bool}{FillBuffer}{\void}
+Truncates the buffer to the current position.

 
 

-Fill the IO buffer.
+Note: Truncate() cannot be used to enlarge the buffer. This is
+usually not needed since the buffer expands automatically.

 
 

-\membersection{wxStreamBuffer::GetDataLeft}

 
 

-\func{size\_t}{GetDataLeft}{\void}
+\membersection{wxStreamBuffer::Write}\label{wxstreambufferwrite}

 
 

-Returns the amount of available datas in the buffer.
+\func{size\_t}{Write}{\param{const void *}{buffer}, \param{size\_t }{size}}

 
 

-% --------------
-% Administration
-% --------------
-\membersection{wxStreamBuffer::Stream}
+Writes a block of the specified {\it size} using data of {\it buffer}. The data
+are cached in a buffer before being sent in one block to the stream.

 
 

-\func{wxStreamBase*}{Stream}{\void}
+\func{size\_t}{Write}{\param{wxStreamBuffer *}{buffer}}

 
 

-Returns the stream parent of the stream buffer.
+See \helpref{Read}{wxstreambufferread}.