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 limited subset
  11 of encodings in 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{void}{Convert}{\param{const char* }{input}, \param{char* }{output}}
  98
  99 \constfunc{void}{Convert}{\param{const wchar\_t* }{input}, \param{wchar\_t* }{output}}
 100
 101 \constfunc{void}{Convert}{\param{const char* }{input}, \param{wchar\_t* }{output}}
 102
 103 \constfunc{void}{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{void}{Convert}{\param{char* }{str}}
 109
 110 \constfunc{void}{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 \constfunc{wxString}{Convert}{\param{const wxString\& }{input}}
 117
 118 Convert wxString and return new wxString object.
 119
 120 \wxheading{Notes}
 121
 122 You must call \helpref{Init}{wxencodingconverterinit} before using this method!
 123
 124 {\tt wchar\_t} versions of the method are not available if wxWidgets was compiled
 125 with {\tt wxUSE\_WCHAR\_T} set to 0.
 126
 127
 128 \membersection{wxEncodingConverter::GetPlatformEquivalents}\label{wxencodingconvertergetplatformequivalents}
 129
 130 \func{static wxFontEncodingArray}{GetPlatformEquivalents}{\param{wxFontEncoding }{enc}, \param{int }{platform = wxPLATFORM\_CURRENT}}
 131
 132 Return equivalents for given font that are used
 133 under given platform. Supported platforms:
 134
 135 \begin{itemize}\itemsep=0pt
 136 \item wxPLATFORM\_UNIX
 137 \item wxPLATFORM\_WINDOWS
 138 \item wxPLATFORM\_OS2
 139 \item wxPLATFORM\_MAC
 140 \item wxPLATFORM\_CURRENT
 141 \end{itemize}
 142
 143 wxPLATFORM\_CURRENT means the platform this binary was compiled for.
 144
 145 Examples:
 146
 147 \begin{verbatim}
 148 current platform   enc          returned value
 149 ----------------------------------------------
 150 unix            CP1250             {ISO8859_2}
 151 unix         ISO8859_2             {ISO8859_2}
 152 windows      ISO8859_2                {CP1250}
 153 unix            CP1252  {ISO8859_1,ISO8859_15}
 154 \end{verbatim}
 155
 156 Equivalence is defined in terms of convertibility:
 157 two encodings are equivalent if you can convert text between
 158 then without losing information (it may - and will - happen
 159 that you lose special chars like quotation marks or em-dashes
 160 but you shouldn't lose any diacritics and language-specific
 161 characters when converting between equivalent encodings).
 162
 163 Remember that this function does {\bf NOT} check for presence of
 164 fonts in system. It only tells you what are most suitable
 165 encodings. (It usually returns only one encoding.)
 166
 167 \wxheading{Notes}
 168
 169 \begin{itemize}\itemsep=0pt
 170 \item Note that argument {\it enc} itself may be present in the returned array,
 171 so that you can, as a side-effect, detect whether the
 172 encoding is native for this platform or not.
 173 \item \helpref{Convert}{wxencodingconverterconvert} is not limited to
 174 converting between equivalent encodings, it can convert between two arbitrary
 175 encodings.
 176 \item If {\it enc} is present in the returned array, then it is {\bf always} the first
 177 item of it.
 178 \item Please note that the returned array may contain no items at all.
 179 \end{itemize}
 180
 181
 182 \membersection{wxEncodingConverter::GetAllEquivalents}\label{wxencodingconvertergetallequivalents}
 183
 184 \func{static wxFontEncodingArray}{GetAllEquivalents}{\param{wxFontEncoding }{enc}}
 185
 186 Similar to
 187 \helpref{GetPlatformEquivalents}{wxencodingconvertergetplatformequivalents},
 188 but this one will return ALL
 189 equivalent encodings, regardless of the platform, and including itself.
 190
 191 This platform's encodings are before others in the array. And again, if {\it enc} is in the array,
 192 it is the very first item in it.
 193