docs/doxygen/overviews/mbconvclasses.h

   1 /////////////////////////////////////////////////////////////////////////////
   2 // Name:        mbconvclasses.h
   3 // Purpose:     topic overview
   4 // Author:      wxWidgets team
   5 // RCS-ID:      $Id$
   6 // Licence:     wxWindows licence
   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 @todo rewrite this overview; it's not up2date with wxString changes
  55
  56 If you have compiled wxWidgets in Unicode mode, the wxChar type will become
  57 identical to wchar_t rather than char, and a wxString stores wxChars. Hence,
  58 all wxString manipulation in your application will then operate on Unicode
  59 strings, and almost as easily as working with ordinary char strings (you just
  60 need to remember to use the wxT() macro to encapsulate any string literals).
  61
  62 But often, your environment doesn't want Unicode strings. You could be sending
  63 data over a network, or processing a text file for some other application. You
  64 need a way to quickly convert your easily-handled Unicode data to and from a
  65 traditional 8-bit encoding. And this is what the wxMBConv classes do.
  66
  67
  68 @section overview_mbconv_classes wxMBConv Classes
  69
  70 The base class for all these conversions is the wxMBConv class (which itself
  71 implements standard libc locale conversion). Derived classes include
  72 wxMBConvLibc, several different wxMBConvUTFxxx classes, and wxCSConv, which
  73 implement different kinds of conversions. You can also derive your own class
  74 for your own custom encoding and use it, should you need it. All you need to do
  75 is override the MB2WC and WC2MB methods.
  76
  77
  78 @section overview_mbconv_objects wxMBConv Objects
  79
  80 Several of the wxWidgets-provided wxMBConv classes have predefined instances
  81 (wxConvLibc, wxConvFileName, wxConvUTF7, wxConvUTF8, wxConvLocal). You can use
  82 these predefined objects directly, or you can instantiate your own objects.
  83
  84 A variable, wxConvCurrent, points to the conversion object that the user
  85 interface is supposed to use, in the case that the user interface is not
  86 Unicode-based (like with GTK+ 1.2). By default, it points to wxConvLibc or
  87 wxConvLocal, depending on which works best on the current platform.
  88
  89
  90 @section overview_mbconv_csconv wxCSConv
  91
  92 The wxCSConv class is special because when it is instantiated, you can tell it
  93 which character set it should use, which makes it meaningful to keep many
  94 instances of them around, each with a different character set (or you can
  95 create a wxCSConv instance on the fly).
  96
  97 The predefined wxCSConv instance, wxConvLocal, is preset to use the default
  98 user character set, but you should rarely need to use it directly, it is better
  99 to go through wxConvCurrent.
 100
 101
 102 @section overview_mbconv_converting Converting Strings
 103
 104 Once you have chosen which object you want to use to convert your text, here is
 105 how you would use them with wxString. These examples all assume that you are
 106 using a Unicode build of wxWidgets, although they will still compile in a
 107 non-Unicode build (they just won't convert anything).
 108
 109 Example 1: Constructing a wxString from input in current encoding.
 110
 111 @code
 112 wxString str(input_data, *wxConvCurrent);
 113 @endcode
 114
 115 Example 2: Input in UTF-8 encoding.
 116
 117 @code
 118 wxString str(input_data, wxConvUTF8);
 119 @endcode
 120
 121 Example 3: Input in KOI8-R. Construction of wxCSConv instance on the fly.
 122
 123 @code
 124 wxString str(input_data, wxCSConv(wxT("koi8-r")));
 125 @endcode
 126
 127 Example 4: Printing a wxString to stdout in UTF-8 encoding.
 128
 129 @code
 130 puts(str.mb_str(wxConvUTF8));
 131 @endcode
 132
 133 Example 5: Printing a wxString to stdout in custom encoding. Using
 134 preconstructed wxCSConv instance.
 135
 136 @code
 137 wxCSConv cust(user_encoding);
 138 printf("Data: %s\n", (const char*) str.mb_str(cust));
 139 @endcode
 140
 141 @note Since mb_str() returns a temporary wxCharBuffer to hold the result of the
 142 conversion, you need to explicitly cast it to const char* if you use it in a
 143 vararg context (like with printf).
 144
 145
 146 @section overview_mbconv_buffers Converting Buffers
 147
 148 If you have specialized needs, or just don't want to use wxString, you can also
 149 use the conversion methods of the conversion objects directly. This can even be
 150 useful if you need to do conversion in a non-Unicode build of wxWidgets;
 151 converting a string from UTF-8 to the current encoding should be possible by
 152 doing this:
 153
 154 @code
 155 wxString str(wxConvUTF8.cMB2WC(input_data), *wxConvCurrent);
 156 @endcode
 157
 158 Here, cMB2WC of the UTF8 object returns a wxWCharBuffer containing a Unicode
 159 string. The wxString constructor then converts it back to an 8-bit character
 160 set using the passed conversion object, *wxConvCurrent. (In a Unicode build of
 161 wxWidgets, the constructor ignores the passed conversion object and retains the
 162 Unicode data.)
 163
 164 This could also be done by first making a wxString of the original data:
 165
 166 @code
 167 wxString input_str(input_data);
 168 wxString str(input_str.wc_str(wxConvUTF8), *wxConvCurrent);
 169 @endcode
 170
 171 To print a wxChar buffer to a non-Unicode stdout:
 172
 173 @code
 174 printf("Data: %s\n", (const char*) wxConvCurrent->cWX2MB(unicode_data));
 175 @endcode
 176
 177 If you need to do more complex processing on the converted data, you may want
 178 to store the temporary buffer in a local variable:
 179
 180 @code
 181 const wxWX2MBbuf tmp_buf = wxConvCurrent->cWX2MB(unicode_data);
 182 const char *tmp_str = (const char*) tmp_buf;
 183 printf("Data: %s\n", tmp_str);
 184 process_data(tmp_str);
 185 @endcode
 186
 187 If a conversion had taken place in cWX2MB (i.e. in a Unicode build), the buffer
 188 will be deallocated as soon as tmp_buf goes out of scope. The macro wxWX2MBbuf
 189 reflects the correct return value of cWX2MB (either char* or wxCharBuffer),
 190 except for the const.
 191
 192 */
 193