escape underscores introduced by the last change

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

diff --git a/docs/latex/wx/mbconv.tex b/docs/latex/wx/mbconv.tex
index 102186019a803b6a537f75e30b9305f0d127456e..554ccde92e57ed59aced05bd02cfc218273945ea 100644 (file)
--- a/docs/latex/wx/mbconv.tex
+++ b/docs/latex/wx/mbconv.tex
@@ -18,7 +18,7 @@ text strings between multibyte (SBCS or DBCS) encodings and Unicode.
 In the documentation for this and related classes please notice that 
 \emph{length} of the string refers to the number of characters in the string
 not counting the terminating \NUL, if any. While the \emph{size} of the string
 In the documentation for this and related classes please notice that 
 \emph{length} of the string refers to the number of characters in the string
 not counting the terminating \NUL, if any. While the \emph{size} of the string

-is the total number of bytes in the string, including any trailing {\NUL}s.
+is the total number of bytes in the string, including any trailing \NUL.

 Thus, length of wide character string \texttt{L"foo"} is $3$ while its size can
 be either $8$ or $16$ depending on whether \texttt{wchar\_t} is $2$ bytes (as
 under Windows) or $4$ (Unix).
 Thus, length of wide character string \texttt{L"foo"} is $3$ while its size can
 be either $8$ or $16$ depending on whether \texttt{wchar\_t} is $2$ bytes (as
 under Windows) or $4$ (Unix).


@@ -30,10 +30,29 @@ There are several predefined instances of this class:
 \twocolitem{\textbf{wxConvLibc}}{Uses the standard ANSI C \texttt{mbstowcs()} and
 \texttt{wcstombs()} functions to perform the conversions; thus depends on the
 current locale.}
 \twocolitem{\textbf{wxConvLibc}}{Uses the standard ANSI C \texttt{mbstowcs()} and
 \texttt{wcstombs()} functions to perform the conversions; thus depends on the
 current locale.}

+\twocolitem{\textbf{wxConvLocal}}{Another conversion corresponding to the
+current locale but this one uses the best available conversion.}
+\twocolitem{\textbf{wxConvUI}}{The conversion used for hte standard UI elements
+such as menu items and buttons. This is a pointer which is initially set to
+\texttt{wxConvLocal} as the program uses the current locale by default but can
+be set to some specific conversion if the program needs to use a specific
+encoding for its UI.}
+\twocolitem{\textbf{wxConvISO8859\_1}}{Conversion to and from ISO-8859-1 (Latin I)
+encoding.}
+\twocolitem{\textbf{wxConvUTF8}}{Conversion to and from UTF-8 encoding.}

 \twocolitem{\textbf{wxConvFile}}{The appropriate conversion for the file names,
 depends on the system.}
 \twocolitem{\textbf{wxConvFile}}{The appropriate conversion for the file names,
 depends on the system.}

+% \twocolitem{\textbf{wxConvCurrent}}{Not really clear what is it for...}

 \end{twocollist}
 
 \end{twocollist}
 

+
+\wxheading{Constants}
+
+\texttt{wxCONV\_FAILED} value is defined as \texttt{(size\_t)$-1$} and is
+returned by the conversion functions instead of the length of the converted
+string if the conversion fails.
+
+

 \wxheading{Derived from}
 
 No base class
 \wxheading{Derived from}
 
 No base class


@@ -42,12 +61,17 @@ No base class
 
 <wx/strconv.h>
 
 
 <wx/strconv.h>
 

+\wxheading{Library}
+
+\helpref{wxBase}{librarieslist}
+

 \wxheading{See also}
 
 \helpref{wxCSConv}{wxcsconv}, 
 \helpref{wxEncodingConverter}{wxencodingconverter}, 
 \helpref{wxMBConv classes overview}{mbconvclasses}
 
 \wxheading{See also}
 
 \helpref{wxCSConv}{wxcsconv}, 
 \helpref{wxEncodingConverter}{wxencodingconverter}, 
 \helpref{wxMBConv classes overview}{mbconvclasses}
 

