interface/wx/encconv.h

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