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