]> git.saurik.com Git - wxWidgets.git/blame - interface/convauto.h
fixed category
[wxWidgets.git] / interface / convauto.h
CommitLineData
23324ae1
FM
1/////////////////////////////////////////////////////////////////////////////
2// Name: convauto.h
3// Purpose: documentation for wxConvAuto class
4// Author: wxWidgets team
5// RCS-ID: $Id$
6// Licence: wxWindows license
7/////////////////////////////////////////////////////////////////////////////
8
9/**
10 @class wxConvAuto
11 @wxheader{convauto.h}
7c913512 12
23324ae1
FM
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.
7c913512 21
23324ae1
FM
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.
7c913512 32
23324ae1 33 This class is used by default in wxWidgets classes and functions reading text
7c913512 34 from files such as wxFile, wxFFile,
23324ae1 35 wxTextFile, wxFileConfig and
7c913512 36 various stream classes so the encoding set with its
23324ae1
FM
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.
7c913512 41
23324ae1
FM
42 @library{wxbase}
43 @category{FIXME}
7c913512 44
23324ae1
FM
45 @seealso
46 @ref overview_mbconvclasses "wxMBConv classes overview"
47*/
48class wxConvAuto : public wxMBConv
49{
50public:
51 /**
52 Constructs a new wxConvAuto instance. The object will try to detect the input
53 of the multibyte text given to its wxMBConv::ToWChar method
54 automatically but if the automatic detection of Unicode encodings fails, the
4cc4bfaf 55 fall-back encoding @a enc will be used to interpret it as multibyte text.
23324ae1
FM
56 The default value of this parameter, @c wxFONTENCODING_DEFAULT means
57 that the global default value which can be set using
58 @ref setdefaultmbencoding() SetFallbackEncoding method should be
59 used. As with that method, passing @c wxFONTENCODING_MAX inhibits using
60 this encoding completely so the input multibyte text will always be interpreted
61 as UTF-8 in the absence of BOM and the conversion will fail if the input
62 doesn't form valid UTF-8 sequence. Another special value is
63 @c wxFONTENCODING_SYSTEM which means to use the encoding currently used
64 on the user system, i.e. the encoding returned by
65 wxLocale::GetSystemEncoding. Any other
7c913512 66 encoding will be used as is, e.g. passing @c wxFONTENCODING_ISO8859_1
23324ae1
FM
67 ensures that non-UTF-8 input will be treated as latin1.
68 */
69 wxConvAuto(wxFontEncoding enc = wxFONTENCODING_DEFAULT);
70
71 /**
72 Disable the use of the fall back encoding: if the input doesn't have a BOM and
73 is not valid UTF-8, the conversion will fail.
74 */
75 static void DisableFallbackEncoding();
76
77 /**
78 Returns the encoding used by default by wxConvAuto if no other encoding is
7c913512
FM
79 explicitly specified in constructor. By default, returns
80 @c wxFONTENCODING_ISO8859_1 but can be changed using
23324ae1
FM
81 @ref setdefaultmbencoding() SetFallbackEncoding method.
82 */
83 static wxFontEncoding GetFallbackEncoding();
84
85 /**
86 Changes the encoding used by default by wxConvAuto if no other encoding is
87 explicitly specified in constructor. The default value, which can be retrieved
7c913512 88 using @ref getdefaultmbencoding() GetFallbackEncoding, is
23324ae1 89 @c wxFONTENCODING_ISO8859_1.
7c913512 90 Special values of @c wxFONTENCODING_SYSTEM or
4cc4bfaf 91 @c wxFONTENCODING_MAX can be used for @a enc parameter to use the
23324ae1
FM
92 encoding of the current user locale as fall back or not use any encoding for
93 fall back at all, respectively (just as with the similar constructor
94 parameter). However @c wxFONTENCODING_DEFAULT value cannot be used here.
95 */
96 static void SetFallbackEncoding(wxFontEncoding enc);
97};