2df2a65b2d
git-svn-id: https://svn.wxwidgets.org/svn/wx/wxWidgets/trunk@49198 c3d73ce0-8a6f-49c7-b76d-6d57e0e08775
116 lines
5.2 KiB
TeX
116 lines
5.2 KiB
TeX
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
|
|
%% 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}{wxmbconv}
|
|
|
|
\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.
|
|
|