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