HitTest() seems to be implemented on most platforms now (replaces patch 1467212)

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

diff --git a/docs/latex/wx/txtstrm.tex b/docs/latex/wx/txtstrm.tex
index 515ecbaf6ecdaabc83cbd51ea4aa20d86a84da46..70afd2cca0df5b06c03892b63327ca2813a8def1 100644 (file)
--- a/docs/latex/wx/txtstrm.tex
+++ b/docs/latex/wx/txtstrm.tex
@@ -15,6 +15,12 @@ and on a typical 32-bit computer, none of these match to the "long" type (wxInt3
 is defined as int on 32-bit architectures) so that you cannot use long. To avoid
 problems (here and elsewhere), make use of wxInt32, wxUint32 and similar types.
 
 is defined as int on 32-bit architectures) so that you cannot use long. To avoid
 problems (here and elsewhere), make use of wxInt32, wxUint32 and similar types.
 

+If you're scanning through a file using wxTextInputStream, you should check for EOF {\bf before}
+reading the next item (word / number), because otherwise the last item may get lost. 
+You should however be prepared to receive an empty item (empty string / zero number) at the
+end of file, especially on Windows systems. This is unavoidable because most (but not all) files end
+with whitespace (i.e. usually a newline).
+

 For example:
 
 \begin{verbatim}
 For example:
 
 \begin{verbatim}


@@ -35,53 +41,148 @@ For example:
 
 \latexignore{\rtfignore{\wxheading{Members}}}
 
 
 \latexignore{\rtfignore{\wxheading{Members}}}
 

-\membersection{wxTextInputStream::wxTextInputStream}\label{wxtextinputstreamconstr}

 
 

-\func{}{wxTextInputStream}{\param{wxInputStream\&}{ stream}}
+\membersection{wxTextInputStream::wxTextInputStream}\label{wxtextinputstreamctor}
+
+\func{}{wxTextInputStream}{\param{wxInputStream\&}{ stream}, \param{const wxString\&}{ sep=" $\backslash$t"}, 
+  \param{wxMBConv\&}{ conv = wxConvUTF8} }

 
 

-Constructs a text stream object from an input stream. Only read methods will
-be available.
+Constructs a text stream associated to the given input stream.

 
 \wxheading{Parameters}
 
 
 \wxheading{Parameters}
 

-\docparam{stream}{The input stream.}
+\docparam{stream}{The underlying input stream.}
+
+\docparam{sep}{The initial string separator characters.}
+
+\docparam{conv}{{\it In Unicode build only:} The encoding converter used to convert the bytes in the
+  underlying input stream to characters.}
+

 
 

-\membersection{wxTextInputStream::\destruct{wxTextInputStream}}
+\membersection{wxTextInputStream::\destruct{wxTextInputStream}}\label{wxtextinputstreamdtor}

 
 \func{}{\destruct{wxTextInputStream}}{\void}
 
 Destroys the wxTextInputStream object.
 
 
 \func{}{\destruct{wxTextInputStream}}{\void}
 
 Destroys the wxTextInputStream object.
 

-\membersection{wxTextInputStream::Read8}

 
 

-\func{wxUint8}{Read8}{\void}
+\membersection{wxTextInputStream::Read8}\label{wxtextinputstreamread8}
+
+\func{wxUint8}{Read8}{\param{int}{ base = 10}}
+
+Reads a single unsigned byte from the stream, given in base {\it base}.
+
+The value of {\it base} must be comprised between $2$ and $36$, inclusive, or
+be a special value $0$ which means that the usual rules of {\tt C} numbers are
+applied: if the number starts with {\tt 0x} it is considered to be in base
+$16$, if it starts with {\tt 0} - in base $8$ and in base $10$ otherwise. Note
+that you may not want to specify the base $0$ if you are parsing the numbers
+which may have leading zeroes as they can yield unexpected (to the user not
+familiar with C) results.
+
+
+\membersection{wxTextInputStream::Read8S}\label{wxtextinputstreamread8s}
+
+\func{wxInt8}{Read8S}{\param{int}{ base = 10}}
+
+Reads a single signed byte from the stream.
+
+See \helpref{wxTextInputStream::Read8}{wxtextinputstreamread8} for the
+description of the {\it base} parameter.
+
+
+\membersection{wxTextInputStream::Read16}\label{wxtextinputstreamread16}
+
+\func{wxUint16}{Read16}{\param{int}{ base = 10}}
+
+Reads a unsigned 16 bit integer from the stream.

 
 

-Reads a single byte from the stream.
+See \helpref{wxTextInputStream::Read8}{wxtextinputstreamread8} for the
+description of the {\it base} parameter.

 
 

-\membersection{wxTextInputStream::Read16}

 
 

-\func{wxUint16}{Read16}{\void}
+\membersection{wxTextInputStream::Read16S}\label{wxtextinputstreamread16s}

 
 

-Reads a 16 bit integer from the stream.
+\func{wxInt16}{Read16S}{\param{int}{ base = 10}}

 
 

-\membersection{wxTextInputStream::Read32}
+Reads a signed 16 bit integer from the stream.

 
 

