]>
Commit | Line | Data |
---|---|---|
1 | ///////////////////////////////////////////////////////////////////////////// | |
2 | // Name: mbconvclasses.h | |
3 | // Purpose: topic overview | |
4 | // Author: wxWidgets team | |
5 | // RCS-ID: $Id$ | |
6 | // Licence: wxWindows license | |
7 | ///////////////////////////////////////////////////////////////////////////// | |
8 | ||
9 | /** | |
10 | ||
11 | @page overview_mbconv wxMBConv Overview | |
12 | ||
13 | Classes: wxMBConv, wxMBConvLibc, wxMBConvUTF7, wxMBConvUTF8, wxCSConv, | |
14 | wxMBConvUTF16, wxMBConvUTF32 | |
15 | ||
16 | The wxMBConv classes in wxWidgets enable an Unicode-aware application to easily | |
17 | convert between Unicode and the variety of 8-bit encoding systems still in use. | |
18 | ||
19 | @li @ref overview_mbconv_need | |
20 | @li @ref overview_mbconv_string | |
21 | @li @ref overview_mbconv_classes | |
22 | @li @ref overview_mbconv_objects | |
23 | @li @ref overview_mbconv_csconv | |
24 | @li @ref overview_mbconv_converting | |
25 | @li @ref overview_mbconv_buffers | |
26 | ||
27 | ||
28 | <hr> | |
29 | ||
30 | ||
31 | @section overview_mbconv_need Background: The Need for Conversion | |
32 | ||
33 | As programs are becoming more and more globalized, and users exchange documents | |
34 | across country boundaries as never before, applications increasingly need to | |
35 | take into account all the different character sets in use around the world. It | |
36 | is no longer enough to just depend on the default byte-sized character set that | |
37 | computers have traditionally used. | |
38 | ||
39 | A few years ago, a solution was proposed: the Unicode standard. Able to contain | |
40 | the complete set of characters in use in one unified global coding system, it | |
41 | would resolve the character set problems once and for all. | |
42 | ||
43 | But it hasn't happened yet, and the migration towards Unicode has created new | |
44 | challenges, resulting in "compatibility encodings" such as UTF-8. A large | |
45 | number of systems out there still depends on the old 8-bit encodings, hampered | |
46 | by the huge amounts of legacy code still widely deployed. Even sending Unicode | |
47 | data from one Unicode-aware system to another may need encoding to an 8-bit | |
48 | multibyte encoding (UTF-7 or UTF-8 is typically used for this purpose), to pass | |
49 | unhindered through any traditional transport channels. | |
50 | ||
51 | ||
52 | @section overview_mbconv_string Background: The wxString Class | |
53 | ||
54 | If you have compiled wxWidgets in Unicode mode, the wxChar type will become | |
55 | identical to wchar_t rather than char, and a wxString stores wxChars. Hence, | |
56 | all wxString manipulation in your application will then operate on Unicode | |
57 | strings, and almost as easily as working with ordinary char strings (you just | |
58 | need to remember to use the wxT() macro to encapsulate any string literals). | |
59 | ||
60 | But often, your environment doesn't want Unicode strings. You could be sending | |
61 | data over a network, or processing a text file for some other application. You | |
62 | need a way to quickly convert your easily-handled Unicode data to and from a | |
63 | traditional 8-bit encoding. And this is what the wxMBConv classes do. | |
64 | ||
65 | ||
66 | @section overview_mbconv_classes wxMBConv Classes | |
67 | ||
68 | The base class for all these conversions is the wxMBConv class (which itself | |
69 | implements standard libc locale conversion). Derived classes include | |
70 | wxMBConvLibc, several different wxMBConvUTFxxx classes, and wxCSConv, which | |
71 | implement different kinds of conversions. You can also derive your own class | |
72 | for your own custom encoding and use it, should you need it. All you need to do | |
73 | is override the MB2WC and WC2MB methods. | |
74 | ||
75 | ||
76 | @section overview_mbconv_objects wxMBConv Objects | |
77 | ||
78 | Several of the wxWidgets-provided wxMBConv classes have predefined instances | |
79 | (wxConvLibc, wxConvFileName, wxConvUTF7, wxConvUTF8, wxConvLocal). You can use | |
80 | these predefined objects directly, or you can instantiate your own objects. | |
81 | ||
82 | A variable, wxConvCurrent, points to the conversion object that the user | |
83 | interface is supposed to use, in the case that the user interface is not | |
84 | Unicode-based (like with GTK+ 1.2). By default, it points to wxConvLibc or | |
85 | wxConvLocal, depending on which works best on the current platform. | |
86 | ||
87 | ||
88 | @section overview_mbconv_csconv wxCSConv | |
89 | ||
90 | The wxCSConv class is special because when it is instantiated, you can tell it | |
91 | which character set it should use, which makes it meaningful to keep many | |
92 | instances of them around, each with a different character set (or you can | |
93 | create a wxCSConv instance on the fly). | |
94 | ||
95 | The predefined wxCSConv instance, wxConvLocal, is preset to use the default | |
96 | user character set, but you should rarely need to use it directly, it is better | |
97 | to go through wxConvCurrent. | |
98 | ||
99 | ||
100 | @section overview_mbconv_converting Converting Strings | |
101 | ||
102 | Once you have chosen which object you want to use to convert your text, here is | |
103 | how you would use them with wxString. These examples all assume that you are | |
104 | using a Unicode build of wxWidgets, although they will still compile in a | |
105 | non-Unicode build (they just won't convert anything). | |
106 | ||
107 | Example 1: Constructing a wxString from input in current encoding. | |
108 | ||
109 | @code | |
110 | wxString str(input_data, *wxConvCurrent); | |
111 | @endcode | |
112 | ||
113 | Example 2: Input in UTF-8 encoding. | |
114 | ||
115 | @code | |
116 | wxString str(input_data, wxConvUTF8); | |
117 | @endcode | |
118 | ||
119 | Example 3: Input in KOI8-R. Construction of wxCSConv instance on the fly. | |
120 | ||
121 | @code | |
122 | wxString str(input_data, wxCSConv(wxT("koi8-r"))); | |
123 | @endcode | |
124 | ||
125 | Example 4: Printing a wxString to stdout in UTF-8 encoding. | |
126 | ||
127 | @code | |
128 | puts(str.mb_str(wxConvUTF8)); | |
129 | @endcode | |
130 | ||
131 | Example 5: Printing a wxString to stdout in custom encoding. Using | |
132 | preconstructed wxCSConv instance. | |
133 | ||
134 | @code | |
135 | wxCSConv cust(user_encoding); | |
136 | printf("Data: %s\n", (const char*) str.mb_str(cust)); | |
137 | @endcode | |
138 | ||
139 | @note Since mb_str() returns a temporary wxCharBuffer to hold the result of the | |
140 | conversion, you need to explicitly cast it to const char* if you use it in a | |
141 | vararg context (like with printf). | |
142 | ||
143 | ||
144 | @section overview_mbconv_buffers Converting Buffers | |
145 | ||
146 | If you have specialized needs, or just don't want to use wxString, you can also | |
147 | use the conversion methods of the conversion objects directly. This can even be | |
148 | useful if you need to do conversion in a non-Unicode build of wxWidgets; | |
149 | converting a string from UTF-8 to the current encoding should be possible by | |
150 | doing this: | |
151 | ||
152 | @code | |
153 | wxString str(wxConvUTF8.cMB2WC(input_data), *wxConvCurrent); | |
154 | @endcode | |
155 | ||
156 | Here, cMB2WC of the UTF8 object returns a wxWCharBuffer containing a Unicode | |
157 | string. The wxString constructor then converts it back to an 8-bit character | |
158 | set using the passed conversion object, *wxConvCurrent. (In a Unicode build of | |
159 | wxWidgets, the constructor ignores the passed conversion object and retains the | |
160 | Unicode data.) | |
161 | ||
162 | This could also be done by first making a wxString of the original data: | |
163 | ||
164 | @code | |
165 | wxString input_str(input_data); | |
166 | wxString str(input_str.wc_str(wxConvUTF8), *wxConvCurrent); | |
167 | @endcode | |
168 | ||
169 | To print a wxChar buffer to a non-Unicode stdout: | |
170 | ||
171 | @code | |
172 | printf("Data: %s\n", (const char*) wxConvCurrent->cWX2MB(unicode_data)); | |
173 | @endcode | |
174 | ||
175 | If you need to do more complex processing on the converted data, you may want | |
176 | to store the temporary buffer in a local variable: | |
177 | ||
178 | @code | |
179 | const wxWX2MBbuf tmp_buf = wxConvCurrent->cWX2MB(unicode_data); | |
180 | const char *tmp_str = (const char*) tmp_buf; | |
181 | printf("Data: %s\n", tmp_str); | |
182 | process_data(tmp_str); | |
183 | @endcode | |
184 | ||
185 | If a conversion had taken place in cWX2MB (i.e. in a Unicode build), the buffer | |
186 | will be deallocated as soon as tmp_buf goes out of scope. The macro wxWX2MBbuf | |
187 | reflects the correct return value of cWX2MB (either char* or wxCharBuffer), | |
188 | except for the const. | |
189 | ||
190 | */ | |
191 |