A few documentation updates, cross-references, properties of UTF-8,

wx??2??buf macros.


git-svn-id: https://svn.wxwidgets.org/svn/wx/wxWidgets/branches/WX_2_2_BRANCH@7032 c3d73ce0-8a6f-49c7-b76d-6d57e0e08775

docs/latex/wx/csconv.tex

@@ -21,7 +21,8 @@ default user character set.
 \wxheading{See also}
 
 \helpref{wxMBConv}{wxmbconv}, 
-\helpref{wxEncodingConverter}{wxencodingconverter}
+\helpref{wxEncodingConverter}{wxencodingconverter}, 
+\helpref{wxMBConv classes overview}{mbconvclasses}
 
 \latexignore{\rtfignore{\wxheading{Members}}}
 

docs/latex/wx/encconv.tex

@@ -7,7 +7,7 @@
 
 This class is capable of converting strings between any two
 8-bit encodings/charsets. It can also convert from/to Unicode (but only
-if you compiled wxWindows with wxUSE\_UNICODE set to 1).
+if you compiled wxWindows with wxUSE\_WCHAR\_T set to 1).
 
 \wxheading{Derived from}
 
@@ -20,6 +20,7 @@ if you compiled wxWindows with wxUSE\_UNICODE set to 1).
 \wxheading{See also}
 
 \helpref{wxFontMapper}{wxfontmapper}, 
+\helpref{wxMBConv}{wxmbconv}, 
 \helpref{Writing non-English applications}{nonenglishoverview}
 
 

docs/latex/wx/mbcnvfil.tex

@@ -29,6 +29,10 @@ FILE *fil = fopen(wxFNCONV(name), "r");
 
 <wx/strconv.h>
 
+\wxheading{See also}
+
+\helpref{wxMBConv classes overview}{mbconvclasses}
+
 \latexignore{\rtfignore{\wxheading{Members}}}
 
 

docs/latex/wx/mbcnvut7.tex

@@ -20,7 +20,8 @@ Unfortunately, this class is not quite implemented yet.
 
 \wxheading{See also}
 
-\helpref{wxMBConvUTF8}{wxmbconvutf8}
+\helpref{wxMBConvUTF8}{wxmbconvutf8}, 
+\helpref{wxMBConv classes overview}{mbconvclasses}
 
 \latexignore{\rtfignore{\wxheading{Members}}}
 

docs/latex/wx/mbcnvut8.tex

@@ -19,7 +19,29 @@ It has one predefined instance, {\bf wxConvUTF8}.
 
 \wxheading{See also}
 
-\helpref{wxMBConvUTF7}{wxmbconvutf7}
+\helpref{wxMBConvUTF7}{wxmbconvutf7}, 
+\helpref{wxMBConv classes overview}{mbconvclasses}
+
+\wxheading{Remarks}
+
+UTF-8 is a compatibility encoding used to encode Unicode text into anything that was
+originally written for 8-bit strings, including (but not limited to) filenames, transfer
+protocols, and database fields. Notable properties include:
+
+\begin{itemize}
+\item Variable-length encoding able to encode up to 31 bits per character
+\item ASCII characters (character values under 128) are encoded as plain ASCII
+(1 byte per character)
+\item Null bytes do not occur in the encoding, except when there's an actual Unicode
+null character
+\item Preserves sort ordering for plain 8-bit comparison routines like strcmp()
+\item High bit patterns unambiguates character boundaries, and makes it easy to
+detect whether a string is encoded with UTF-8 or not
+\end{itemize}
+
+All of these properties make UTF-8 a very favorable solution in any situation
+where full Unicode character support is desired while remaining compatible with
+code written with only 8-bit extended-ASCII characters in mind.
 
 \latexignore{\rtfignore{\wxheading{Members}}}
 

docs/latex/wx/mbconv.tex

@@ -22,7 +22,8 @@ No base class
 \wxheading{See also}
 
 \helpref{wxCSConv}{wxcsconv}, 
