]> git.saurik.com Git - wxWidgets.git/blame - interface/wx/encconv.h
Implement wx-prefixed macros versions of DECLARE/IMPLEMENT*CLASS macros.
[wxWidgets.git] / interface / wx / encconv.h
CommitLineData
23324ae1
FM
1/////////////////////////////////////////////////////////////////////////////
2// Name: encconv.h
e54c96f1 3// Purpose: interface of wxEncodingConverter
23324ae1
FM
4// Author: wxWidgets team
5// RCS-ID: $Id$
6// Licence: wxWindows license
7/////////////////////////////////////////////////////////////////////////////
8
9/**
10 @class wxEncodingConverter
7c913512 11
1f1d2182 12 This class is capable of converting strings between two 8-bit encodings/charsets.
8d94819c 13 It can also convert from/to Unicode.
1f1d2182
FM
14
15 Only a limited subset of encodings is supported by wxEncodingConverter:
7c913512 16 @c wxFONTENCODING_ISO8859_1..15, @c wxFONTENCODING_CP1250..1257 and
23324ae1 17 @c wxFONTENCODING_KOI8.
7c913512 18
1f1d2182 19 @note
1f1d2182
FM
20 Please use wxMBConv classes instead if possible. wxCSConv has much better
21 support for various encodings than wxEncodingConverter.
22 wxEncodingConverter is useful only if you rely on wxCONVERT_SUBSTITUTE mode
23 of operation (see wxEncodingConverter::Init()).
24
23324ae1 25 @library{wxbase}
3c99e2fd 26 @category{conv}
7c913512 27
1f1d2182 28 @see wxFontMapper, wxMBConv, @ref overview_nonenglish
23324ae1
FM
29*/
30class wxEncodingConverter : public wxObject
31{
32public:
33 /**
34 Constructor.
35 */
36 wxEncodingConverter();
37
38 /**
4cc4bfaf 39 Return @true if (any text in) multibyte encoding @a encIn can be converted to
1f1d2182
FM
40 another one (@a encOut) losslessly.
41
42 Do not call this method with @c wxFONTENCODING_UNICODE as either parameter,
43 it doesn't make sense (always works in one sense and always depends
23324ae1
FM
44 on the text to convert in the other).
45 */
46 static bool CanConvert(wxFontEncoding encIn,
47 wxFontEncoding encOut);
48
23324ae1 49 /**
1f1d2182
FM
50 @name Conversion functions
51
52 @{
53 */
54 /**
55 Convert input string according to settings passed to Init() and writes
56 the result to output.
57
58 All the Convert() function overloads return @true if the conversion was
59 lossless and @false if at least one of the characters couldn't be converted
60 was and replaced with '?' in the output.
61
62 Note that if @c wxCONVERT_SUBSTITUTE was passed to Init(), substitution is
63 considered a lossless operation.
64
65 @note You must call Init() before using this method!
23324ae1 66 */
328f5751 67 bool Convert(const char* input, char* output) const;
1f1d2182
FM
68 bool Convert(const wchar_t* input, wchar_t* output) const;
69 bool Convert(const char* input, wchar_t* output) const;
70 bool Convert(const wchar_t* input, char* output) const;
71
72 /**
73 Convert input string according to settings passed to Init() in-place,
74 i.e. write the result to the same memory area.
75
76 See the Convert(const char*,char*) const overload for more info.
77 */
78 bool Convert(char* str) const;
79 bool Convert(wchar_t* str) const;
80
81 /**
82 Convert a wxString and return a new wxString object.
83
84 See the Convert(const char*,char*) const overload for more info.
85 */
86 wxString Convert(const wxString& input) const;
23324ae1
FM
87 //@}
88
1f1d2182 89
23324ae1 90 /**
1f1d2182 91 Similar to GetPlatformEquivalents(), but this one will return ALL
23324ae1 92 equivalent encodings, regardless of the platform, and including itself.
1f1d2182
FM
93
94 This platform's encodings are before others in the array.
95 And again, if @a enc is in the array, it is the very first item in it.
23324ae1
FM
96 */
97 static wxFontEncodingArray GetAllEquivalents(wxFontEncoding enc);
98
99 /**
1f1d2182
FM
100 Return equivalents for given font that are used under given platform.
101
102 Supported platforms:
103 @li wxPLATFORM_UNIX
104 @li wxPLATFORM_WINDOWS
105 @li wxPLATFORM_OS2
106 @li wxPLATFORM_MAC
107 @li wxPLATFORM_CURRENT
108
23324ae1 109 wxPLATFORM_CURRENT means the platform this binary was compiled for.
1f1d2182 110
23324ae1 111 Examples:
3c4f71cc 112
1f1d2182
FM
113 @verbatim
114 current platform enc returned value
115 ----------------------------------------------
116 unix CP1250 {ISO8859_2}
117 unix ISO8859_2 {ISO8859_2}
118 windows ISO8859_2 {CP1250}
119 unix CP1252 {ISO8859_1,ISO8859_15}
120 @endverbatim
121
122 Equivalence is defined in terms of convertibility: two encodings are
123 equivalent if you can convert text between then without losing
124 information (it may - and will - happen that you lose special chars
125 like quotation marks or em-dashes but you shouldn't lose any diacritics
126 and language-specific characters when converting between equivalent encodings).
127
23324ae1
FM
128 Remember that this function does @b NOT check for presence of
129 fonts in system. It only tells you what are most suitable
130 encodings. (It usually returns only one encoding.)
1f1d2182
FM
131
132 @note Note that argument enc itself may be present in the returned array,
133 so that you can, as a side-effect, detect whether the encoding is
134 native for this platform or not.
135
136 @note Convert() is not limited to converting between equivalent encodings,
137 it can convert between two arbitrary encodings.
138
139 @note If @a enc is present in the returned array, then it is always the first
140 item of it.
141
142 @note Please note that the returned array may contain no items at all.
23324ae1
FM
143 */
144 static wxFontEncodingArray GetPlatformEquivalents(wxFontEncoding enc,
1f1d2182 145 int platform = wxPLATFORM_CURRENT);
23324ae1
FM
146
147 /**
1f1d2182
FM
148 Initialize the conversion.
149
150 Both output or input encoding may be wxFONTENCODING_UNICODE, but only
151 if wxUSE_ENCODING is set to 1.
152
153 All subsequent calls to Convert() will interpret its argument
4cc4bfaf
FM
154 as a string in @a input_enc encoding and will output string in
155 @a output_enc encoding.
1f1d2182 156
7c913512 157 You must call this method before calling Convert. You may call
23324ae1 158 it more than once in order to switch to another conversion.
3c4f71cc 159
1f1d2182
FM
160 @a method affects behaviour of Convert() in case input character
161 cannot be converted because it does not exist in output encoding:
3c4f71cc 162
1f1d2182
FM
163 @li @b wxCONVERT_STRICT: follow behaviour of GNU Recode - just copy
164 unconvertible characters to output and don't change them
165 (its integer value will stay the same)
166 @li @b wxCONVERT_SUBSTITUTE: try some (lossy) substitutions - e.g.
167 replace unconvertible latin capitals with acute by ordinary
168 capitals, replace en-dash or em-dash by '-' etc.
3c4f71cc 169
23324ae1
FM
170 Both modes guarantee that output string will have same length
171 as input string.
1f1d2182
FM
172
173 @return @false if given conversion is impossible, @true otherwise
174 (conversion may be impossible either if you try to convert
175 to Unicode with non-Unicode build of wxWidgets or if input
176 or output encoding is not supported).
23324ae1
FM
177 */
178 bool Init(wxFontEncoding input_enc, wxFontEncoding output_enc,
179 int method = wxCONVERT_STRICT);
180};
e54c96f1 181