interface/convauto.h

   1 /////////////////////////////////////////////////////////////////////////////
   2 // Name:        convauto.h
   3 // Purpose:     interface of wxConvAuto
   4 // Author:      wxWidgets team
   5 // RCS-ID:      $Id$
   6 // Licence:     wxWindows license
   7 /////////////////////////////////////////////////////////////////////////////
   8
   9 /**
  10     @class wxConvAuto
  11     @wxheader{convauto.h}
  12
  13     This class implements a Unicode to/from multibyte converter capable of
  14     automatically recognizing the encoding of the multibyte text on input. The
  15     logic used is very simple: the class uses the BOM (byte order mark) if it's
  16     present and tries to interpret the input as UTF-8 otherwise. If this fails,
  17     the input is interpreted as being in the default multibyte encoding which
  18     can be specified in the constructor of a wxConvAuto instance and, in turn,
  19     defaults to the value of GetFallbackEncoding() if not explicitly given.
  20
  21     For the conversion from Unicode to multibyte, the same encoding as was
  22     previously used for multibyte to Unicode conversion is reused. If there had
  23     been no previous multibyte to Unicode conversion, UTF-8 is used by default.
  24     Notice that once the multibyte encoding is automatically detected, it
  25     doesn't change any more, i.e. it is entirely determined by the first use of
  26     wxConvAuto object in the multibyte-to-Unicode direction. However creating a
  27     copy of wxConvAuto object, either via the usual copy constructor or
  28     assignment operator, or using wxMBConv::Clone(), resets the automatically
  29     detected encoding so that the new copy will try to detect the encoding of
  30     the input on first use.
  31
  32     This class is used by default in wxWidgets classes and functions reading
  33     text from files such as wxFile, wxFFile, wxTextFile, wxFileConfig and
  34     various stream classes so the encoding set with its SetFallbackEncoding()
  35     method will affect how these classes treat input files. In particular, use
  36     this method to change the fall-back multibyte encoding used to interpret
  37     the contents of the files whose contents isn't valid UTF-8 or to disallow
  38     it completely.
  39
  40     @library{wxbase}
  41     @category{data}
  42
  43     @see @ref overview_mbconv
  44 */
  45 class wxConvAuto : public wxMBConv
  46 {
  47 public:
  48     /**
  49         Constructs a new wxConvAuto instance. The object will try to detect the
  50         input of the multibyte text given to its wxMBConv::ToWChar() method
  51         automatically but if the automatic detection of Unicode encodings
  52         fails, the fall-back encoding @a enc will be used to interpret it as
  53         multibyte text.
  54
  55         The default value of @a enc, @c wxFONTENCODING_DEFAULT, means that the
  56         global default value (which can be set using SetFallbackEncoding())
  57         should be used. As with that method, passing @c wxFONTENCODING_MAX
  58         inhibits using this encoding completely so the input multibyte text
  59         will always be interpreted as UTF-8 in the absence of BOM and the
  60         conversion will fail if the input doesn't form valid UTF-8 sequence.
  61
  62         Another special value is @c wxFONTENCODING_SYSTEM which means to use
  63         the encoding currently used on the user system, i.e. the encoding
  64         returned by wxLocale::GetSystemEncoding(). Any other encoding will be
  65         used as is, e.g. passing @c wxFONTENCODING_ISO8859_1 ensures that
  66         non-UTF-8 input will be treated as latin1.
  67     */
  68     wxConvAuto(wxFontEncoding enc = wxFONTENCODING_DEFAULT);
  69
  70     /**
  71         Disable the use of the fall back encoding: if the input doesn't have a
  72         BOM and is not valid UTF-8, the conversion will fail.
  73     */
  74     static void DisableFallbackEncoding();
  75
  76     /**
  77         Returns the encoding used by default by wxConvAuto if no other encoding
  78         is explicitly specified in constructor. By default, returns
  79         @c wxFONTENCODING_ISO8859_1 but can be changed using
  80         SetFallbackEncoding().
  81     */
  82     static wxFontEncoding GetFallbackEncoding();
  83
  84     /**
  85         Changes the encoding used by default by wxConvAuto if no other encoding
  86         is explicitly specified in constructor. The default value, which can be
  87         retrieved using GetFallbackEncoding(), is @c wxFONTENCODING_ISO8859_1.
  88
  89         Special values of @c wxFONTENCODING_SYSTEM or @c wxFONTENCODING_MAX can
  90         be used for the @a enc parameter to use the encoding of the current
  91         user locale as fall back or not use any encoding for fall back at all,
  92         respectively (just as with the similar constructor parameter). However,
  93         @c wxFONTENCODING_DEFAULT can't be used here.
  94     */
  95     static void SetFallbackEncoding(wxFontEncoding enc);
  96 };
  97