+

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


@@ -55,12 +79,24 @@ No base class
 
 \func{}{wxMBConv}{\void}
 
 
 \func{}{wxMBConv}{\void}
 

-Constructor.
+Trivial default constructor.
+
+
+\membersection{wxMBConv::Clone}\label{wxmbconvclone}
+
+\constfunc{virtual wxMBConv *}{Clone}{\void}
+
+This pure virtual function is overridden in each of the derived classes to
+return a new copy of the object it is called on. It is used for copying the
+conversion objects while preserving their dynamic type.
+

 
 \membersection{wxMBConv::MB2WC}\label{wxmbconvmb2wc}
 
 \constfunc{virtual size\_t}{MB2WC}{\param{wchar\_t *}{out}, \param{const char *}{in}, \param{size\_t }{outLen}}
 
 
 \membersection{wxMBConv::MB2WC}\label{wxmbconvmb2wc}
 
 \constfunc{virtual size\_t}{MB2WC}{\param{wchar\_t *}{out}, \param{const char *}{in}, \param{size\_t }{outLen}}
 

+\deprecated{\helpref{ToWChar}{wxmbconvtowchar}}
+

 Converts from a string \arg{in} in multibyte encoding to Unicode putting up to 
 \arg{outLen} characters into the buffer \arg{out}.
 
 Converts from a string \arg{in} in multibyte encoding to Unicode putting up to 
 \arg{outLen} characters into the buffer \arg{out}.
 


@@ -82,20 +118,22 @@ interested in the length of the resulting string}
 
 \wxheading{Return value}
 
 
 \wxheading{Return value}
 

-The length of the converted string \emph{excluding} the trailing {\NUL}.
+The length of the converted string \emph{excluding} the trailing \NUL.

 
 
 \membersection{wxMBConv::WC2MB}\label{wxmbconvwc2mb}
 
 \constfunc{virtual size\_t}{WC2MB}{\param{char* }{buf}, \param{const wchar\_t* }{psz}, \param{size\_t }{n}}
 
 
 
 \membersection{wxMBConv::WC2MB}\label{wxmbconvwc2mb}
 
 \constfunc{virtual size\_t}{WC2MB}{\param{char* }{buf}, \param{const wchar\_t* }{psz}, \param{size\_t }{n}}
 

+\deprecated{\helpref{FromWChar}{wxmbconvfromwchar}}
+

 Converts from Unicode to multibyte encoding. The semantics of this function
 (including the return value meaning) is the same as for 
 \helpref{MB2WC}{wxmbconvmb2wc}.
 
 Notice that when the function is called with a non-\NULL buffer, the 
 {\it n} parameter should be the size of the buffer and so it \emph{should} take
 Converts from Unicode to multibyte encoding. The semantics of this function
 (including the return value meaning) is the same as for 
 \helpref{MB2WC}{wxmbconvmb2wc}.
 
 Notice that when the function is called with a non-\NULL buffer, the 
 {\it n} parameter should be the size of the buffer and so it \emph{should} take

-into account the trailing NUL, which might take two or four bytes for some
+into account the trailing \NUL, which might take two or four bytes for some

 encodings (UTF-16 and UTF-32) and not one.
 
 
 encodings (UTF-16 and UTF-32) and not one.
 
 


@@ -111,11 +149,12 @@ the result.
 
 The first overload takes a \NUL-terminated input string. The second one takes a
 string of exactly the specified length and the string may include or not the
 
 The first overload takes a \NUL-terminated input string. The second one takes a
 string of exactly the specified length and the string may include or not the

