1% 2% automatically generated by HelpGen from 3% encconv.h at 30/Dec/99 18:45:16 4% 5 6\section{\class{wxEncodingConverter}}\label{wxencodingconverter} 7 8This class is capable of converting strings between two 98-bit encodings/charsets. It can also convert from/to Unicode (but only 10if you compiled wxWidgets with wxUSE\_WCHAR\_T set to 1). Only a limited subset 11of encodings is supported by wxEncodingConverter: 12{\tt wxFONTENCODING\_ISO8859\_1..15}, {\tt wxFONTENCODING\_CP1250..1257} and 13{\tt wxFONTENCODING\_KOI8}. 14 15\wxheading{Note} 16 17Please use \helpref{wxMBConv classes}{mbconvclasses} instead 18if possible. \helpref{wxCSConv}{wxcsconv} has much better support for various 19encodings than wxEncodingConverter. wxEncodingConverter is useful only 20if you rely on {\tt wxCONVERT\_SUBSTITUTE} mode of operation (see 21\helpref{Init}{wxencodingconverterinit}). 22 23\wxheading{Derived from} 24 25\helpref{wxObject}{wxobject} 26 27\wxheading{Include files} 28 29<wx/encconv.h> 30 31\wxheading{See also} 32 33\helpref{wxFontMapper}{wxfontmapper}, 34\helpref{wxMBConv}{wxmbconv}, 35\helpref{Writing non-English applications}{nonenglishoverview} 36 37 38\latexignore{\rtfignore{\wxheading{Members}}} 39 40 41\membersection{wxEncodingConverter::wxEncodingConverter}\label{wxencodingconverterwxencodingconverter} 42 43\func{}{wxEncodingConverter}{\void} 44 45Constructor. 46 47 48\membersection{wxEncodingConverter::Init}\label{wxencodingconverterinit} 49 50\func{bool}{Init}{\param{wxFontEncoding }{input\_enc}, \param{wxFontEncoding }{output\_enc}, \param{int }{method = wxCONVERT\_STRICT}} 51 52Initialize conversion. Both output or input encoding may 53be wxFONTENCODING\_UNICODE, but only if wxUSE\_ENCODING is set to 1. 54All subsequent calls to \helpref{Convert()}{wxencodingconverterconvert} 55will interpret its argument 56as a string in {\it input\_enc} encoding and will output string in 57{\it output\_enc} encoding. 58You must call this method before calling Convert. You may call 59it more than once in order to switch to another conversion. 60{\it Method} affects behaviour of Convert() in case input character 61cannot be converted because it does not exist in output encoding: 62 63\begin{twocollist}\itemsep=0pt 64\twocolitem{{\bf wxCONVERT\_STRICT}}{follow behaviour of GNU Recode - 65just copy unconvertible characters to output and don't change them 66(its integer value will stay the same)} 67\twocolitem{{\bf wxCONVERT\_SUBSTITUTE}}{try some (lossy) substitutions 68- e.g. replace unconvertible latin capitals with acute by ordinary 69capitals, replace en-dash or em-dash by '-' etc.} 70\end{twocollist} 71 72Both modes guarantee that output string will have same length 73as input string. 74 75\wxheading{Return value} 76 77false if given conversion is impossible, true otherwise 78(conversion may be impossible either if you try to convert 79to Unicode with non-Unicode build of wxWidgets or if input 80or output encoding is not supported.) 81 82 83\membersection{wxEncodingConverter::CanConvert}\label{wxencodingconvertercanconvert} 84 85\func{static bool}{CanConvert}{\param{wxFontEncoding }{encIn}, \param{wxFontEncoding }{encOut}} 86 87Return true if (any text in) multibyte encoding \arg{encIn} can be converted to 88another one ({\it encOut}) losslessly. 89 90Do not call this method with \texttt{wxFONTENCODING\_UNICODE} as either 91parameter, it doesn't make sense (always works in one sense and always depends 92on the text to convert in the other). 93 94 95\membersection{wxEncodingConverter::Convert}\label{wxencodingconverterconvert} 96 97\constfunc{bool}{Convert}{\param{const char* }{input}, \param{char* }{output}} 98 99\constfunc{bool}{Convert}{\param{const wchar\_t* }{input}, \param{wchar\_t* }{output}} 100 101\constfunc{bool}{Convert}{\param{const char* }{input}, \param{wchar\_t* }{output}} 102 103\constfunc{bool}{Convert}{\param{const wchar\_t* }{input}, \param{char* }{output}} 104 105Convert input string according to settings passed to 106\helpref{Init}{wxencodingconverterinit} and writes the result to {\it output}. 107 108\constfunc{bool}{Convert}{\param{char* }{str}} 109 110\constfunc{bool}{Convert}{\param{wchar\_t* }{str}} 111 112Convert input string according to settings passed to 113\helpref{Init}{wxencodingconverterinit} in-place, i.e. write the result to the 114same memory area. 115 116All of the versions above return \true if the conversion was lossless and 117\false if at least one of the characters couldn't be converted and was replaced 118with {\tt '?'} in the output. Note that if {\tt wxCONVERT\_SUBSTITUTE} was 119passed to \helpref{Init}{wxencodingconverterinit}, substitution is considered 120lossless operation. 121 122\constfunc{wxString}{Convert}{\param{const wxString\& }{input}} 123 124Convert wxString and return new wxString object. 125 126\wxheading{Notes} 127 128You must call \helpref{Init}{wxencodingconverterinit} before using this method! 129 130{\tt wchar\_t} versions of the method are not available if wxWidgets was compiled 131with {\tt wxUSE\_WCHAR\_T} set to 0. 132 133 134\membersection{wxEncodingConverter::GetPlatformEquivalents}\label{wxencodingconvertergetplatformequivalents} 135 136\func{static wxFontEncodingArray}{GetPlatformEquivalents}{\param{wxFontEncoding }{enc}, \param{int }{platform = wxPLATFORM\_CURRENT}} 137 138Return equivalents for given font that are used 139under given platform. Supported platforms: 140 141\begin{itemize}\itemsep=0pt 142\item wxPLATFORM\_UNIX 143\item wxPLATFORM\_WINDOWS 144\item wxPLATFORM\_OS2 145\item wxPLATFORM\_MAC 146\item wxPLATFORM\_CURRENT 147\end{itemize} 148 149wxPLATFORM\_CURRENT means the platform this binary was compiled for. 150 151Examples: 152 153\begin{verbatim} 154current platform enc returned value 155---------------------------------------------- 156unix CP1250 {ISO8859_2} 157unix ISO8859_2 {ISO8859_2} 158windows ISO8859_2 {CP1250} 159unix CP1252 {ISO8859_1,ISO8859_15} 160\end{verbatim} 161 162Equivalence is defined in terms of convertibility: 163two encodings are equivalent if you can convert text between 164then without losing information (it may - and will - happen 165that you lose special chars like quotation marks or em-dashes 166but you shouldn't lose any diacritics and language-specific 167characters when converting between equivalent encodings). 168 169Remember that this function does {\bf NOT} check for presence of 170fonts in system. It only tells you what are most suitable 171encodings. (It usually returns only one encoding.) 172 173\wxheading{Notes} 174 175\begin{itemize}\itemsep=0pt 176\item Note that argument {\it enc} itself may be present in the returned array, 177so that you can, as a side-effect, detect whether the 178encoding is native for this platform or not. 179\item \helpref{Convert}{wxencodingconverterconvert} is not limited to 180converting between equivalent encodings, it can convert between two arbitrary 181encodings. 182\item If {\it enc} is present in the returned array, then it is {\bf always} the first 183item of it. 184\item Please note that the returned array may contain no items at all. 185\end{itemize} 186 187 188\membersection{wxEncodingConverter::GetAllEquivalents}\label{wxencodingconvertergetallequivalents} 189 190\func{static wxFontEncodingArray}{GetAllEquivalents}{\param{wxFontEncoding }{enc}} 191 192Similar to 193\helpref{GetPlatformEquivalents}{wxencodingconvertergetplatformequivalents}, 194but this one will return ALL 195equivalent encodings, regardless of the platform, and including itself. 196 197This platform's encodings are before others in the array. And again, if {\it enc} is in the array, 198it is the very first item in it. 199 200