[wxWidgets.git] / docs / latex / wx / encconv.tex

%
% automatically generated by HelpGen from
% encconv.h at 30/Dec/99 18:45:16
%

\section{\class{wxEncodingConverter}}\label{wxencodingconverter}

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\_WCHAR\_T set to 1).

\wxheading{Derived from}

\helpref{wxObject}{wxobject}

\wxheading{Include files}

<wx/encconv.h>

\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
be wxFONTENCODING\_UNICODE, but only if wxUSE\_ENCODING is set to 1.
All subsequent calls to \helpref{Convert()}{wxencodingconverterconvert} 
will interpret its argument
as a string in {\it input\_enc} encoding and will output string in 
{\it output\_enc} encoding.
You must call this method before calling Convert. You may call 
it more than once in order to switch to another conversion.
{\it Method} affects behaviour of Convert() in case input character
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 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 unconvertible latin capitals with acute by ordinary
capitals, replace en-dash or em-dash by '-' etc.}
\end{twocollist}

Both modes guarantee that output string will have same length
as input string.

\wxheading{Return value} 

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
or output encoding is not supported.)

\membersection{wxEncodingConverter::Convert}\label{wxencodingconverterconvert}

\func{wxString}{Convert}{\param{const wxString\& }{input}}

\func{void}{Convert}{\param{const wxChar* }{input}, \param{wxChar* }{output}}

\func{void}{Convert}{\param{wxChar* }{str}}

\func{void}{Convert}{\param{const char* }{input}, \param{wxChar* }{output}}

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}

\func{static wxFontEncodingArray}{GetPlatformEquivalents}{\param{wxFontEncoding }{enc}, \param{int }{platform = wxPLATFORM\_CURRENT}}

Return equivalents for given font that are used
under given platform. Supported platforms:

\begin{itemize}\itemsep=0pt
\item wxPLATFORM\_UNIX
\item wxPLATFORM\_WINDOWS
\item wxPLATFORM\_OS2
\item wxPLATFORM\_MAC
\item wxPLATFORM\_CURRENT
\end{itemize}

wxPLATFORM\_CURRENT means the plaform this binary was compiled for.

Examples:

\begin{verbatim}
current platform   enc          returned value
----------------------------------------------
unix            CP1250             {ISO8859_2}
unix         ISO8859_2             {ISO8859_2}
windows      ISO8859_2                {CP1250}
unix            CP1252  {ISO8859_1,ISO8859_15}
\end{verbatim}

Equivalence is defined in terms of convertibility:
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
fonts in system. It only tells you what are most suitable
encodings. (It usually returns only one encoding.)

\wxheading{Notes}

\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
encoding is native for this platform or not.
\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 contain no items at all.
\end{itemize}

\membersection{wxEncodingConverter::GetAllEquivalents}\label{wxencodingconvertergetallequivalents}

\func{static wxFontEncodingArray}{GetAllEquivalents}{\param{wxFontEncoding }{enc}}

Similar to 
\helpref{GetPlatformEquivalents}{wxencodingconvertergetplatformequivalents}, 
but this one will return ALL 
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.
Commit	Line	Data
c958260b VS	1	%
	2	% automatically generated by HelpGen from
	3	% encconv.h at 30/Dec/99 18:45:16
	4	%
	5
c958260b VS	6	\section{\class{wxEncodingConverter}}\label{wxencodingconverter}
	7
	8	This class is capable of converting strings between any two
457e6c54	9	8-bit encodings/charsets. It can also convert from/to Unicode (but only
f6bcfd97	10	if you compiled wxWindows with wxUSE\_WCHAR\_T set to 1).
c958260b	11
c958260b VS	12	\wxheading{Derived from}
	13
	14	\helpref{wxObject}{wxobject}
	15
9704b250 VS	16	\wxheading{Include files}
	17
	18	<wx/encconv.h>
	19
04a4a2af VS	20	\wxheading{See also}
	21
	22	\helpref{wxFontMapper}{wxfontmapper},
f6bcfd97	23	\helpref{wxMBConv}{wxmbconv},
04a4a2af VS	24	\helpref{Writing non-English applications}{nonenglishoverview}
	25
	26
c958260b VS	27	\latexignore{\rtfignore{\wxheading{Members}}}
c958260b VS	28
c958260b VS	29	\membersection{wxEncodingConverter::wxEncodingConverter}\label{wxencodingconverterwxencodingconverter}
	30
	31	\func{}{wxEncodingConverter}{\void}
	32
	33	Constructor.
	34
	35	\membersection{wxEncodingConverter::Init}\label{wxencodingconverterinit}
	36
	37	\func{bool}{Init}{\param{wxFontEncoding }{input\_enc}, \param{wxFontEncoding }{output\_enc}, \param{int }{method = wxCONVERT\_STRICT}}
	38
	39	Initialize convertion. Both output or input encoding may
	40	be wxFONTENCODING\_UNICODE, but only if wxUSE\_ENCODING is set to 1.
	41	All subsequent calls to \helpref{Convert()}{wxencodingconverterconvert}
457e6c54 JS	42	will interpret its argument
457e6c54 JS	43	as a string in {\it input\_enc} encoding and will output string in
c958260b VS	44	{\it output\_enc} encoding.
	45	You must call this method before calling Convert. You may call
	46	it more than once in order to switch to another conversion.
	47	{\it Method} affects behaviour of Convert() in case input character
	48	cannot be converted because it does not exist in output encoding:
	49