-trailing {\NUL}s. If the string is not \NUL-terminated, a temporary 
+trailing \NUL character(s). If the string is not \NUL-terminated, a temporary 

 \NUL-terminated copy of it suitable for passing to \helpref{MB2WC}{wxmbconvmb2wc} 
 is made, so it is more efficient to ensure that the string is does have the
 appropriate number of \NUL bytes (which is usually $1$ but may be $2$ or $4$
 \NUL-terminated copy of it suitable for passing to \helpref{MB2WC}{wxmbconvmb2wc} 
 is made, so it is more efficient to ensure that the string is does have the
 appropriate number of \NUL bytes (which is usually $1$ but may be $2$ or $4$

-for UTF-16 or UTF-32), especially for long strings.
+for UTF-16 or UTF-32, see \helpref{GetMBNulLen}{wxmbconvgetmbnullen}),
+especially for long strings.

 
 If \arg{outLen} is not-\NULL, it receives the length of the converted
 string.
 
 If \arg{outLen} is not-\NULL, it receives the length of the converted
 string.


@@ -189,3 +228,62 @@ it returns the parameter unaltered. If wxChar is char, it returns the
 result in a wxWCharBuffer. The macro wxWX2WCbuf is defined as the correct
 return type (without const).
 
 result in a wxWCharBuffer. The macro wxWX2WCbuf is defined as the correct
 return type (without const).
 

+
+\membersection{wxMBConv::FromWChar}\label{wxmbconvfromwchar}
+
+\constfunc{virtual size\_t}{FromWChar}{\param{char\_t *}{dst}, \param{size\_t }{dstLen}, \param{const wchar\_t *}{src}, \param{size\_t }{srcLen = wxNO\_LEN}}
+
+This function has the same semantics as \helpref{ToWChar}{wxmbconvtowchar} 
+except that it converts a wide string to multibyte one.
+
+\membersection{wxMBConv::GetMaxMBNulLen}\label{wxmbconvgetmaxmbnullen}
+
+\func{const size\_t}{GetMaxMBNulLen}{\void}
+
+Returns the maximal value which can be returned by 
+\helpref{GetMBNulLen}{wxmbconvgetmbnullen} for any conversion object. Currently
+this value is $4$.
+
+This method can be used to allocate the buffer with enough space for the
+trailing \NUL characters for any encoding.
+
+
+\membersection{wxMBConv::GetMBNulLen}\label{wxmbconvgetmbnullen}
+
+\constfunc{size\_t}{GetMBNulLen}{\void}
+
+This function returns $1$ for most of the multibyte encodings in which the
+string is terminated by a single \NUL, $2$ for UTF-16 and $4$ for UTF-32 for
+which the string is terminated with $2$ and $4$ \NUL characters respectively.
+The other cases are not currently supported and \texttt{wxCONV\_FAILED} 
+(defined as $-1$) is returned for them.
+
+
+\membersection{wxMBConv::ToWChar}\label{wxmbconvtowchar}
+
+\constfunc{virtual size\_t}{ToWChar}{\param{wchar\_t *}{dst}, \param{size\_t }{dstLen}, \param{const char *}{src}, \param{size\_t }{srcLen = wxNO\_LEN}}
+
+The most general function for converting a multibyte string to a wide string.
+The main case is when \arg{dst} is not \NULL and \arg{srcLen} is not 
+\texttt{wxNO\_LEN} (which is defined as \texttt{(size\_t)$-1$}): then
+the function converts exactly \arg{srcLen} bytes starting at \arg{src} into
+wide string which it output to \arg{dst}. If the length of the resulting wide
+string is greater than \arg{dstLen}, an error is returned. Note that if 
+\arg{srcLen} bytes don't include \NUL characters, the resulting wide string is
+not \NUL-terminated neither.
+
+If \arg{srcLen} is \texttt{wxNO\_LEN}, the function supposes that the string is
+properly (i.e. as necessary for the encoding handled by this conversion) 
+\NUL-terminated and converts the entire string, including any trailing \NUL 
+bytes. In this case the wide string is also \NUL-terminated.
+
+Finally, if \arg{dst} is \NULL, the function returns the length of the needed
+buffer.
+
+\wxheading{Return value}
+
+The number of characters written to \arg{dst} (or the number of characters
+which would have been written to it if it were non-\NULL) on success or 
+\texttt{wxCONV\_FAILED} on error.
+
+