-\helpref{wxEncodingConverter}{wxencodingconverter}
+\helpref{wxEncodingConverter}{wxencodingconverter}, 
+\helpref{wxMBConv classes overview}{mbconvclasses}
 
 \latexignore{\rtfignore{\wxheading{Members}}}
 
@@ -70,7 +71,8 @@ allocating a temporary wxCharBuffer to hold the result.
 Converts from multibyte encoding to the current wxChar type
 (which depends on whether wxUSE\_UNICODE is set to 1). If wxChar is char,
 it returns the parameter unaltered. If wxChar is wchar\_t, it returns the
-result in a wxWCharBuffer.
+result in a wxWCharBuffer. The macro wxMB2WXbuf is defined as the correct
+return type (without const).
 
 \membersection{wxMBConv::cWX2MB}\label{wxmbconvcwx2mb}
 
@@ -80,7 +82,8 @@ result in a wxWCharBuffer.
 
 Converts from the current wxChar type to multibyte encoding. If wxChar is char,
 it returns the parameter unaltered. If wxChar is wchar\_t, it returns the
-result in a wxCharBuffer.
+result in a wxCharBuffer. The macro wxWX2MBbuf is defined as the correct
+return type (without const).
 
 \membersection{wxMBConv::cWC2WX}\label{wxmbconvcwc2wx}
 
@@ -90,7 +93,8 @@ result in a wxCharBuffer.
 
 Converts from Unicode to the current wxChar type. If wxChar is wchar\_t,
 it returns the parameter unaltered. If wxChar is char, it returns the
-result in a wxCharBuffer.
+result in a wxCharBuffer. The macro wxWC2WXbuf is defined as the correct
+return type (without const).
 
 \membersection{wxMBConv::cWX2WC}\label{wxmbconvcwx2wc}
 
@@ -100,5 +104,5 @@ result in a wxCharBuffer.
 
 Converts from the current wxChar type to Unicode. If wxChar is wchar\_t,
 it returns the parameter unaltered. If wxChar is char, it returns the
-result in a wxWCharBuffer.
-
+result in a wxWCharBuffer. The macro wxWX2WCbuf is defined as the correct
+return type (without const).

docs/latex/wx/tmbconv.tex

@@ -9,7 +9,7 @@
 %% Licence:     wxWindows license
 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
 
-\section{wxMBConv classes}\label{mbconvclasses}
+\section{wxMBConv classes overview}\label{mbconvclasses}
 
 Classes: \helpref{wxMBConv}{wxmbconv}, \helpref{wxMBConvFile}{wxmbconvfile}, 
 \helpref{wxMBConvUTF7}{wxmbconvutf7}, \helpref{wxMBConvUTF8}{wxmbconvutf8}, 
@@ -122,7 +122,7 @@ Using preconstructed wxCSConv instance.
 
 \begin{verbatim}
 wxCSConv cust(user_encoding);
-printf("Data: %s\\n", (const char*) str.mb_str(cust));
+printf("Data: %s\n", (const char*) str.mb_str(cust));
 \end{verbatim}
 
 Note: Since mb_str() returns a temporary wxCharBuffer to hold the result
@@ -147,9 +147,30 @@ set using the passed conversion object, *wxConvCurrent. (In a Unicode build
 of wxWindows, 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:
+
+\begin{verbatim}
+wxString input_str(input_data);
+wxString str(input_str.wc_str(wxConvUTF8), *wxConvCurrent);
+\end{verbatim}
+
 To print a wxChar buffer to a non-Unicode stdout:
 
 \begin{verbatim}
-printf("Data: %s\\n", (const char*) wxConvCurrent->cWX2MB(unicode_data));
+printf("Data: %s\n", (const char*) wxConvCurrent->cWX2MB(unicode_data));
 \end{verbatim}
 
+If you need to do more complex processing on the converted data, you
+may want to store the temporary buffer in a local variable:
+
+\begin{verbatim}
+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);
+\end{verbatim}
+
+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.)