Described in the comments and documented the semantics of the parameters and

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

%
% automatically generated by HelpGen from
% encconv.h at 30/Dec/99 18:45:16
%

\section{\class{wxEncodingConverter}}\label{wxencodingconverter}

This class is capable of converting strings between two
8-bit encodings/charsets. It can also convert from/to Unicode (but only
if you compiled wxWidgets with wxUSE\_WCHAR\_T set to 1). Only a limited subset
of encodings is 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{Include files}

<wx/encconv.h>

\wxheading{See also}

\helpref{wxFontMapper}{wxfontmapper}, 
\helpref{wxMBConv}{wxmbconv}, 
\helpref{Writing non-English applications}{nonenglishoverview}


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


\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}}

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
as a string in {\it input\_enc} encoding and will output string in 
{\it output\_enc} encoding.
You must call this method before calling Convert. You may call 
it more than once in order to switch to another conversion.
{\it Method} affects behaviour of Convert() in case input character
cannot be converted because it does not exist in output encoding:

\begin{twocollist}\itemsep=0pt
\twocolitem{{\bf wxCONVERT\_STRICT}}{follow behaviour of GNU Recode -
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 
- e.g. replace unconvertible latin capitals with acute by ordinary
capitals, replace en-dash or em-dash by '-' etc.}
\end{twocollist}

Both modes guarantee that output string will have same length
as input string.

\wxheading{Return value} 

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 wxWidgets 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}

\constfunc{bool}{Convert}{\param{const char* }{input}, \param{char* }{output}}

\constfunc{bool}{Convert}{\param{const wchar\_t* }{input}, \param{wchar\_t* }{output}}

\constfunc{bool}{Convert}{\param{const char* }{input}, \param{wchar\_t* }{output}}

\constfunc{bool}{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{bool}{Convert}{\param{char* }{str}}

\constfunc{bool}{Convert}{\param{wchar\_t* }{str}}

Convert input string according to settings passed to
\helpref{Init}{wxencodingconverterinit} in-place, i.e. write the result to the
same memory area.

All of the versions above return \true if the conversion was lossless and
\false if at least one of the characters couldn't be converted and was replaced
with {\tt '?'} in the output. Note that if {\tt wxCONVERT\_SUBSTITUTE} was
passed to \helpref{Init}{wxencodingconverterinit}, substitution is considered
lossless operation.

\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 wxWidgets was compiled
with {\tt wxUSE\_WCHAR\_T} set to 0.


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

\func{static wxFontEncodingArray}{GetPlatformEquivalents}{\param{wxFontEncoding }{enc}, \param{int }{platform = wxPLATFORM\_CURRENT}}

Return equivalents for given font that are used
under given platform. Supported platforms:

\begin{itemize}\itemsep=0pt
\item wxPLATFORM\_UNIX
\item wxPLATFORM\_WINDOWS
\item wxPLATFORM\_OS2
\item wxPLATFORM\_MAC
\item wxPLATFORM\_CURRENT
\end{itemize}

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

Examples:

\begin{verbatim}
current platform   enc          returned value
----------------------------------------------
unix            CP1250             {ISO8859_2}
unix         ISO8859_2             {ISO8859_2}
windows      ISO8859_2                {CP1250}
unix            CP1252  {ISO8859_1,ISO8859_15}
\end{verbatim}

Equivalence is defined in terms of convertibility:
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
fonts in system. It only tells you what are most suitable
encodings. (It usually returns only one encoding.)

\wxheading{Notes}

\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
encoding is native for this platform or not.
\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 Please note that the returned array may contain no items at all.
\end{itemize}


\membersection{wxEncodingConverter::GetAllEquivalents}\label{wxencodingconvertergetallequivalents}

\func{static wxFontEncodingArray}{GetAllEquivalents}{\param{wxFontEncoding }{enc}}

Similar to 
\helpref{GetPlatformEquivalents}{wxencodingconvertergetplatformequivalents}, 
but this one will return ALL 
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.