use fallback encoding in wxConvAuto when input is not in UTF-8

git-svn-id: https://svn.wxwidgets.org/svn/wx/wxWidgets/trunk@48463 c3d73ce0-8a6f-49c7-b76d-6d57e0e08775

docs/latex/wx/classes.tex

@@ -70,6 +70,7 @@
 \input cshelp.tex
 \input control.tex
 \input ctrlsub.tex
+\input convauto.tex
 \input countstr.tex
 \input critsect.tex
 \input crtslock.tex

docs/latex/wx/convauto.tex

@@ -0,0 +1,115 @@
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+%% Name:        convauto.tex
+%% Purpose:     wxConvAuto documentation
+%% Author:      Vadim Zeitlin
+%% Created:     2007-08-26
+%% RCS-ID:      $Id:$
+%% Copyright:   (c) 2007 Vadim Zeitlin <vadim@wxwidgets.org>
+%% License:     wxWindows license
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+
+\section{\class{wxConvAuto}}\label{wxconvauto}
+
+This class implements a Unicode to/from multibyte converter capable of
+automatically recognizing the encoding of the multibyte text on input. The
+logic used is very simple: the class uses the BOM (byte order mark) if it's
+present and tries to interpret the input as UTF-8 otherwise. If this fails, the
+input is interpreted as being in the default multibyte encoding which can be
+specified in the constructor of a wxConvAuto instance and, in turn, defaults to
+the value of \helpref{GetFallbackEncoding}{wxconvautogetdefaultmbencoding} if
+not explicitly given.
+
+For the conversion from Unicode to multibyte, the same encoding as was
+previously used for multibyte to Unicode conversion is reused. If there had
+been no previous multibyte to Unicode conversion, UTF-8 is used by default.
+Notice that once the multibyte encoding is automatically detected, it doesn't
+change any more, i.e. it is entirely determined by the first use of wxConvAuto
+object in the multibyte-to-Unicode direction. However creating a copy of
+wxConvAuto object, either via the usual copy constructor or assignment
+operator, or using \helpref{Clone}{wxmbconvclone} method, resets the
+automatically detected encoding so that the new copy will try to detect the
+encoding of the input on first use.
+
+This class is used by default in wxWidgets classes and functions reading text
+from files such as \helpref{wxFile}{wxfile}, \helpref{wxFFile}{wxffile}, 
+\helpref{wxTextFile}{wxtextfile}, \helpref{wxFileConfig}{wxfileconfig} and
+various stream classes so the encoding set with its 
+\helpref{SetFallbackEncoding}{wxconvautosetdefaultmbencoding} method will
+affect how these classes treat input files. In particular, use this method
+to change the fall-back multibyte encoding used to interpret the contents of
+the files whose contents isn't valid UTF-8 or to disallow it completely.
+
+\wxheading{Derived from}
+
+\helpref{wxMBConv}{mbconv}
+
+\wxheading{Include files}
+
+<wx/convauto.h>
+
+\wxheading{Library}
+
+\helpref{wxBase}{librarieslist}
+
+\wxheading{See also}
+
+\helpref{wxMBConv classes overview}{mbconvclasses}
+
+
+\latexignore{\rtfignore{\wxheading{Members}}}
+
+\membersection{wxConvAuto::wxConvAuto}\label{wxconvautowxconvauto}
+
+\func{}{wxConvAuto}{\param{wxFontEncoding }{enc = wxFONTENCODING\_DEFAULT}}
+
+Constructs a new wxConvAuto instance. The object will try to detect the input
+of the multibyte text given to its \helpref{ToWChar}{wxmbconvtowchar} method
+automatically but if the automatic detection of Unicode encodings fails, the
+fall-back encoding \arg{enc} will be used to interpret it as multibyte text.
+The default value of this parameter, \texttt{wxFONTENCODING\_DEFAULT} means
+that the global default value which can be set using
+\helpref{SetFallbackEncoding}{wxconvautosetdefaultmbencoding} method should be
+used. As with that method, passing \texttt{wxFONTENCODING\_MAX} inhibits using
+this encoding completely so the input multibyte text will always be interpreted
+as UTF-8 in the absence of BOM and the conversion will fail if the input
+doesn't form valid UTF-8 sequence. Another special value is
+\texttt{wxFONTENCODING\_SYSTEM} which means to use the encoding currently used
+on the user system, i.e. the encoding returned by
+\helpref{wxLocale::GetSystemEncoding}{wxlocalegetsystemencoding}. Any other
+encoding will be used as is, e.g. passing \texttt{wxFONTENCODING\_ISO8859\_1} 
+ensures that non-UTF-8 input will be treated as latin1.
+
+
+\membersection{wxConvAuto::DisableFallbackEncoding}\label{wxconvautodisablefallbackencoding}
+
+\func{static void}{DisableFallbackEncoding}{\void}
+
+Disable the use of the fall back encoding: if the input doesn't have a BOM and
+is not valid UTF-8, the conversion will fail.
+
+
+\membersection{wxConvAuto::GetFallbackEncoding}\label{wxconvautogetdefaultmbencoding}
+
+\func{static wxFontEncoding}{GetFallbackEncoding}{\void}
+
+Returns the encoding used by default by wxConvAuto if no other encoding is
+explicitly specified in constructor. By default, returns 
+\texttt{wxFONTENCODING\_ISO8859\_1} but can be changed using 
+\helpref{SetFallbackEncoding}{wxconvautosetdefaultmbencoding} method.
+
+
+\membersection{wxConvAuto::SetFallbackEncoding}\label{wxconvautosetdefaultmbencoding}
+
+\func{static void}{SetFallbackEncoding}{\param{wxFontEncoding }{enc}}
+
+Changes the encoding used by default by wxConvAuto if no other encoding is
+explicitly specified in constructor. The default value, which can be retrieved
+using \helpref{GetFallbackEncoding}{wxconvautogetdefaultmbencoding}, is 
+\texttt{wxFONTENCODING\_ISO8859\_1}.
+
+Special values of \texttt{wxFONTENCODING\_SYSTEM} or 
+\texttt{wxFONTENCODING\_MAX} can be used for \arg{enc} parameter to use the
+encoding of the current user locale as fall back or not use any encoding for
+fall back at all, respectively (just as with the similar constructor
+parameter). However \texttt{wxFONTENCODING\_DEFAULT} value cannot be used here.
+