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