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