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