1999-09-29 15:02:07 -04:00
|
|
|
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
|
|
|
|
%% Name: tunicode.tex
|
2004-05-04 04:27:20 -04:00
|
|
|
%% Purpose: Overview of the Unicode support in wxWidgets
|
1999-09-29 15:02:07 -04:00
|
|
|
%% Author: Vadim Zeitlin
|
|
|
|
%% Modified by:
|
|
|
|
%% Created: 22.09.99
|
|
|
|
%% RCS-ID: $Id$
|
|
|
|
%% Copyright: (c) 1999 Vadim Zeitlin <zeitlin@dptmaths.ens-cachan.fr>
|
2004-05-04 04:27:20 -04:00
|
|
|
%% Licence: wxWidgets license
|
1999-09-29 15:02:07 -04:00
|
|
|
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
|
|
|
|
|
2004-05-04 04:27:20 -04:00
|
|
|
\section{Unicode support in wxWidgets}\label{unicode}
|
1999-09-29 15:02:07 -04:00
|
|
|
|
2004-05-04 04:27:20 -04:00
|
|
|
This section briefly describes the state of the Unicode support in wxWidgets.
|
1999-09-29 15:02:07 -04:00
|
|
|
Read it if you want to know more about how to write programs able to work with
|
|
|
|
characters from languages other than English.
|
|
|
|
|
2004-09-20 07:21:04 -04:00
|
|
|
\subsection{What is Unicode?}\label{whatisunicode}
|
1999-09-29 15:02:07 -04:00
|
|
|
|
2004-05-04 04:27:20 -04:00
|
|
|
Starting with release 2.1 wxWidgets has support for compiling in Unicode mode
|
1999-09-29 15:02:07 -04:00
|
|
|
on the platforms which support it. Unicode is a standard for character
|
2000-07-15 15:51:35 -04:00
|
|
|
encoding which addresses the shortcomings of the previous, 8 bit standards, by
|
2001-12-17 11:52:22 -05:00
|
|
|
using at least 16 (and possibly 32) bits for encoding each character. This
|
|
|
|
allows to have at least 65536 characters (what is called the BMP, or basic
|
|
|
|
multilingual plane) and possible $2^{32}$ of them instead of the usual 256 and
|
|
|
|
is sufficient to encode all of the world languages at once. More details about
|
|
|
|
Unicode may be found at {\tt www.unicode.org}.
|
1999-09-29 15:02:07 -04:00
|
|
|
|
|
|
|
% TODO expand on it, say that Unicode extends ASCII, mention ISO8859, ...
|
|
|
|
|
|
|
|
As this solution is obviously preferable to the previous ones (think of
|
|
|
|
incompatible encodings for the same language, locale chaos and so on), many
|
2000-07-15 15:51:35 -04:00
|
|
|
modern operating systems support it. The probably first example is Windows NT
|
1999-09-29 15:02:07 -04:00
|
|
|
which uses only Unicode internally since its very first version.
|
|
|
|
|
|
|
|
Writing internationalized programs is much easier with Unicode and, as the
|
|
|
|
support for it improves, it should become more and more so. Moreover, in the
|
|
|
|
Windows NT/2000 case, even the program which uses only standard ASCII can profit
|
|
|
|
from using Unicode because they will work more efficiently - there will be no
|
2000-07-15 15:51:35 -04:00
|
|
|
need for the system to convert all strings the program uses to/from Unicode
|
1999-09-29 15:02:07 -04:00
|
|
|
each time a system call is made.
|
|
|
|
|
2004-09-20 07:21:04 -04:00
|
|
|
\subsection{Unicode and ANSI modes}\label{unicodeandansi}
|
1999-09-29 15:02:07 -04:00
|
|
|
|
2004-05-04 04:27:20 -04:00
|
|
|
As not all platforms supported by wxWidgets support Unicode (fully) yet, in
|
1999-09-29 15:02:07 -04:00
|
|
|
many cases it is unwise to write a program which can only work in Unicode
|
|
|
|
environment. A better solution is to write programs in such way that they may
|
|
|
|
be compiled either in ANSI (traditional) mode or in the Unicode one.
|
|
|
|
|
2004-05-04 04:27:20 -04:00
|
|
|
This can be achieved quite simply by using the means provided by wxWidgets.
|
2000-07-15 15:51:35 -04:00
|
|
|
Basically, there are only a few things to watch out for:
|
1999-10-11 07:06:44 -04:00
|
|
|
|
1999-09-29 15:02:07 -04:00
|
|
|
\begin{itemize}
|
|
|
|
\item Character type ({\tt char} or {\tt wchar\_t})
|
|
|
|
\item Literal strings (i.e. {\tt "Hello, world!"} or {\tt '*'})
|
|
|
|
\item String functions ({\tt strlen()}, {\tt strcpy()}, ...)
|
2001-12-17 11:52:22 -05:00
|
|
|
\item Special preprocessor tokens ({\tt \_\_FILE\_\_}, {\tt \_\_DATE\_\_}
|
|
|
|
and {\tt \_\_TIME\_\_})
|
1999-09-29 15:02:07 -04:00
|
|
|
\end{itemize}
|
|
|
|
|
|
|
|
Let's look at them in order. First of all, each character in an Unicode
|
|
|
|
program takes 2 bytes instead of usual one, so another type should be used to
|
|
|
|
store the characters ({\tt char} only holds 1 byte usually). This type is
|
|
|
|
called {\tt wchar\_t} which stands for {\it wide-character type}.
|
|
|
|
|
2001-12-17 11:52:22 -05:00
|
|
|
Also, the string and character constants should be encoded using wide
|
|
|
|
characters ({\tt wchar\_t} type) which typically take $2$ or $4$ bytes instead
|
|
|
|
of {\tt char} which only takes one. This is achieved by using the standard C
|
|
|
|
(and C++) way: just put the letter {\tt 'L'} after any string constant and it
|
|
|
|
becomes a {\it long} constant, i.e. a wide character one. To make things a bit
|
|
|
|
more readable, you are also allowed to prefix the constant with {\tt 'L'}
|
|
|
|
instead of putting it after it.
|
1999-09-29 15:02:07 -04:00
|
|
|
|
2001-12-17 11:52:22 -05:00
|
|
|
Of course, the usual standard C functions don't work with {\tt wchar\_t}
|
|
|
|
strings, so another set of functions exists which do the same thing but accept
|
1999-09-29 15:02:07 -04:00
|
|
|
{\tt wchar\_t *} instead of {\tt char *}. For example, a function to get the
|
|
|
|
length of a wide-character string is called {\tt wcslen()} (compare with
|
|
|
|
{\tt strlen()} - you see that the only difference is that the "str" prefix
|
2001-12-17 11:52:22 -05:00
|
|
|
standing for "string" has been replaced with "wcs" standing for "wide-character
|
|
|
|
string").
|
|
|
|
|
|
|
|
And finally, the standard preprocessor tokens enumerated above expand to ANSI
|
|
|
|
strings but it is more likely that Unicode strings are wanted in the Unicode
|
2004-05-04 04:27:20 -04:00
|
|
|
build. wxWidgets provides the macros {\tt \_\_TFILE\_\_}, {\tt \_\_TDATE\_\_}
|
2001-12-17 11:52:22 -05:00
|
|
|
and {\tt \_\_TTIME\_\_} which behave exactly as the standard ones except that
|
|
|
|
they produce ANSI strings in ANSI build and Unicode ones in the Unicode build.
|
1999-09-29 15:02:07 -04:00
|
|
|
|
|
|
|
To summarize, here is a brief example of how a program which can be compiled
|
|
|
|
in both ANSI and Unicode modes could look like:
|
|
|
|
|
|
|
|
\begin{verbatim}
|
|
|
|
#ifdef __UNICODE__
|
|
|
|
wchar_t wch = L'*';
|
|
|
|
const wchar_t *ws = L"Hello, world!";
|
|
|
|
int len = wcslen(ws);
|
2001-12-17 11:52:22 -05:00
|
|
|
|
|
|
|
wprintf(L"Compiled at %s\n", __TDATE__);
|
1999-09-29 15:02:07 -04:00
|
|
|
#else // ANSI
|
|
|
|
char ch = '*';
|
|
|
|
const char *s = "Hello, world!";
|
|
|
|
int len = strlen(s);
|
2001-12-17 11:52:22 -05:00
|
|
|
|
|
|
|
printf("Compiled at %s\n", __DATE__);
|
1999-09-29 15:02:07 -04:00
|
|
|
#endif // Unicode/ANSI
|
|
|
|
\end{verbatim}
|
|
|
|
|
|
|
|
Of course, it would be nearly impossibly to write such programs if it had to
|
1999-12-24 18:40:13 -05:00
|
|
|
be done this way (try to imagine the number of {\tt \#ifdef UNICODE} an average
|
1999-09-29 15:02:07 -04:00
|
|
|
program would have had!). Luckily, there is another way - see the next
|
|
|
|
section.
|
|
|
|
|
2004-09-20 07:21:04 -04:00
|
|
|
\subsection{Unicode support in wxWidgets}\label{unicodeinsidewxw}
|
1999-09-29 15:02:07 -04:00
|
|
|
|
2004-05-04 04:27:20 -04:00
|
|
|
In wxWidgets, the code fragment from above should be written instead:
|
1999-09-29 15:02:07 -04:00
|
|
|
|
|
|
|
\begin{verbatim}
|
1999-11-04 12:49:21 -05:00
|
|
|
wxChar ch = wxT('*');
|
|
|
|
wxString s = wxT("Hello, world!");
|
1999-09-29 15:02:07 -04:00
|
|
|
int len = s.Len();
|
|
|
|
\end{verbatim}
|
|
|
|
|
1999-12-24 18:40:13 -05:00
|
|
|
What happens here? First of all, you see that there are no more {\tt \#ifdef}s
|
1999-09-29 15:02:07 -04:00
|
|
|
at all. Instead, we define some types and macros which behave differently in
|
|
|
|
the Unicode and ANSI builds and allows us to avoid using conditional
|
|
|
|
compilation in the program itself.
|
|
|
|
|
|
|
|
We have a {\tt wxChar} type which maps either on {\tt char} or {\tt wchar\_t}
|
|
|
|
depending on the mode in which program is being compiled. There is no need for
|
|
|
|
a separate type for strings though, because the standard
|
1999-11-04 12:49:21 -05:00
|
|
|
\helpref{wxString}{wxstring} supports Unicode, i.e. it stores either ANSI or
|
|
|
|
Unicode strings depending on the compile mode.
|
1999-09-29 15:02:07 -04:00
|
|
|
|
2003-01-25 17:49:41 -05:00
|
|
|
Finally, there is a special \helpref{wxT()}{wxt} macro which should enclose all
|
|
|
|
literal strings in the program. As it is easy to see comparing the last
|
|
|
|
fragment with the one above, this macro expands to nothing in the (usual) ANSI
|
|
|
|
mode and prefixes {\tt 'L'} to its argument in the Unicode mode.
|
1999-09-29 15:02:07 -04:00
|
|
|
|
|
|
|
The important conclusion is that if you use {\tt wxChar} instead of
|
|
|
|
{\tt char}, avoid using C style strings and use {\tt wxString} instead and
|
2003-01-25 17:49:41 -05:00
|
|
|
don't forget to enclose all string literals inside \helpref{wxT()}{wxt} macro, your
|
1999-09-29 15:02:07 -04:00
|
|
|
program automatically becomes (almost) Unicode compliant!
|
|
|
|
|
|
|
|
Just let us state once again the rules:
|
1999-10-11 07:06:44 -04:00
|
|
|
|
1999-09-29 15:02:07 -04:00
|
|
|
\begin{itemize}
|
|
|
|
\item Always use {\tt wxChar} instead of {\tt char}
|
2003-01-25 17:49:41 -05:00
|
|
|
\item Always enclose literal string constants in \helpref{wxT()}{wxt} macro
|
|
|
|
unless they're already converted to the right representation (another standard
|
2004-05-04 04:27:20 -04:00
|
|
|
wxWidgets macro \helpref{\_()}{underscore} does it, for example, so there is no
|
2003-01-25 17:49:41 -05:00
|
|
|
need for {\tt wxT()} in this case) or you intend to pass the constant directly
|
|
|
|
to an external function which doesn't accept wide-character strings.
|
1999-09-29 15:02:07 -04:00
|
|
|
\item Use {\tt wxString} instead of C style strings.
|
|
|
|
\end{itemize}
|
|
|
|
|
2004-09-20 07:21:04 -04:00
|
|
|
\subsection{Unicode and the outside world}\label{unicodeoutsidewxw}
|
1999-09-29 15:02:07 -04:00
|
|
|
|
2004-05-04 04:27:20 -04:00
|
|
|
We have seen that it was easy to write Unicode programs using wxWidgets types
|
1999-09-29 15:02:07 -04:00
|
|
|
and macros, but it has been also mentioned that it isn't quite enough.
|
|
|
|
Although everything works fine inside the program, things can get nasty when
|
|
|
|
it tries to communicate with the outside world which, sadly, often expects
|
|
|
|
ANSI strings (a notable exception is the entire Win32 API which accepts either
|
|
|
|
Unicode or ANSI strings and which thus makes it unnecessary to ever perform
|
2002-12-04 09:11:26 -05:00
|
|
|
any conversions in the program). GTK 2.0 only accepts UTF-8 strings.
|
1999-09-29 15:02:07 -04:00
|
|
|
|
1999-10-22 09:12:08 -04:00
|
|
|
To get a ANSI string from a wxString, you may use the
|
|
|
|
mb\_str() function which always returns an ANSI
|
1999-09-29 15:02:07 -04:00
|
|
|
string (independently of the mode - while the usual
|
|
|
|
\helpref{c\_str()}{wxstringcstr} returns a pointer to the internal
|
|
|
|
representation which is either ASCII or Unicode). More rarely used, but still
|
1999-10-22 09:12:08 -04:00
|
|
|
useful, is wc\_str() function which always returns
|
1999-09-29 15:02:07 -04:00
|
|
|
the Unicode string.
|
|
|
|
|
|
|
|
% TODO describe fn_str(), wx_str(), wxCharBuf classes, ...
|
2000-07-15 15:51:35 -04:00
|
|
|
|
2004-09-20 07:21:04 -04:00
|
|
|
\subsection{Unicode-related compilation settings}\label{unicodesettings}
|
2000-07-15 15:51:35 -04:00
|
|
|
|
|
|
|
You should define {\tt wxUSE\_UNICODE} to $1$ to compile your program in
|
2002-12-04 09:11:26 -05:00
|
|
|
Unicode mode. Note that it currently only works in Win32 and GTK 2.0 and
|
|
|
|
that some parts of
|
2005-01-10 13:31:54 -05:00
|
|
|
wxWidgets are not Unicode-compliant yet. If you
|
2000-07-15 15:51:35 -04:00
|
|
|
compile your program in ANSI mode you can still define {\tt wxUSE\_WCHAR\_T}
|
|
|
|
to get some limited support for {\tt wchar\_t} type.
|
|
|
|
|
|
|
|
This will allow your program to perform conversions between Unicode strings and
|
2003-01-23 14:49:53 -05:00
|
|
|
ANSI ones (using \helpref{wxMBConv classes}{mbconvclasses})
|
|
|
|
and construct wxString objects from Unicode strings (presumably read
|
2000-07-15 15:51:35 -04:00
|
|
|
from some external file or elsewhere).
|
1999-10-11 07:06:44 -04:00
|
|
|
|