added images for topic overviews

[wxWidgets.git] / docs / doxygen / overviews / mbconvclasses.h

diff --git a/docs/doxygen/overviews/mbconvclasses.h b/docs/doxygen/overviews/mbconvclasses.h
index a90907a02adf63934bad4e54213b124098f6bae2..28d80c4792a3f3e80ab26933b513e7e8e08c4e32 100644 (file)
--- a/docs/doxygen/overviews/mbconvclasses.h
+++ b/docs/doxygen/overviews/mbconvclasses.h
@@ -7,12 +7,12 @@
 /////////////////////////////////////////////////////////////////////////////
 
 /*!
 /////////////////////////////////////////////////////////////////////////////
 
 /*!

- 
+

  @page mbconvclasses_overview wxMBConv classes overview
  @page mbconvclasses_overview wxMBConv classes overview

- 
- Classes: #wxMBConv, wxMBConvLibc, 
- #wxMBConvUTF7, #wxMBConvUTF8, 
- #wxCSConv, 
+
+ Classes: #wxMBConv, wxMBConvLibc,
+ #wxMBConvUTF7, #wxMBConvUTF8,
+ #wxCSConv,

  #wxMBConvUTF16, #wxMBConvUTF32
  The wxMBConv classes in wxWidgets enable an Unicode-aware application to
  easily convert between Unicode and the variety of 8-bit encoding systems still
  #wxMBConvUTF16, #wxMBConvUTF32
  The wxMBConv classes in wxWidgets enable an Unicode-aware application to
  easily convert between Unicode and the variety of 8-bit encoding systems still


@@ -24,10 +24,10 @@
  #wxCSConv
  @ref convertingstrings_overview
  @ref convertingbuffers_overview
  #wxCSConv
  @ref convertingstrings_overview
  @ref convertingbuffers_overview

- 
- 
+
+

  @section needforconversion Background: The need for conversion
  @section needforconversion Background: The need for conversion

- 
+

  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
  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


@@ -43,9 +43,9 @@
  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.
  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.

- 
+

  @section conversionandwxstring Background: The wxString class
  @section conversionandwxstring Background: The wxString class

- 
+

  If you have compiled wxWidgets in Unicode mode, the wxChar type will become
  identical to wchar_t rather than char, and a wxString stores wxChars. Hence,
  all wxString manipulation in your application will then operate on Unicode
  If you have compiled wxWidgets in Unicode mode, the wxChar type will become
  identical to wchar_t rather than char, and a wxString stores wxChars. Hence,
  all wxString manipulation in your application will then operate on Unicode


@@ -56,18 +56,18 @@
  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 wxMBConv classes do.
  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 wxMBConv classes do.

- 
+

  @section wxmbconvclasses wxMBConv classes
  @section wxmbconvclasses wxMBConv classes

- 
+

  The base class for all these conversions is the wxMBConv class (which itself
  implements standard libc locale conversion). Derived classes include
  wxMBConvLibc, several different wxMBConvUTFxxx classes, and wxCSConv, 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.
  The base class for all these conversions is the wxMBConv class (which itself
  implements standard libc locale conversion). Derived classes include
  wxMBConvLibc, several different wxMBConvUTFxxx classes, and wxCSConv, 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.

- 
+

  @section wxmbconvobjects wxMBConv objects
  @section wxmbconvobjects wxMBConv objects

- 
+

  Several of the wxWidgets-provided wxMBConv classes have predefined instances
  (wxConvLibc, wxConvFileName, wxConvUTF7, wxConvUTF8, wxConvLocal). You can use
  these predefined objects directly, or you can instantiate your own objects.
  Several of the wxWidgets-provided wxMBConv classes have predefined instances
  (wxConvLibc, wxConvFileName, wxConvUTF7, wxConvUTF8, wxConvLocal). You can use
  these predefined objects directly, or you can instantiate your own objects.


@@ -75,9 +75,9 @@
  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.
  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.

- 
+

  @section wxcsconvclass wxCSConv
  @section wxcsconvclass wxCSConv

- 
+

  The wxCSConv 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
  The wxCSConv 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


@@ -85,94 +85,94 @@
  The predefined wxCSConv 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.
  The predefined wxCSConv 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.

- 
+

  @section convertingstrings Converting strings
  @section convertingstrings Converting strings

- 
+

  Once you have chosen which object you want to use to convert your text,
  here is how you would use them with wxString. 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).
  Example 1: Constructing a wxString from input in current encoding.
  Once you have chosen which object you want to use to convert your text,
  here is how you would use them with wxString. 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).
  Example 1: Constructing a wxString from input in current encoding.

- 
+

  @code
  wxString str(input_data, *wxConvCurrent);
  @endcode
  @code
  wxString str(input_data, *wxConvCurrent);
  @endcode

- 
+

  Example 2: Input in UTF-8 encoding.
  Example 2: Input in UTF-8 encoding.

- 
+

  @code
  wxString str(input_data, wxConvUTF8);
  @endcode
  @code
  wxString str(input_data, wxConvUTF8);
  @endcode

- 
+

  Example 3: Input in KOI8-R. Construction of wxCSConv instance on the fly.
  Example 3: Input in KOI8-R. Construction of wxCSConv instance on the fly.

- 
+

  @code
  wxString str(input_data, wxCSConv(wxT("koi8-r")));
  @endcode
  @code
  wxString str(input_data, wxCSConv(wxT("koi8-r")));
  @endcode

- 
+

  Example 4: Printing a wxString to stdout in UTF-8 encoding.
  Example 4: Printing a wxString to stdout in UTF-8 encoding.

- 
+

  @code
  puts(str.mb_str(wxConvUTF8));
  @endcode
  @code
  puts(str.mb_str(wxConvUTF8));
  @endcode

- 
+

  Example 5: Printing a wxString to stdout in custom encoding.
  Using preconstructed wxCSConv instance.
  Example 5: Printing a wxString to stdout in custom encoding.
  Using preconstructed wxCSConv instance.

- 
+

  @code
  wxCSConv cust(user_encoding);
  printf("Data: %s\n", (const char*) str.mb_str(cust));
  @endcode
  @code
  wxCSConv cust(user_encoding);
  printf("Data: %s\n", (const char*) str.mb_str(cust));
  @endcode

- 
+

  Note: Since mb_str() returns a temporary wxCharBuffer 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).
  Note: Since mb_str() returns a temporary wxCharBuffer 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).

- 
+

  @section convertingbuffers Converting buffers
  @section convertingbuffers Converting buffers

- 
+

  If you have specialized needs, or just don't want to use wxString, 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:
  If you have specialized needs, or just don't want to use wxString, 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:

- 
+

  @code
  wxString str(wxConvUTF8.cMB2WC(input_data), *wxConvCurrent);
  @endcode
  @code
  wxString str(wxConvUTF8.cMB2WC(input_data), *wxConvCurrent);
  @endcode

- 
+

  Here, cMB2WC of the UTF8 object returns a wxWCharBuffer containing a Unicode
  string. The wxString 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.)
  This could also be done by first making a wxString of the original data:
  Here, cMB2WC of the UTF8 object returns a wxWCharBuffer containing a Unicode
  string. The wxString 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.)
  This could also be done by first making a wxString of the original data:

- 
+

  @code
  wxString input_str(input_data);
  wxString str(input_str.wc_str(wxConvUTF8), *wxConvCurrent);
  @endcode
  @code
  wxString input_str(input_data);
  wxString str(input_str.wc_str(wxConvUTF8), *wxConvCurrent);
  @endcode

- 
+

  To print a wxChar buffer to a non-Unicode stdout:
  To print a wxChar buffer to a non-Unicode stdout:

- 
+

  @code
  printf("Data: %s\n", (const char*) wxConvCurrent-cWX2MB(unicode_data));
  @endcode
  @code
  printf("Data: %s\n", (const char*) wxConvCurrent-cWX2MB(unicode_data));
  @endcode

- 
+

  If you need to do more complex processing on the converted data, you
  may want to store the temporary buffer in a local variable:
  If you need to do more complex processing on the converted data, you
  may want to store the temporary buffer in a local variable:

- 
+

  @code
  const wxWX2MBbuf tmp_buf = wxConvCurrent-cWX2MB(unicode_data);
  const char *tmp_str = (const char*) tmp_buf;
  printf("Data: %s\n", tmp_str);
  process_data(tmp_str);
  @endcode
  @code
  const wxWX2MBbuf tmp_buf = wxConvCurrent-cWX2MB(unicode_data);
  const char *tmp_str = (const char*) tmp_buf;
  printf("Data: %s\n", tmp_str);
  process_data(tmp_str);
  @endcode

- 
+

  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 wxCharBuffer), except for the const.)
  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 wxCharBuffer), except for the const.)

- 
+

  */
  */

- 
- 
+
+