-\func{wxUint16}{Read32}{\void}
+See \helpref{wxTextInputStream::Read8}{wxtextinputstreamread8} for the
+description of the {\it base} parameter.

 
 

-Reads a 32 bit integer from the stream.

 
 

-\membersection{wxTextInputStream::ReadDouble}
+\membersection{wxTextInputStream::Read32}\label{wxtextinputstreamread32}
+
+\func{wxUint32}{Read32}{\param{int}{ base = 10}}
+
+Reads a 32 bit unsigned integer from the stream.
+
+See \helpref{wxTextInputStream::Read8}{wxtextinputstreamread8} for the
+description of the {\it base} parameter.
+
+
+\membersection{wxTextInputStream::Read32S}\label{wxtextinputstreamread32s}
+
+\func{wxInt32}{Read32S}{\param{int}{ base = 10}}
+
+Reads a 32 bit signed integer from the stream.
+
+See \helpref{wxTextInputStream::Read8}{wxtextinputstreamread8} for the
+description of the {\it base} parameter.
+
+
+\membersection{wxTextInputStream::GetChar}\label{wxtextinputstreamgetchar}
+
+\func{wxChar}{GetChar}{\void}
+
+Reads a character, returns $0$ if there are no more characters in the stream.
+
+
+\membersection{wxTextInputStream::ReadDouble}\label{wxtextinputstreamreaddouble}

 
 \func{double}{ReadDouble}{\void}
 
 Reads a double (IEEE encoded) from the stream.
 
 
 \func{double}{ReadDouble}{\void}
 
 Reads a double (IEEE encoded) from the stream.
 

-\membersection{wxTextInputStream::ReadString}

 
 

-\func{wxString}{wxTextInputStream::ReadString}{\void}
+\membersection{wxTextInputStream::ReadLine}\label{wxtextinputstreamreadline}
+
+\func{wxString}{ReadLine}{\void}
+
+Reads a line from the input stream and returns it (without the end of line
+character).

 
 

-Reads a line from the stream. A line is a string which ends with 
-$\backslash$n or $\backslash$r$\backslash$n or $\backslash$r.
+
+\membersection{wxTextInputStream::ReadString}\label{wxtextinputstreamreadstring}
+
+\func{wxString}{ReadString}{\void}
+
+{\bf NB:} This method is deprecated, use \helpref{ReadLine}{wxtextinputstreamreadline} 
+or \helpref{ReadWord}{wxtextinputstreamreadword} instead.
+
+Same as \helpref{ReadLine}{wxtextinputstreamreadline}.
+
+
+\membersection{wxTextInputStream::ReadWord}\label{wxtextinputstreamreadword}
+
+\func{wxString}{ReadWord}{\void}
+
+Reads a word (a sequence of characters until the next separator) from the
+input stream.
+
+\wxheading{See also}
+
+\helpref{SetStringSeparators}{wxtextinputstreamsetstringseparators}
+
+
+\membersection{wxTextInputStream::SetStringSeparators}\label{wxtextinputstreamsetstringseparators}
+
+\func{void}{SetStringSeparators}{\param{const wxString\& }{sep}}
+
+Sets the characters which are used to define the word boundaries in 
+\helpref{ReadWord}{wxtextinputstreamreadword}.
+
+The default separators are the space and {\tt TAB} characters.

 
 % ----------------------------------------------------------------------------
 % wxTextOutputStream
 
 % ----------------------------------------------------------------------------
 % wxTextOutputStream


@@ -106,14 +207,18 @@ You can also simulate the C++ cout class:
 The wxTextOutputStream writes text files (or streams) on DOS, Macintosh
 and Unix in their native formats (concerning the line ending).
 
 The wxTextOutputStream writes text files (or streams) on DOS, Macintosh
 and Unix in their native formats (concerning the line ending).
 

+\wxheading{Include files}
+
+<wx/txtstrm.h>
+

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

-\membersection{wxTextOutputStream::wxTextOutputStream}\label{wxtextoutputstreamconstr}

 
 

-\func{}{wxTextOutputStream}{\param{wxOutputStream\&}{ stream}, \param{wxEOL}{ mode = wxEOL\_NATIVE}}
+\membersection{wxTextOutputStream::wxTextOutputStream}\label{wxtextoutputstreamctor}

 
 

-Constructs a text stream object from an output stream. Only write methods will
-be available.
+\func{}{wxTextOutputStream}{\param{wxOutputStream\&}{ stream}, \param{wxEOL}{ mode = wxEOL\_NATIVE}, \param{wxMBConv\&}{ conv = wxConvUTF8}}
+
+Constructs a text stream object associated to the given output stream.

 
 \wxheading{Parameters}
 
 
 \wxheading{Parameters}
 


@@ -121,52 +226,71 @@ be available.
 
 \docparam{mode}{The end-of-line mode. One of {\bf wxEOL\_NATIVE}, {\bf wxEOL\_DOS}, {\bf wxEOL\_MAC} and {\bf wxEOL\_UNIX}.}
 
 
 \docparam{mode}{The end-of-line mode. One of {\bf wxEOL\_NATIVE}, {\bf wxEOL\_DOS}, {\bf wxEOL\_MAC} and {\bf wxEOL\_UNIX}.}
 

