interface/wx/encconv.h

   1 /////////////////////////////////////////////////////////////////////////////
   2 // Name:        encconv.h
   3 // Purpose:     interface of wxEncodingConverter
   4 // Author:      wxWidgets team
   5 // Licence:     wxWindows licence
   6 /////////////////////////////////////////////////////////////////////////////
   7
   8 /**
   9     @class wxEncodingConverter
  10
  11     This class is capable of converting strings between two 8-bit encodings/charsets.
  12     It can also convert from/to Unicode.
  13
  14     Only a limited subset of encodings is supported by wxEncodingConverter:
  15     @c wxFONTENCODING_ISO8859_1..15, @c wxFONTENCODING_CP1250..1257 and
  16     @c wxFONTENCODING_KOI8.
  17
  18     @note
  19     Please use wxMBConv classes instead if possible. wxCSConv has much better
  20     support for various encodings than wxEncodingConverter.
  21     wxEncodingConverter is useful only if you rely on wxCONVERT_SUBSTITUTE mode
  22     of operation (see wxEncodingConverter::Init()).
  23
  24     @library{wxbase}
  25     @category{conv}
  26
  27     @see wxFontMapper, wxMBConv, @ref overview_nonenglish
  28 */
  29 class wxEncodingConverter : public wxObject
  30 {
  31 public:
  32     /**
  33         Constructor.
  34     */
  35     wxEncodingConverter();
  36
  37     /**
  38         Return @true if (any text in) multibyte encoding @a encIn can be converted to
  39         another one (@a encOut) losslessly.
  40
  41         Do not call this method with @c wxFONTENCODING_UNICODE as either parameter,
  42         it doesn't make sense (always works in one sense and always depends
  43         on the text to convert in the other).
  44     */
  45     static bool CanConvert(wxFontEncoding encIn,
  46                            wxFontEncoding encOut);
  47
  48     /**
  49         @name Conversion functions
  50
  51         @{
  52     */
  53     /**
  54         Convert input string according to settings passed to Init() and writes
  55         the result to output.
  56
  57         All the Convert() function overloads return @true if the conversion was
  58         lossless and @false if at least one of the characters couldn't be converted
  59         was and replaced with '?' in the output.
  60
  61         Note that if @c wxCONVERT_SUBSTITUTE was passed to Init(), substitution is
  62         considered a lossless operation.
  63
  64         @note You must call Init() before using this method!
  65     */
  66     bool Convert(const char* input, char* output) const;
  67     bool Convert(const wchar_t* input, wchar_t* output) const;
  68     bool Convert(const char* input, wchar_t* output) const;
  69     bool Convert(const wchar_t* input, char* output) const;
  70
  71     /**
  72         Convert input string according to settings passed to Init() in-place.
  73
  74         With this overload, the conversion result is written to the same memory
  75         area from which the input is read.
  76
  77         See the Convert(const char*,char*) const overload for more info.
  78     */
  79     bool Convert(char* str) const;
  80
  81     /**
  82         Convert input string according to settings passed to Init() in-place.
  83
  84         With this overload, the conversion result is written to the same memory
  85         area from which the input is read.
  86
  87         See the Convert(const wchar_t*,wchar_t*) const overload for more info.
  88     */
  89     bool Convert(wchar_t* str) const;
  90
  91     /**
  92         Convert a wxString and return a new wxString object.
  93
  94         See the Convert(const char*,char*) const overload for more info.
  95     */
  96     wxString Convert(const wxString& input) const;
  97     //@}
  98
  99
 100     /**
 101         Similar to GetPlatformEquivalents(), but this one will return ALL
 102         equivalent encodings, regardless of the platform, and including itself.
 103
 104         This platform's encodings are before others in the array.
 105         And again, if @a enc is in the array, it is the very first item in it.
 106     */
 107     static wxFontEncodingArray GetAllEquivalents(wxFontEncoding enc);
 108
 109     /**
 110         Return equivalents for given font that are used under given platform.
 111
 112         Supported platforms:
 113         @li wxPLATFORM_UNIX
 114         @li wxPLATFORM_WINDOWS
 115         @li wxPLATFORM_OS2
 116         @li wxPLATFORM_MAC
 117         @li wxPLATFORM_CURRENT
 118
 119         wxPLATFORM_CURRENT means the platform this binary was compiled for.
 120
 121         Examples:
 122
 123         @verbatim
 124         current platform   enc          returned value
 125         ----------------------------------------------
 126         unix            CP1250             {ISO8859_2}
 127         unix         ISO8859_2             {ISO8859_2}
 128         windows      ISO8859_2                {CP1250}
 129         unix            CP1252  {ISO8859_1,ISO8859_15}
 130         @endverbatim
 131
 132         Equivalence is defined in terms of convertibility: two encodings are
 133         equivalent if you can convert text between then without losing
 134         information (it may - and will - happen that you lose special chars
 135         like quotation marks or em-dashes but you shouldn't lose any diacritics
 136         and language-specific characters when converting between equivalent encodings).
 137
 138         Remember that this function does @b NOT check for presence of
 139         fonts in system. It only tells you what are most suitable
 140         encodings. (It usually returns only one encoding.)
 141
 142         @note Note that argument enc itself may be present in the returned array,
 143               so that you can, as a side-effect, detect whether the encoding is
 144               native for this platform or not.
 145
 146         @note Convert() is not limited to converting between equivalent encodings,
 147               it can convert between two arbitrary encodings.
 148
 149         @note If @a enc is present in the returned array, then it is always the first
 150               item of it.
 151
 152         @note Please note that the returned array may contain no items at all.
 153     */
 154     static wxFontEncodingArray GetPlatformEquivalents(wxFontEncoding enc,
 155                                                       int platform = wxPLATFORM_CURRENT);
 156
 157     /**
 158         Initialize the conversion.
 159
 160         Both output or input encoding may be wxFONTENCODING_UNICODE, but only
 161         if wxUSE_ENCODING is set to 1.
 162
 163         All subsequent calls to Convert() will interpret its argument
 164         as a string in @a input_enc encoding and will output string in
 165         @a output_enc encoding.
 166
 167         You must call this method before calling Convert. You may call
 168         it more than once in order to switch to another conversion.
 169
 170         @a method affects behaviour of Convert() in case input character
 171         cannot be converted because it does not exist in output encoding:
 172
 173         @li @b wxCONVERT_STRICT: follow behaviour of GNU Recode - just copy
 174             unconvertible  characters to output and don't change them
 175             (its integer value will stay the same)
 176         @li @b wxCONVERT_SUBSTITUTE:  try some (lossy) substitutions - e.g.
 177             replace unconvertible latin capitals with acute by ordinary
 178             capitals, replace en-dash or em-dash by '-' etc.
 179
 180         Both modes guarantee that output string will have same length
 181         as input string.
 182
 183         @return @false if given conversion is impossible, @true otherwise
 184                 (conversion may be impossible either if you try to convert
 185                 to Unicode with non-Unicode build of wxWidgets or if input
 186                 or output encoding is not supported).
 187     */
 188     bool Init(wxFontEncoding input_enc, wxFontEncoding output_enc,
 189               int method = wxCONVERT_STRICT);
 190 };
 191