X-Git-Url: https://git.saurik.com/wxWidgets.git/blobdiff_plain/d17f05afeb41c64fab410cd3178a78596da55e38..d441742626a54f7dd10888ebac5abcc0e55f9234:/docs/latex/wx/encconv.tex diff --git a/docs/latex/wx/encconv.tex b/docs/latex/wx/encconv.tex index 2c45952bda..f24df2dd1e 100644 --- a/docs/latex/wx/encconv.tex +++ b/docs/latex/wx/encconv.tex @@ -5,27 +5,51 @@ \section{\class{wxEncodingConverter}}\label{wxencodingconverter} -This class is capable of converting strings between any two +This class is capable of converting strings between 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 wxWidgets with wxUSE\_WCHAR\_T set to 1). Only a limited subset +of encodings is supported by wxEncodingConverter: +{\tt wxFONTENCODING\_ISO8859\_1..15}, {\tt wxFONTENCODING\_CP1250..1257} and +{\tt wxFONTENCODING\_KOI8}. + +\wxheading{Note} + +Please use \helpref{wxMBConv classes}{mbconvclasses} instead +if possible. \helpref{wxCSConv}{wxcsconv} has much better support for various +encodings than wxEncodingConverter. wxEncodingConverter is useful only +if you rely on {\tt wxCONVERT\_SUBSTITUTE} mode of operation (see +\helpref{Init}{wxencodingconverterinit}). \wxheading{Derived from} \helpref{wxObject}{wxobject} +\wxheading{Include files} + + + +\wxheading{See also} + +\helpref{wxFontMapper}{wxfontmapper}, +\helpref{wxMBConv}{wxmbconv}, +\helpref{Writing non-English applications}{nonenglishoverview} + + \latexignore{\rtfignore{\wxheading{Members}}} + \membersection{wxEncodingConverter::wxEncodingConverter}\label{wxencodingconverterwxencodingconverter} \func{}{wxEncodingConverter}{\void} Constructor. + \membersection{wxEncodingConverter::Init}\label{wxencodingconverterinit} \func{bool}{Init}{\param{wxFontEncoding }{input\_enc}, \param{wxFontEncoding }{output\_enc}, \param{int }{method = wxCONVERT\_STRICT}} -Initialize convertion. Both output or input encoding may +Initialize conversion. Both output or input encoding may be wxFONTENCODING\_UNICODE, but only if wxUSE\_ENCODING is set to 1. All subsequent calls to \helpref{Convert()}{wxencodingconverterconvert} will interpret its argument @@ -38,35 +62,74 @@ cannot be converted because it does not exist in output encoding: \begin{twocollist}\itemsep=0pt \twocolitem{{\bf wxCONVERT\_STRICT}}{follow behaviour of GNU Recode - -just copy unconvertable characters to output and don't change them +just copy unconvertible characters to output and don't change them (its integer value will stay the same)} \twocolitem{{\bf wxCONVERT\_SUBSTITUTE}}{try some (lossy) substitutions -- e.g. replace unconvertable latin capitals with acute by ordinary +- e.g. replace unconvertible latin capitals with acute by ordinary capitals, replace en-dash or em-dash by '-' etc.} \end{twocollist} -Both modes gurantee that output string will have same length +Both modes guarantee that output string will have same length as input string. \wxheading{Return value} -FALSE if given conversion is impossible, TRUE otherwise +false if given conversion is impossible, true otherwise (conversion may be impossible either if you try to convert -to Unicode with non-Unicode build of wxWindows or if input +to Unicode with non-Unicode build of wxWidgets or if input or output encoding is not supported.) + +\membersection{wxEncodingConverter::CanConvert}\label{wxencodingconvertercanconvert} + +\func{static bool}{CanConvert}{\param{wxFontEncoding }{encIn}, \param{wxFontEncoding }{encOut}} + +Return true if (any text in) multibyte encoding \arg{encIn} can be converted to +another one ({\it encOut}) losslessly. + +Do not call this method with \texttt{wxFONTENCODING\_UNICODE} as either +parameter, it doesn't make sense (always works in one sense and always depends +on the text to convert in the other). + + \membersection{wxEncodingConverter::Convert}\label{wxencodingconverterconvert} -\func{wxString}{Convert}{\param{const wxString\& }{input}} +\constfunc{bool}{Convert}{\param{const char* }{input}, \param{char* }{output}} + +\constfunc{bool}{Convert}{\param{const wchar\_t* }{input}, \param{wchar\_t* }{output}} + +\constfunc{bool}{Convert}{\param{const char* }{input}, \param{wchar\_t* }{output}} + +\constfunc{bool}{Convert}{\param{const wchar\_t* }{input}, \param{char* }{output}} + +Convert input string according to settings passed to +\helpref{Init}{wxencodingconverterinit} and writes the result to {\it output}. + +\constfunc{bool}{Convert}{\param{char* }{str}} + +\constfunc{bool}{Convert}{\param{wchar\_t* }{str}} -\func{void}{Convert}{\param{const wxChar* }{input}, \param{wxChar* }{output}} +Convert input string according to settings passed to +\helpref{Init}{wxencodingconverterinit} in-place, i.e. write the result to the +same memory area. -\func{void}{Convert}{\param{wxChar* }{str}} +All of the versions above return \true if the conversion was lossless and +\false if at least one of the characters couldn't be converted and was replaced +with {\tt '?'} in the output. Note that if {\tt wxCONVERT\_SUBSTITUTE} was +passed to \helpref{Init}{wxencodingconverterinit}, substitution is considered +lossless operation. -\func{void}{Convert}{\param{const char* }{input}, \param{wxChar* }{output}} +\constfunc{wxString}{Convert}{\param{const wxString\& }{input}} + +Convert wxString and return new wxString object. + +\wxheading{Notes} + +You must call \helpref{Init}{wxencodingconverterinit} before using this method! + +{\tt wchar\_t} versions of the method are not available if wxWidgets was compiled +with {\tt wxUSE\_WCHAR\_T} set to 0. -Convert input string according to settings passed to \helpref{Init}{wxencodingconverterinit}. -Note that you must call Init before using Convert! \membersection{wxEncodingConverter::GetPlatformEquivalents}\label{wxencodingconvertergetplatformequivalents} @@ -83,7 +146,7 @@ under given platform. Supported platforms: \item wxPLATFORM\_CURRENT \end{itemize} -wxPLATFORM\_CURRENT means the plaform this binary was compiled for. +wxPLATFORM\_CURRENT means the platform this binary was compiled for. Examples: @@ -97,10 +160,10 @@ unix CP1252 {ISO8859_1,ISO8859_15} \end{verbatim} Equivalence is defined in terms of convertibility: -2 encodings are equivalent if you can convert text between -then without loosing information (it may - and will - happen -that you loose special chars like quotation marks or em-dashes -but you shouldn't loose any diacritics and language-specific +two encodings are equivalent if you can convert text between +then without losing information (it may - and will - happen +that you lose special chars like quotation marks or em-dashes +but you shouldn't lose any diacritics and language-specific characters when converting between equivalent encodings). Remember that this function does {\bf NOT} check for presence of @@ -111,16 +174,17 @@ encodings. (It usually returns only one encoding.) \begin{itemize}\itemsep=0pt \item Note that argument {\it enc} itself may be present in the returned array, -so that you can - as a side effect - detect whether the +so that you can, as a side-effect, detect whether the encoding is native for this platform or not. -\item helpref{Convert}{wxencodingconverterconvert} is not limited to -converting between equivalent encodings, it can convert between arbitrary -two encodings. -\item If {\it enc} is present in returned array, then it is {\bf always} first +\item \helpref{Convert}{wxencodingconverterconvert} is not limited to +converting between equivalent encodings, it can convert between two arbitrary +encodings. +\item If {\it enc} is present in the returned array, then it is {\bf always} the first item of it. -\item Please note that the returned array may not contain any items at all. +\item Please note that the returned array may contain no items at all. \end{itemize} + \membersection{wxEncodingConverter::GetAllEquivalents}\label{wxencodingconvertergetallequivalents} \func{static wxFontEncodingArray}{GetAllEquivalents}{\param{wxFontEncoding }{enc}} @@ -128,7 +192,7 @@ item of it. Similar to \helpref{GetPlatformEquivalents}{wxencodingconvertergetplatformequivalents}, but this one will return ALL -equivalent encodings, regardless the platform, and including itself. +equivalent encodings, regardless of the platform, and including itself. This platform's encodings are before others in the array. And again, if {\it enc} is in the array, it is the very first item in it.