docs/latex/wx/tmbconv.tex

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