Some doc corrections

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

diff --git a/docs/latex/wx/encconv.tex b/docs/latex/wx/encconv.tex
index 4287f63054c78931b164686914ffad12e2e28d01..0548703ba1eb44ede11206c4284c32b5d12e3677 100644 (file)
--- a/docs/latex/wx/encconv.tex
+++ b/docs/latex/wx/encconv.tex
@@ -5,27 +5,51 @@
 
 \section{\class{wxEncodingConverter}}\label{wxencodingconverter}
 
 
 \section{\class{wxEncodingConverter}}\label{wxencodingconverter}
 

-This class is capable of converting strings between any two
+This class is capable of converting strings between two

 8-bit encodings/charsets. It can also convert from/to Unicode (but only
 8-bit encodings/charsets. It can also convert from/to Unicode (but only

-if you compiled wxWindows with wxUSE_UNICODE set to 1).
+if you compiled wxWindows with wxUSE\_WCHAR\_T set to 1). Only limited subset
+of encodings in supported by wxEncodingConverter:
+{\tt wxFONTENCODING\_ISO8859\_1..15}, {\tt wxFONTENCODING\_CP1250..1257} and 
+{\tt wxFONTENCODING\_KOI8}.
+
+\wxheading{Note}
+
+Please use \helpref{wxMBConv classes}{mbconvclasses} instead
+if possible. \helpref{wxCSConv}{wxcsconv} has much better support for various
+encodings than wxEncodingConverter. wxEncodingConverter is useful only
+if you rely on {\tt wxCONVERT\_SUBSTITUTE} mode of operation (see 
+\helpref{Init}{wxencodingconverterinit}).

 
 \wxheading{Derived from}
 
 \helpref{wxObject}{wxobject}
 
 
 \wxheading{Derived from}
 
 \helpref{wxObject}{wxobject}
 

+\wxheading{Include files}
+
+<wx/encconv.h>
+
+\wxheading{See also}
+
+\helpref{wxFontMapper}{wxfontmapper}, 
+\helpref{wxMBConv}{wxmbconv}, 
+\helpref{Writing non-English applications}{nonenglishoverview}
+
+

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

+

 \membersection{wxEncodingConverter::wxEncodingConverter}\label{wxencodingconverterwxencodingconverter}
 
 \func{}{wxEncodingConverter}{\void}
 
 Constructor.
 
 \membersection{wxEncodingConverter::wxEncodingConverter}\label{wxencodingconverterwxencodingconverter}
 
 \func{}{wxEncodingConverter}{\void}
 
 Constructor.
 

+

 \membersection{wxEncodingConverter::Init}\label{wxencodingconverterinit}
 
 \func{bool}{Init}{\param{wxFontEncoding }{input\_enc}, \param{wxFontEncoding }{output\_enc}, \param{int }{method = wxCONVERT\_STRICT}}
 
 \membersection{wxEncodingConverter::Init}\label{wxencodingconverterinit}
 
 \func{bool}{Init}{\param{wxFontEncoding }{input\_enc}, \param{wxFontEncoding }{output\_enc}, \param{int }{method = wxCONVERT\_STRICT}}
 

-Initialize convertion. Both output or input encoding may
+Initialize conversion. Both output or input encoding may

 be wxFONTENCODING\_UNICODE, but only if wxUSE\_ENCODING is set to 1.
 All subsequent calls to \helpref{Convert()}{wxencodingconverterconvert} 
 will interpret its argument
 be wxFONTENCODING\_UNICODE, but only if wxUSE\_ENCODING is set to 1.
 All subsequent calls to \helpref{Convert()}{wxencodingconverterconvert} 
 will interpret its argument


