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