interface/encconv.h

   1 /////////////////////////////////////////////////////////////////////////////
   2 // Name:        encconv.h
   3 // Purpose:     interface of wxEncodingConverter
   4 // Author:      wxWidgets team
   5 // RCS-ID:      $Id$
   6 // Licence:     wxWindows license
   7 /////////////////////////////////////////////////////////////////////////////
   8
   9 /**
  10     @class wxEncodingConverter
  11     @wxheader{encconv.h}
  12
  13     This class is capable of converting strings between two
  14     8-bit encodings/charsets. It can also convert from/to Unicode (but only
  15     if you compiled wxWidgets with wxUSE_WCHAR_T set to 1). Only a limited subset
  16     of encodings is supported by wxEncodingConverter:
  17     @c wxFONTENCODING_ISO8859_1..15, @c wxFONTENCODING_CP1250..1257 and
  18     @c wxFONTENCODING_KOI8.
  19
  20     @library{wxbase}
  21     @category{misc}
  22
  23     @see wxFontMapper, wxMBConv, @ref overview_nonenglishoverview "Writing
  24     non-English applications"
  25 */
  26 class wxEncodingConverter : public wxObject
  27 {
  28 public:
  29     /**
  30         Constructor.
  31     */
  32     wxEncodingConverter();
  33
  34     /**
  35         Return @true if (any text in) multibyte encoding @a encIn can be converted to
  36         another one (@e encOut) losslessly.
  37         Do not call this method with @c wxFONTENCODING_UNICODE as either
  38         parameter, it doesn't make sense (always works in one sense and always depends
  39         on the text to convert in the other).
  40     */
  41     static bool CanConvert(wxFontEncoding encIn,
  42                            wxFontEncoding encOut);
  43
  44     //@{
  45     /**
  46         Convert wxString and return new wxString object.
  47     */
  48     bool Convert(const char* input, char* output) const;
  49     const bool Convert(const wchar_t* input, wchar_t* output) const;
  50     const bool Convert(const char* input, wchar_t* output) const;
  51     const bool Convert(const wchar_t* input, char* output) const;
  52     const bool Convert(char* str) const;
  53     const bool Convert(wchar_t* str) const;
  54     const wxString  Convert(const wxString& input) const;
  55     //@}
  56
  57     /**
  58         Similar to
  59         GetPlatformEquivalents(),
  60         but this one will return ALL
  61         equivalent encodings, regardless of the platform, and including itself.
  62         This platform's encodings are before others in the array. And again, if @a enc
  63         is in the array,
  64         it is the very first item in it.
  65     */
  66     static wxFontEncodingArray GetAllEquivalents(wxFontEncoding enc);
  67
  68     /**
  69         Return equivalents for given font that are used
  70         under given platform. Supported platforms:
  71          wxPLATFORM_UNIX
  72          wxPLATFORM_WINDOWS
  73          wxPLATFORM_OS2
  74          wxPLATFORM_MAC
  75          wxPLATFORM_CURRENT
  76         wxPLATFORM_CURRENT means the platform this binary was compiled for.
  77         Examples:
  78
  79         Equivalence is defined in terms of convertibility:
  80         two encodings are equivalent if you can convert text between
  81         then without losing information (it may - and will - happen
  82         that you lose special chars like quotation marks or em-dashes
  83         but you shouldn't lose any diacritics and language-specific
  84         characters when converting between equivalent encodings).
  85         Remember that this function does @b NOT check for presence of
  86         fonts in system. It only tells you what are most suitable
  87         encodings. (It usually returns only one encoding.)
  88     */
  89     static wxFontEncodingArray GetPlatformEquivalents(wxFontEncoding enc,
  90             int platform = wxPLATFORM_CURRENT);
  91
  92     /**
  93         Initialize conversion. Both output or input encoding may
  94         be wxFONTENCODING_UNICODE, but only if wxUSE_ENCODING is set to 1.
  95         All subsequent calls to Convert()
  96         will interpret its argument
  97         as a string in @a input_enc encoding and will output string in
  98         @a output_enc encoding.
  99         You must call this method before calling Convert. You may call
 100         it more than once in order to switch to another conversion.
 101         @e Method affects behaviour of Convert() in case input character
 102         cannot be converted because it does not exist in output encoding:
 103
 104         @b wxCONVERT_STRICT
 105
 106         follow behaviour of GNU Recode -
 107         just copy unconvertible  characters to output and don't change them
 108         (its integer value will stay the same)
 109
 110         @b wxCONVERT_SUBSTITUTE
 111
 112         try some (lossy) substitutions
 113         - e.g. replace unconvertible latin capitals with acute by ordinary
 114         capitals, replace en-dash or em-dash by '-' etc.
 115
 116         Both modes guarantee that output string will have same length
 117         as input string.
 118     */
 119     bool Init(wxFontEncoding input_enc, wxFontEncoding output_enc,
 120               int method = wxCONVERT_STRICT);
 121 };
 122