docs/doxygen/overviews/mbconvclasses.h

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