1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126
|
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<meta http-equiv="Content-Type" content="text/xhtml;charset=UTF-8"/>
<meta http-equiv="X-UA-Compatible" content="IE=9"/>
<title>wxWidgets: wxMBConv Overview</title>
<link href="tabs.css" rel="stylesheet" type="text/css"/>
<script type="text/javascript" src="jquery.js"></script>
<script type="text/javascript" src="dynsections.js"></script>
<link href="doxygen.css" rel="stylesheet" type="text/css" />
<link href="extra_stylesheet.css" rel="stylesheet" type="text/css"/>
</head>
<body>
<div id="page_container">
<div id="top"><!-- do not remove this div, it is closed by doxygen! -->
<div id="titlearea">
<table cellspacing="0" cellpadding="0" style="width: 100%;">
<tbody>
<tr>
<td id="projectlogo">
<a href="http://www.wxwidgets.org/" target="_new">
<img alt="wxWidgets" src="logo.png"/>
</a>
</td>
<td style="padding-left: 0.5em; text-align: right;">
<span id="projectnumber">Version: 3.0.2</span>
</td>
</tr>
</tbody>
</table>
</div>
<!-- Generated by Doxygen 1.8.2 -->
<div id="navrow1" class="tabs">
<ul class="tablist">
<li><a href="index.html"><span>Main Page</span></a></li>
<li class="current"><a href="pages.html"><span>Related Pages</span></a></li>
<li><a href="modules.html"><span>Categories</span></a></li>
<li><a href="annotated.html"><span>Classes</span></a></li>
<li><a href="files.html"><span>Files</span></a></li>
</ul>
</div>
<div id="nav-path" class="navpath">
<ul>
<li class="navelem"><a class="el" href="index.html">Documentation</a></li><li class="navelem"><a class="el" href="page_topics.html">Programming Guides</a></li> </ul>
</div>
</div><!-- top -->
<div class="header">
<div class="headertitle">
<div class="title"><a class="el" href="classwx_m_b_conv.html" title="This class is the base class of a hierarchy of classes capable of converting text strings between mul...">wxMBConv</a> Overview </div> </div>
</div><!--header-->
<div class="contents">
<div class="toc"><h3>Table of Contents</h3>
<ul><li class="level1"><a href="#overview_mbconv_need">Background: The Need for Conversion</a></li>
<li class="level1"><a href="#overview_mbconv_string">Background: The wxString Class</a></li>
<li class="level1"><a href="#overview_mbconv_classes">wxMBConv Classes</a></li>
<li class="level1"><a href="#overview_mbconv_objects">wxMBConv Objects</a></li>
<li class="level1"><a href="#overview_mbconv_csconv">wxCSConv</a></li>
<li class="level1"><a href="#overview_mbconv_converting">Converting Strings</a></li>
<li class="level1"><a href="#overview_mbconv_buffers">Converting Buffers</a></li>
</ul>
</div>
<div class="textblock"><p>The <a class="el" href="classwx_m_b_conv.html" title="This class is the base class of a hierarchy of classes capable of converting text strings between mul...">wxMBConv</a> classes in wxWidgets enable an Unicode-aware application to easily convert between Unicode and the variety of 8-bit encoding systems still in use.</p>
<dl class="section see"><dt>See Also</dt><dd><a class="el" href="group__group__class__conv.html">Text Conversion</a></dd></dl>
<h1><a class="anchor" id="overview_mbconv_need"></a>
Background: The Need for Conversion</h1>
<p>As programs are becoming more and more globalized, and users exchange documents across country boundaries as never before, applications increasingly need to take into account all the different character sets in use around the world. It is no longer enough to just depend on the default byte-sized character set that computers have traditionally used.</p>
<p>A few years ago, a solution was proposed: the Unicode standard. Able to contain the complete set of characters in use in one unified global coding system, it would resolve the character set problems once and for all.</p>
<p>But it hasn't happened yet, and the migration towards Unicode has created new challenges, resulting in "compatibility encodings" such as UTF-8. A large number of systems out there still depends on the old 8-bit encodings, hampered by the huge amounts of legacy code still widely deployed. Even sending Unicode data from one Unicode-aware system to another may need encoding to an 8-bit multibyte encoding (UTF-7 or UTF-8 is typically used for this purpose), to pass unhindered through any traditional transport channels.</p>
<h1><a class="anchor" id="overview_mbconv_string"></a>
Background: The wxString Class</h1>
<dl class="todo"><dt><b><a class="el" href="todo.html#_todo000005">Todo:</a></b></dt><dd>rewrite this overview; it's not up2date with <a class="el" href="classwx_string.html" title="String class for passing textual data to or receiving it from wxWidgets.">wxString</a> changes</dd></dl>
<p>If you have compiled wxWidgets in Unicode mode, the wxChar type will become identical to wchar_t rather than char, and a <a class="el" href="classwx_string.html" title="String class for passing textual data to or receiving it from wxWidgets.">wxString</a> stores wxChars. Hence, all <a class="el" href="classwx_string.html" title="String class for passing textual data to or receiving it from wxWidgets.">wxString</a> manipulation in your application will then operate on Unicode strings, and almost as easily as working with ordinary char strings (you just need to remember to use the <a class="el" href="group__group__funcmacro__string.html#ga437ea6ba615b75dac8603e96ec864160" title="This macro can be used with character and string literals (in other words, 'x' or "foo") to automatic...">wxT()</a> macro to encapsulate any string literals).</p>
<p>But often, your environment doesn't want Unicode strings. You could be sending data over a network, or processing a text file for some other application. You need a way to quickly convert your easily-handled Unicode data to and from a traditional 8-bit encoding. And this is what the <a class="el" href="classwx_m_b_conv.html" title="This class is the base class of a hierarchy of classes capable of converting text strings between mul...">wxMBConv</a> classes do.</p>
<h1><a class="anchor" id="overview_mbconv_classes"></a>
wxMBConv Classes</h1>
<p>The base class for all these conversions is the <a class="el" href="classwx_m_b_conv.html" title="This class is the base class of a hierarchy of classes capable of converting text strings between mul...">wxMBConv</a> class (which itself implements standard libc locale conversion). Derived classes include wxMBConvLibc, several different wxMBConvUTFxxx classes, and <a class="el" href="classwx_c_s_conv.html" title="This class converts between any character set supported by the system and Unicode.">wxCSConv</a>, which implement different kinds of conversions. You can also derive your own class for your own custom encoding and use it, should you need it. All you need to do is override the MB2WC and WC2MB methods.</p>
<h1><a class="anchor" id="overview_mbconv_objects"></a>
wxMBConv Objects</h1>
<p>Several of the wxWidgets-provided <a class="el" href="classwx_m_b_conv.html" title="This class is the base class of a hierarchy of classes capable of converting text strings between mul...">wxMBConv</a> classes have predefined instances (wxConvLibc, wxConvFileName, wxConvUTF7, wxConvUTF8, wxConvLocal). You can use these predefined objects directly, or you can instantiate your own objects.</p>
<p>A variable, wxConvCurrent, points to the conversion object that the user interface is supposed to use, in the case that the user interface is not Unicode-based (like with GTK+ 1.2). By default, it points to wxConvLibc or wxConvLocal, depending on which works best on the current platform.</p>
<h1><a class="anchor" id="overview_mbconv_csconv"></a>
wxCSConv</h1>
<p>The <a class="el" href="classwx_c_s_conv.html" title="This class converts between any character set supported by the system and Unicode.">wxCSConv</a> class is special because when it is instantiated, you can tell it which character set it should use, which makes it meaningful to keep many instances of them around, each with a different character set (or you can create a <a class="el" href="classwx_c_s_conv.html" title="This class converts between any character set supported by the system and Unicode.">wxCSConv</a> instance on the fly).</p>
<p>The predefined <a class="el" href="classwx_c_s_conv.html" title="This class converts between any character set supported by the system and Unicode.">wxCSConv</a> instance, wxConvLocal, is preset to use the default user character set, but you should rarely need to use it directly, it is better to go through wxConvCurrent.</p>
<h1><a class="anchor" id="overview_mbconv_converting"></a>
Converting Strings</h1>
<p>Once you have chosen which object you want to use to convert your text, here is how you would use them with <a class="el" href="classwx_string.html" title="String class for passing textual data to or receiving it from wxWidgets.">wxString</a>. These examples all assume that you are using a Unicode build of wxWidgets, although they will still compile in a non-Unicode build (they just won't convert anything).</p>
<p>Example 1: Constructing a <a class="el" href="classwx_string.html" title="String class for passing textual data to or receiving it from wxWidgets.">wxString</a> from input in current encoding.</p>
<div class="fragment"><div class="line"><a class="code" href="classwx_string.html" title="String class for passing textual data to or receiving it from wxWidgets.">wxString</a> str(input_data, *wxConvCurrent);</div>
</div><!-- fragment --><p>Example 2: Input in UTF-8 encoding.</p>
<div class="fragment"><div class="line"><a class="code" href="classwx_string.html" title="String class for passing textual data to or receiving it from wxWidgets.">wxString</a> str(input_data, wxConvUTF8);</div>
</div><!-- fragment --><p>Example 3: Input in KOI8-R. Construction of <a class="el" href="classwx_c_s_conv.html" title="This class converts between any character set supported by the system and Unicode.">wxCSConv</a> instance on the fly.</p>
<div class="fragment"><div class="line"><a class="code" href="classwx_string.html" title="String class for passing textual data to or receiving it from wxWidgets.">wxString</a> str(input_data, <a class="code" href="classwx_c_s_conv.html" title="This class converts between any character set supported by the system and Unicode.">wxCSConv</a>(<a class="code" href="group__group__funcmacro__string.html#ga437ea6ba615b75dac8603e96ec864160" title="This macro can be used with character and string literals (in other words, 'x' or "foo") to automatic...">wxT</a>(<span class="stringliteral">"koi8-r"</span>)));</div>
</div><!-- fragment --><p>Example 4: Printing a <a class="el" href="classwx_string.html" title="String class for passing textual data to or receiving it from wxWidgets.">wxString</a> to stdout in UTF-8 encoding.</p>
<div class="fragment"><div class="line">puts(str.mb_str(wxConvUTF8));</div>
</div><!-- fragment --><p>Example 5: Printing a <a class="el" href="classwx_string.html" title="String class for passing textual data to or receiving it from wxWidgets.">wxString</a> to stdout in custom encoding. Using preconstructed <a class="el" href="classwx_c_s_conv.html" title="This class converts between any character set supported by the system and Unicode.">wxCSConv</a> instance.</p>
<div class="fragment"><div class="line"><a class="code" href="classwx_c_s_conv.html" title="This class converts between any character set supported by the system and Unicode.">wxCSConv</a> cust(user_encoding);</div>
<div class="line">printf(<span class="stringliteral">"Data: %s\n"</span>, (<span class="keyword">const</span> <span class="keywordtype">char</span>*) str.mb_str(cust));</div>
</div><!-- fragment --><dl class="section note"><dt>Note</dt><dd>Since mb_str() returns a temporary <a class="el" href="classwx_char_buffer.html" title="This is a specialization of wxCharTypeBuffer<T> for char type.">wxCharBuffer</a> to hold the result of the conversion, you need to explicitly cast it to const char* if you use it in a vararg context (like with printf).</dd></dl>
<h1><a class="anchor" id="overview_mbconv_buffers"></a>
Converting Buffers</h1>
<p>If you have specialized needs, or just don't want to use <a class="el" href="classwx_string.html" title="String class for passing textual data to or receiving it from wxWidgets.">wxString</a>, you can also use the conversion methods of the conversion objects directly. This can even be useful if you need to do conversion in a non-Unicode build of wxWidgets; converting a string from UTF-8 to the current encoding should be possible by doing this:</p>
<div class="fragment"><div class="line"><a class="code" href="classwx_string.html" title="String class for passing textual data to or receiving it from wxWidgets.">wxString</a> str(wxConvUTF8.cMB2WC(input_data), *wxConvCurrent);</div>
</div><!-- fragment --><p>Here, cMB2WC of the UTF8 object returns a <a class="el" href="classwx_w_char_buffer.html" title="This is a specialization of wxCharTypeBuffer<T> for wchar_t type.">wxWCharBuffer</a> containing a Unicode string. The <a class="el" href="classwx_string.html" title="String class for passing textual data to or receiving it from wxWidgets.">wxString</a> constructor then converts it back to an 8-bit character set using the passed conversion object, *wxConvCurrent. (In a Unicode build of wxWidgets, the constructor ignores the passed conversion object and retains the Unicode data.)</p>
<p>This could also be done by first making a <a class="el" href="classwx_string.html" title="String class for passing textual data to or receiving it from wxWidgets.">wxString</a> of the original data:</p>
<div class="fragment"><div class="line"><a class="code" href="classwx_string.html" title="String class for passing textual data to or receiving it from wxWidgets.">wxString</a> input_str(input_data);</div>
<div class="line"><a class="code" href="classwx_string.html" title="String class for passing textual data to or receiving it from wxWidgets.">wxString</a> str(input_str.wc_str(wxConvUTF8), *wxConvCurrent);</div>
</div><!-- fragment --><p>To print a wxChar buffer to a non-Unicode stdout:</p>
<div class="fragment"><div class="line">printf(<span class="stringliteral">"Data: %s\n"</span>, (<span class="keyword">const</span> <span class="keywordtype">char</span>*) wxConvCurrent->cWX2MB(unicode_data));</div>
</div><!-- fragment --><p>If you need to do more complex processing on the converted data, you may want to store the temporary buffer in a local variable:</p>
<div class="fragment"><div class="line"><span class="keyword">const</span> wxWX2MBbuf tmp_buf = wxConvCurrent->cWX2MB(unicode_data);</div>
<div class="line"><span class="keyword">const</span> <span class="keywordtype">char</span> *tmp_str = (<span class="keyword">const</span> <span class="keywordtype">char</span>*) tmp_buf;</div>
<div class="line">printf(<span class="stringliteral">"Data: %s\n"</span>, tmp_str);</div>
<div class="line">process_data(tmp_str);</div>
</div><!-- fragment --><p>If a conversion had taken place in cWX2MB (i.e. in a Unicode build), the buffer will be deallocated as soon as tmp_buf goes out of scope. The macro wxWX2MBbuf reflects the correct return value of cWX2MB (either char* or <a class="el" href="classwx_char_buffer.html" title="This is a specialization of wxCharTypeBuffer<T> for char type.">wxCharBuffer</a>), except for the const. </p>
</div></div><!-- contents -->
<address class="footer">
<small>
Generated on Thu Nov 27 2014 13:46:42 for wxWidgets by <a href="http://www.doxygen.org/index.html" target="_new">Doxygen</a> 1.8.2
</small>
</address>
<script src="wxwidgets.js" type="text/javascript"></script>
</div><!-- #page_container -->
</body>
</html>
|