docs/latex/wx/convauto.tex

   1 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
   2 %% Name:        convauto.tex
   3 %% Purpose:     wxConvAuto documentation
   4 %% Author:      Vadim Zeitlin
   5 %% Created:     2007-08-26
   6 %% RCS-ID:      $Id:$
   7 %% Copyright:   (c) 2007 Vadim Zeitlin <vadim@wxwidgets.org>
   8 %% License:     wxWindows license
   9 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
  10
  11 \section{\class{wxConvAuto}}\label{wxconvauto}
  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 \helpref{GetFallbackEncoding}{wxconvautogetdefaultmbencoding} 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 \helpref{Clone}{wxmbconvclone} 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 \helpref{wxFile}{wxfile}, \helpref{wxFFile}{wxffile},
  35 \helpref{wxTextFile}{wxtextfile}, \helpref{wxFileConfig}{wxfileconfig} and
  36 various stream classes so the encoding set with its
  37 \helpref{SetFallbackEncoding}{wxconvautosetdefaultmbencoding} 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 \wxheading{Derived from}
  43
  44 \helpref{wxMBConv}{wxmbconv}
  45
  46 \wxheading{Include files}
  47
  48 <wx/convauto.h>
  49
  50 \wxheading{Library}
  51
  52 \helpref{wxBase}{librarieslist}
  53
  54 \wxheading{See also}
  55
  56 \helpref{wxMBConv classes overview}{mbconvclasses}
  57
  58
  59 \latexignore{\rtfignore{\wxheading{Members}}}
  60
  61 \membersection{wxConvAuto::wxConvAuto}\label{wxconvautowxconvauto}
  62
  63 \func{}{wxConvAuto}{\param{wxFontEncoding }{enc = wxFONTENCODING\_DEFAULT}}
  64
  65 Constructs a new wxConvAuto instance. The object will try to detect the input
  66 of the multibyte text given to its \helpref{ToWChar}{wxmbconvtowchar} method
  67 automatically but if the automatic detection of Unicode encodings fails, the
  68 fall-back encoding \arg{enc} will be used to interpret it as multibyte text.
  69 The default value of this parameter, \texttt{wxFONTENCODING\_DEFAULT} means
  70 that the global default value which can be set using
  71 \helpref{SetFallbackEncoding}{wxconvautosetdefaultmbencoding} method should be
  72 used. As with that method, passing \texttt{wxFONTENCODING\_MAX} inhibits using
  73 this encoding completely so the input multibyte text will always be interpreted
  74 as UTF-8 in the absence of BOM and the conversion will fail if the input
  75 doesn't form valid UTF-8 sequence. Another special value is
  76 \texttt{wxFONTENCODING\_SYSTEM} which means to use the encoding currently used
  77 on the user system, i.e. the encoding returned by
  78 \helpref{wxLocale::GetSystemEncoding}{wxlocalegetsystemencoding}. Any other
  79 encoding will be used as is, e.g. passing \texttt{wxFONTENCODING\_ISO8859\_1}
  80 ensures that non-UTF-8 input will be treated as latin1.
  81
  82
  83 \membersection{wxConvAuto::DisableFallbackEncoding}\label{wxconvautodisablefallbackencoding}
  84
  85 \func{static void}{DisableFallbackEncoding}{\void}
  86
  87 Disable the use of the fall back encoding: if the input doesn't have a BOM and
  88 is not valid UTF-8, the conversion will fail.
  89
  90
  91 \membersection{wxConvAuto::GetFallbackEncoding}\label{wxconvautogetdefaultmbencoding}
  92
  93 \func{static wxFontEncoding}{GetFallbackEncoding}{\void}
  94
  95 Returns the encoding used by default by wxConvAuto if no other encoding is
  96 explicitly specified in constructor. By default, returns
  97 \texttt{wxFONTENCODING\_ISO8859\_1} but can be changed using
  98 \helpref{SetFallbackEncoding}{wxconvautosetdefaultmbencoding} method.
  99
 100
 101 \membersection{wxConvAuto::SetFallbackEncoding}\label{wxconvautosetdefaultmbencoding}
 102
 103 \func{static void}{SetFallbackEncoding}{\param{wxFontEncoding }{enc}}
 104
 105 Changes the encoding used by default by wxConvAuto if no other encoding is
 106 explicitly specified in constructor. The default value, which can be retrieved
 107 using \helpref{GetFallbackEncoding}{wxconvautogetdefaultmbencoding}, is
 108 \texttt{wxFONTENCODING\_ISO8859\_1}.
 109
 110 Special values of \texttt{wxFONTENCODING\_SYSTEM} or
 111 \texttt{wxFONTENCODING\_MAX} can be used for \arg{enc} parameter to use the
 112 encoding of the current user locale as fall back or not use any encoding for
 113 fall back at all, respectively (just as with the similar constructor
 114 parameter). However \texttt{wxFONTENCODING\_DEFAULT} value cannot be used here.
 115