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