-\membersection{wxTextOutputStream::\destruct{wxTextOutputStream}}
+\docparam{conv}{{\it In Unicode build only:} The object used to convert
+Unicode text into ASCII characters written to the output stream.}
+
+
+\membersection{wxTextOutputStream::\destruct{wxTextOutputStream}}\label{wxtextoutputstreamdtor}

 
 \func{}{\destruct{wxTextOutputStream}}{\void}
 
 Destroys the wxTextOutputStream object.
 
 
 \func{}{\destruct{wxTextOutputStream}}{\void}
 
 Destroys the wxTextOutputStream object.
 

-\membersection{wxTextOutputStream::GetMode}

 
 

-\func{wxEOL}{wxTextOutputStream::GetMode}{\void}
+\membersection{wxTextOutputStream::GetMode}\label{wxtextoutputstreamgetmode}
+
+\func{wxEOL}{GetMode}{\void}

 
 Returns the end-of-line mode. One of {\bf wxEOL\_DOS}, {\bf wxEOL\_MAC} and {\bf wxEOL\_UNIX}.
 
 
 Returns the end-of-line mode. One of {\bf wxEOL\_DOS}, {\bf wxEOL\_MAC} and {\bf wxEOL\_UNIX}.
 

-\membersection{wxTextOutputStream::SetMode}

 
 

-\func{void}{wxTextOutputStream::SetMode}{{\param wxEOL}{ mode = wxEOL\_NATIVE}}
+\membersection{wxTextOutputStream::PutChar}\label{wxtextoutputstreamputchar}
+
+\func{void}{PutChar}{{\param wxChar }{c}}
+
+Writes a character to the stream.
+
+
+\membersection{wxTextOutputStream::SetMode}\label{wxtextoutputstreamsetmode}
+
+\func{void}{SetMode}{{\param wxEOL}{ mode = wxEOL\_NATIVE}}

 
 Set the end-of-line mode. One of {\bf wxEOL\_NATIVE}, {\bf wxEOL\_DOS}, {\bf wxEOL\_MAC} and {\bf wxEOL\_UNIX}.
 
 
 Set the end-of-line mode. One of {\bf wxEOL\_NATIVE}, {\bf wxEOL\_DOS}, {\bf wxEOL\_MAC} and {\bf wxEOL\_UNIX}.
 

-\membersection{wxTextOutputStream::Write8}

 
 

-\func{void}{wxTextOutputStream::Write8}{{\param wxUint8 }{i8}}
+\membersection{wxTextOutputStream::Write8}\label{wxtextoutputstreamwrite8}
+
+\func{void}{Write8}{{\param wxUint8 }{i8}}

 
 Writes the single byte {\it i8} to the stream.
 
 
 Writes the single byte {\it i8} to the stream.
 

-\membersection{wxTextOutputStream::Write16}

 
 

-\func{void}{wxTextOutputStream::Write16}{{\param wxUint16 }{i16}}
+\membersection{wxTextOutputStream::Write16}\label{wxtextoutputstreamwrite16}
+
+\func{void}{Write16}{{\param wxUint16 }{i16}}

 
 Writes the 16 bit integer {\it i16} to the stream.
 
 
 Writes the 16 bit integer {\it i16} to the stream.
 

-\membersection{wxTextOutputStream::Write32}

 
 

-\func{void}{wxTextOutputStream::Write32}{{\param wxUint32 }{i32}}
+\membersection{wxTextOutputStream::Write32}\label{wxtextoutputstreamwrite32}
+
+\func{void}{Write32}{{\param wxUint32 }{i32}}

 
 Writes the 32 bit integer {\it i32} to the stream.
 
 
 Writes the 32 bit integer {\it i32} to the stream.
 

-\membersection{wxTextOutputStream::WriteDouble}

 
 

-\func{virtual void}{wxTextOutputStream::WriteDouble}{{\param double }{f}}
+\membersection{wxTextOutputStream::WriteDouble}\label{wxtextoutputstreamwritedouble}
+
+\func{virtual void}{WriteDouble}{{\param double }{f}}

 
 Writes the double {\it f} to the stream using the IEEE format.
 
 
 Writes the double {\it f} to the stream using the IEEE format.
 

-\membersection{wxTextOutputStream::WriteString}

 
 

-\func{virtual void}{wxTextOutputStream::WriteString}{{\param const wxString\& }{string}}
+\membersection{wxTextOutputStream::WriteString}\label{wxtextoutputstreamwritestring}
+
+\func{virtual void}{WriteString}{{\param const wxString\& }{string}}

 
 

-Writes {\it string} as a line. Depending on the end-of-line mode, it adds 
-$\backslash$n, $\backslash$r or $\backslash$r$\backslash$n.
+Writes {\it string} as a line. Depending on the end-of-line mode the end of
+line ('$\backslash$n') characters in the string are converted to the correct
+line ending terminator.