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, the
  17     input is interpreted as being in the default multibyte encoding which can be
  18     specified in the constructor of a wxConvAuto instance and, in turn, defaults to
  19     the value of @ref wxConvAuto::getdefaultmbencoding GetFallbackEncoding if
  20     not explicitly given.
  21
  22     For the conversion from Unicode to multibyte, the same encoding as was
  23     previously used for multibyte to Unicode conversion is reused. If there had
  24     been no previous multibyte to Unicode conversion, UTF-8 is used by default.
  25     Notice that once the multibyte encoding is automatically detected, it doesn't
  26     change any more, i.e. it is entirely determined by the first use of wxConvAuto
  27     object in the multibyte-to-Unicode direction. However creating a copy of
  28     wxConvAuto object, either via the usual copy constructor or assignment
  29     operator, or using wxMBConv::Clone method, resets the
  30     automatically detected encoding so that the new copy will try to detect the
  31     encoding of the input on first use.
  32
  33     This class is used by default in wxWidgets classes and functions reading text
  34     from files such as wxFile, wxFFile,
  35     wxTextFile, wxFileConfig and
  36     various stream classes so the encoding set with its
  37     @ref wxConvAuto::setdefaultmbencoding SetFallbackEncoding method will
  38     affect how these classes treat input files. In particular, use this method
  39     to change the fall-back multibyte encoding used to interpret the contents of
  40     the files whose contents isn't valid UTF-8 or to disallow it completely.
  41
  42     @library{wxbase}
  43     @category{FIXME}
  44
  45     @see @ref overview_mbconvclasses "wxMBConv classes overview"
  46 */
  47 class wxConvAuto : public wxMBConv
  48 {
  49 public:
  50     /**
  51         Constructs a new wxConvAuto instance. The object will try to detect the input
  52         of the multibyte text given to its wxMBConv::ToWChar method
  53         automatically but if the automatic detection of Unicode encodings fails, the
  54         fall-back encoding @a enc will be used to interpret it as multibyte text.
  55         The default value of this parameter, @c wxFONTENCODING_DEFAULT means
  56         that the global default value which can be set using
  57         @ref setdefaultmbencoding() SetFallbackEncoding method should be
  58         used. As with that method, passing @c wxFONTENCODING_MAX inhibits using
  59         this encoding completely so the input multibyte text will always be interpreted
  60         as UTF-8 in the absence of BOM and the conversion will fail if the input
  61         doesn't form valid UTF-8 sequence. Another special value is
  62         @c wxFONTENCODING_SYSTEM which means to use the encoding currently used
  63         on the user system, i.e. the encoding returned by
  64         wxLocale::GetSystemEncoding. Any other
  65         encoding will be used as is, e.g. passing @c wxFONTENCODING_ISO8859_1
  66         ensures that 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 BOM and
  72         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 is
  78         explicitly specified in constructor. By default, returns
  79         @c wxFONTENCODING_ISO8859_1 but can be changed using
  80         @ref setdefaultmbencoding() SetFallbackEncoding method.
  81     */
  82     static wxFontEncoding GetFallbackEncoding();
  83
  84     /**
  85         Changes the encoding used by default by wxConvAuto if no other encoding is
  86         explicitly specified in constructor. The default value, which can be retrieved
  87         using @ref getdefaultmbencoding() GetFallbackEncoding, is
  88         @c wxFONTENCODING_ISO8859_1.
  89         Special values of @c wxFONTENCODING_SYSTEM or
  90         @c wxFONTENCODING_MAX can be used for @a enc parameter to use the
  91         encoding of the current user locale as fall back or not use any encoding for
  92         fall back at all, respectively (just as with the similar constructor
  93         parameter). However @c wxFONTENCODING_DEFAULT value cannot be used here.
  94     */
  95     static void SetFallbackEncoding(wxFontEncoding enc);
  96 };
  97