Removed OGL prior to re-adding; some Watcom corrections

[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 any two
8-bit encodings/charsets. It can also convert from/to Unicode (but only
if you compiled wxWindows with wxUSE\_UNICODE set to 1).

\wxheading{Derived from}

\helpref{wxObject}{wxobject}

\wxheading{Include files}

<wx/encconv.h>

\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 convertion. 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 unconvertable  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 unconvertable latin capitals with acute by ordinary
capitals, replace en-dash or em-dash by '-' etc.}
\end{twocollist}

Both modes gurantee 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 wxWindows or if input
or output encoding is not supported.)

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

\func{wxString}{Convert}{\param{const wxString\& }{input}}

\func{void}{Convert}{\param{const wxChar* }{input}, \param{wxChar* }{output}}

\func{void}{Convert}{\param{wxChar* }{str}}

\func{void}{Convert}{\param{const char* }{input}, \param{wxChar* }{output}}

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}

\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 plaform 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:
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
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 arbitrary
two encodings.
\item If {\it enc} is present in returned array, then it is {\bf always} first
item of it.
\item Please note that the returned array may not contain any 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 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.