docs/latex/wx/encconv.tex

   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
   8 This class is capable of converting strings between two
   9 8-bit encodings/charsets. It can also convert from/to Unicode (but only
  10 if you compiled wxWidgets with wxUSE\_WCHAR\_T set to 1). Only a limited subset
  11 of 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
  17 Please use \helpref{wxMBConv classes}{mbconvclasses} instead
  18 if possible. \helpref{wxCSConv}{wxcsconv} has much better support for various
  19 encodings than wxEncodingConverter. wxEncodingConverter is useful only
  20 if 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
  45 Constructor.
  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
  52 Initialize conversion. Both output or input encoding may
  53 be wxFONTENCODING\_UNICODE, but only if wxUSE\_ENCODING is set to 1.
  54 All subsequent calls to \helpref{Convert()}{wxencodingconverterconvert}
  55 will interpret its argument
  56 as a string in {\it input\_enc} encoding and will output string in
  57 {\it output\_enc} encoding.
  58 You must call this method before calling Convert. You may call
  59 it more than once in order to switch to another conversion.
  60 {\it Method} affects behaviour of Convert() in case input character
  61 cannot 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 -
  65 just 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
  69 capitals, replace en-dash or em-dash by '-' etc.}
  70 \end{twocollist}
  71
  72 Both modes guarantee that output string will have same length
  73 as input string.
  74
  75 \wxheading{Return value}
  76
  77 false if given conversion is impossible, true otherwise
  78 (conversion may be impossible either if you try to convert
  79 to Unicode with non-Unicode build of wxWidgets or if input
  80 or 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
  87 Return true if (any text in) multibyte encoding \arg{encIn} can be converted to
  88 another one ({\it encOut}) losslessly.
  89
  90 Do not call this method with \texttt{wxFONTENCODING\_UNICODE} as either
  91 parameter, it doesn't make sense (always works in one sense and always depends
  92 on 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
 105 Convert 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
 112 Convert input string according to settings passed to
 113 \helpref{Init}{wxencodingconverterinit} in-place, i.e. write the result to the
 114 same memory area.
 115
 116 All 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
 118 with {\tt '?'} in the output. Note that if {\tt wxCONVERT\_SUBSTITUTE} was
 119 passed to \helpref{Init}{wxencodingconverterinit}, substitution is considered
 120 lossless operation.
 121
 122 \constfunc{wxString}{Convert}{\param{const wxString\& }{input}}
 123
 124 Convert wxString and return new wxString object.
 125
 126 \wxheading{Notes}
 127
 128 You 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
 131 with {\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
 138 Return equivalents for given font that are used
 139 under 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
 149 wxPLATFORM\_CURRENT means the platform this binary was compiled for.
 150
 151 Examples:
 152
 153 \begin{verbatim}
 154 current platform   enc          returned value
 155 ----------------------------------------------
 156 unix            CP1250             {ISO8859_2}
 157 unix         ISO8859_2             {ISO8859_2}
 158 windows      ISO8859_2                {CP1250}
 159 unix            CP1252  {ISO8859_1,ISO8859_15}
 160 \end{verbatim}
 161
 162 Equivalence is defined in terms of convertibility:
 163 two encodings are equivalent if you can convert text between
 164 then without losing information (it may - and will - happen
 165 that you lose special chars like quotation marks or em-dashes
 166 but you shouldn't lose any diacritics and language-specific
 167 characters when converting between equivalent encodings).
 168
 169 Remember that this function does {\bf NOT} check for presence of
 170 fonts in system. It only tells you what are most suitable
 171 encodings. (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,
 177 so that you can, as a side-effect, detect whether the
 178 encoding is native for this platform or not.
 179 \item \helpref{Convert}{wxencodingconverterconvert} is not limited to
 180 converting between equivalent encodings, it can convert between two arbitrary
 181 encodings.
 182 \item If {\it enc} is present in the returned array, then it is {\bf always} the first
 183 item 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
 192 Similar to
 193 \helpref{GetPlatformEquivalents}{wxencodingconvertergetplatformequivalents},
 194 but this one will return ALL
 195 equivalent encodings, regardless of the platform, and including itself.
 196
 197 This platform's encodings are before others in the array. And again, if {\it enc} is in the array,
 198 it is the very first item in it.
 199