@@ -38,35 +62,68 @@ cannot be converted because it does not exist in output encoding:
 
 \begin{twocollist}\itemsep=0pt
 \twocolitem{{\bf wxCONVERT\_STRICT}}{follow behaviour of GNU Recode -
 
 \begin{twocollist}\itemsep=0pt
 \twocolitem{{\bf wxCONVERT\_STRICT}}{follow behaviour of GNU Recode -

-just copy unconvertable  characters to output and don't change them 
+just copy unconvertible  characters to output and don't change them 

 (its integer value will stay the same)}
 \twocolitem{{\bf wxCONVERT\_SUBSTITUTE}}{try some (lossy) substitutions 
 (its integer value will stay the same)}
 \twocolitem{{\bf wxCONVERT\_SUBSTITUTE}}{try some (lossy) substitutions 

-- e.g. replace unconvertable latin capitals with acute by ordinary
+- e.g. replace unconvertible latin capitals with acute by ordinary

 capitals, replace en-dash or em-dash by '-' etc.}
 \end{twocollist}
 
 capitals, replace en-dash or em-dash by '-' etc.}
 \end{twocollist}
 

-Both modes gurantee that output string will have same length
+Both modes guarantee that output string will have same length

 as input string.
 
 \wxheading{Return value} 
 
 as input string.
 
 \wxheading{Return value} 
 

-FALSE if given conversion is impossible, TRUE otherwise
+false if given conversion is impossible, true otherwise

 (conversion may be impossible either if you try to convert
 to Unicode with non-Unicode build of wxWindows or if input
 or output encoding is not supported.)
 
 (conversion may be impossible either if you try to convert
 to Unicode with non-Unicode build of wxWindows or if input
 or output encoding is not supported.)
 

+
+\membersection{wxEncodingConverter::CanConvert}\label{wxencodingconvertercanconvert}
+
+\func{static bool}{CanConvert}{\param{wxFontEncoding}{encIn}, \param{wxFontEncoding }{encOut}}
+
+Return true if (any text in) multibyte encoding \arg{encIn} can be converted to
+another one (\it{encOut}) losslessly.
+
+Do not call this method with \texttt{wxFONTENCODING\_UNICODE} as either
+parameter, it doesn't make sense (always works in one sense and always depends
+on the text to convert in the other).
+
+

 \membersection{wxEncodingConverter::Convert}\label{wxencodingconverterconvert}
 
 \membersection{wxEncodingConverter::Convert}\label{wxencodingconverterconvert}
 

-\func{wxString}{Convert}{\param{const wxString\& }{input}}
+\constfunc{void}{Convert}{\param{const char* }{input}, \param{char* }{output}}
+
+\constfunc{void}{Convert}{\param{const wchar\_t* }{input}, \param{wchar\_t* }{output}}
+
+\constfunc{void}{Convert}{\param{const char* }{input}, \param{wchar\_t* }{output}}
+
+\constfunc{void}{Convert}{\param{const wchar\_t* }{input}, \param{char* }{output}}
+
+Convert input string according to settings passed to
+\helpref{Init}{wxencodingconverterinit} and writes the result to {\it output}.
+
+\constfunc{void}{Convert}{\param{char* }{str}}

 
 

-\func{void}{Convert}{\param{const wxChar* }{input}, \param{wxChar* }{output}}
+\constfunc{void}{Convert}{\param{wchar\_t* }{str}}

 
 

-\func{void}{Convert}{\param{wxChar* }{str}}
+Convert input string according to settings passed to
+\helpref{Init}{wxencodingconverterinit} in-place, i.e. write the result to the
+same memory area.

 
 

-\func{void}{Convert}{\param{const char* }{input}, \param{wxChar* }{output}}
+\constfunc{wxString}{Convert}{\param{const wxString\& }{input}}
+
+Convert wxString and return new wxString object.
+
+\wxheading{Notes}
+
+You must call \helpref{Init}{wxencodingconverterinit} before using this method!
+
+{\tt wchar\_t} versions of the method are not available if wxWindows was compiled
+with {\tt wxUSE\_WCHAR\_T} set to 0.

 
 