457e6c54	50	\begin{twocollist}\itemsep=0pt
c958260b	51	\twocolitem{{\bf wxCONVERT\_STRICT}}{follow behaviour of GNU Recode -
f6bcfd97	52	just copy unconvertible characters to output and don't change them
c958260b VS	53	(its integer value will stay the same)}
c958260b VS	54	\twocolitem{{\bf wxCONVERT\_SUBSTITUTE}}{try some (lossy) substitutions
f6bcfd97	55	- e.g. replace unconvertible latin capitals with acute by ordinary
c958260b VS	56	capitals, replace en-dash or em-dash by '-' etc.}
	57	\end{twocollist}
	58
f6bcfd97	59	Both modes guarantee that output string will have same length
c958260b VS	60	as input string.
	61
	62	\wxheading{Return value}
	63
	64	FALSE if given conversion is impossible, TRUE otherwise
	65	(conversion may be impossible either if you try to convert
	66	to Unicode with non-Unicode build of wxWindows or if input
	67	or output encoding is not supported.)
	68
c958260b VS	69	\membersection{wxEncodingConverter::Convert}\label{wxencodingconverterconvert}
	70
	71	\func{wxString}{Convert}{\param{const wxString\& }{input}}
	72
	73	\func{void}{Convert}{\param{const wxChar* }{input}, \param{wxChar* }{output}}
	74
	75	\func{void}{Convert}{\param{wxChar* }{str}}
	76
5b5d025c VS	77	\func{void}{Convert}{\param{const char* }{input}, \param{wxChar* }{output}}
5b5d025c VS	78
c958260b VS	79	Convert input string according to settings passed to \helpref{Init}{wxencodingconverterinit}.
	80	Note that you must call Init before using Convert!
	81
c958260b VS	82	\membersection{wxEncodingConverter::GetPlatformEquivalents}\label{wxencodingconvertergetplatformequivalents}
c958260b VS	83
5b5d025c	84	\func{static wxFontEncodingArray}{GetPlatformEquivalents}{\param{wxFontEncoding }{enc}, \param{int }{platform = wxPLATFORM\_CURRENT}}
c958260b VS	85
	86	Return equivalents for given font that are used
	87	under given platform. Supported platforms:
	88
457e6c54	89	\begin{itemize}\itemsep=0pt
c958260b VS	90	\item wxPLATFORM\_UNIX
	91	\item wxPLATFORM\_WINDOWS
	92	\item wxPLATFORM\_OS2
	93	\item wxPLATFORM\_MAC
	94	\item wxPLATFORM\_CURRENT
	95	\end{itemize}
	96
	97	wxPLATFORM\_CURRENT means the plaform this binary was compiled for.
	98
	99	Examples:
457e6c54	100
c958260b VS	101	\begin{verbatim}
	102	current platform enc returned value
	103	----------------------------------------------
	104	unix CP1250 {ISO8859_2}
	105	unix ISO8859_2 {ISO8859_2}
	106	windows ISO8859_2 {CP1250}
	107	unix CP1252 {ISO8859_1,ISO8859_15}
	108	\end{verbatim}
	109
	110	Equivalence is defined in terms of convertibility:
f6bcfd97 BP	111	two encodings are equivalent if you can convert text between
	112	then without losing information (it may - and will - happen
	113	that you lose special chars like quotation marks or em-dashes
	114	but you shouldn't lose any diacritics and language-specific
c958260b VS	115	characters when converting between equivalent encodings).
	116
	117	Remember that this function does {\bf NOT} check for presence of
	118	fonts in system. It only tells you what are most suitable
	119	encodings. (It usually returns only one encoding.)
	120
	121	\wxheading{Notes}
	122
457e6c54 JS	123	\begin{itemize}\itemsep=0pt
457e6c54 JS	124	\item Note that argument {\it enc} itself may be present in the returned array,
f6bcfd97	125	so that you can, as a side-effect, detect whether the
457e6c54	126	encoding is native for this platform or not.
f6bcfd97 BP	127	\item \helpref{Convert}{wxencodingconverterconvert} is not limited to
	128	converting between equivalent encodings, it can convert between two arbitrary
	129	encodings.
	130	\item If {\it enc} is present in the returned array, then it is {\bf always} the first
5b5d025c	131	item of it.
f6bcfd97	132	\item Please note that the returned array may contain no items at all.
c958260b VS	133	\end{itemize}
c958260b VS	134
c958260b VS	135	\membersection{wxEncodingConverter::GetAllEquivalents}\label{wxencodingconvertergetallequivalents}
c958260b VS	136
5b5d025c	137	\func{static wxFontEncodingArray}{GetAllEquivalents}{\param{wxFontEncoding }{enc}}
c958260b VS	138
	139	Similar to
	140	\helpref{GetPlatformEquivalents}{wxencodingconvertergetplatformequivalents},
	141	but this one will return ALL
f6bcfd97	142	equivalent encodings, regardless of the platform, and including itself.
c958260b	143
5b5d025c VS	144	This platform's encodings are before others in the array. And again, if {\it enc} is in the array,
5b5d025c VS	145	it is the very first item in it.
457e6c54	146