interface/encconv.h

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