-Convert input string according to settings passed to \helpref{Init}{wxencodingconverterinit}.
-Note that you must call Init before using Convert!

 
 \membersection{wxEncodingConverter::GetPlatformEquivalents}\label{wxencodingconvertergetplatformequivalents}
 
 
 \membersection{wxEncodingConverter::GetPlatformEquivalents}\label{wxencodingconvertergetplatformequivalents}
 


@@ -83,7 +140,7 @@ under given platform. Supported platforms:
 \item wxPLATFORM\_CURRENT
 \end{itemize}
 
 \item wxPLATFORM\_CURRENT
 \end{itemize}
 

-wxPLATFORM\_CURRENT means the plaform this binary was compiled for.
+wxPLATFORM\_CURRENT means the platform this binary was compiled for.

 
 Examples:
 
 
 Examples:
 


@@ -97,10 +154,10 @@ unix            CP1252  {ISO8859_1,ISO8859_15}
 \end{verbatim}
 
 Equivalence is defined in terms of convertibility:
 \end{verbatim}
 
 Equivalence is defined in terms of convertibility:

-2 encodings are equivalent if you can convert text between
-then without loosing information (it may - and will - happen
-that you loose special chars like quotation marks or em-dashes
-but you shouldn't loose any diacritics and language-specific
+two encodings are equivalent if you can convert text between
+then without losing information (it may - and will - happen
+that you lose special chars like quotation marks or em-dashes
+but you shouldn't lose any diacritics and language-specific

 characters when converting between equivalent encodings).
 
 Remember that this function does {\bf NOT} check for presence of
 characters when converting between equivalent encodings).
 
 Remember that this function does {\bf NOT} check for presence of


@@ -111,16 +168,17 @@ encodings. (It usually returns only one encoding.)
 
 \begin{itemize}\itemsep=0pt
 \item Note that argument {\it enc} itself may be present in the returned array,
 
 \begin{itemize}\itemsep=0pt
 \item Note that argument {\it enc} itself may be present in the returned array,

-so that you can - as a side effect - detect whether the
+so that you can, as a side-effect, detect whether the

 encoding is native for this platform or not.
 encoding is native for this platform or not.

-\item helpref{Convert}{wxencodingconverterconvert} is not limited to 
-converting between equivalent encodings, it can convert between arbitrary
-two encodings.
-\item If {\it enc} is present in returned array, then it is {\bf always} first
+\item \helpref{Convert}{wxencodingconverterconvert} is not limited to 
+converting between equivalent encodings, it can convert between two arbitrary
+encodings.
+\item If {\it enc} is present in the returned array, then it is {\bf always} the first

 item of it.
 item of it.

-\item Please note that the returned array may not contain any items at all.
+\item Please note that the returned array may contain no items at all.

 \end{itemize}
 
 \end{itemize}
 

+

 \membersection{wxEncodingConverter::GetAllEquivalents}\label{wxencodingconvertergetallequivalents}
 
 \func{static wxFontEncodingArray}{GetAllEquivalents}{\param{wxFontEncoding }{enc}}
 \membersection{wxEncodingConverter::GetAllEquivalents}\label{wxencodingconvertergetallequivalents}
 
 \func{static wxFontEncodingArray}{GetAllEquivalents}{\param{wxFontEncoding }{enc}}


@@ -128,7 +186,7 @@ item of it.
 Similar to 
 \helpref{GetPlatformEquivalents}{wxencodingconvertergetplatformequivalents}, 
 but this one will return ALL 
 Similar to 
 \helpref{GetPlatformEquivalents}{wxencodingconvertergetplatformequivalents}, 
 but this one will return ALL 

-equivalent encodings, regardless the platform, and including itself.
+equivalent encodings, regardless of the platform, and including itself.

 
 This platform's encodings are before others in the array. And again, if {\it enc} is in the array,
 it is the very first item in it.
 
 This platform's encodings are before others in the array. And again, if {\it enc} is in the array,
 it is the very first item in it.