Update copyright headers
[qt:qt.git] / doc / src / frameworks-technologies / unicode.qdoc
1 /****************************************************************************
2 **
3 ** Copyright (C) 2015 The Qt Company Ltd.
4 ** Contact: http://www.qt.io/licensing/
5 **
6 ** This file is part of the documentation of the Qt Toolkit.
7 **
8 ** $QT_BEGIN_LICENSE:FDL$
9 ** Commercial License Usage
10 ** Licensees holding valid commercial Qt licenses may use this file in
11 ** accordance with the commercial license agreement provided with the
12 ** Software or, alternatively, in accordance with the terms contained in
13 ** a written agreement between you and The Qt Company. For licensing terms
14 ** and conditions see http://www.qt.io/terms-conditions. For further
15 ** information use the contact form at http://www.qt.io/contact-us.
16 **
17 ** GNU Free Documentation License Usage
18 ** Alternatively, this file may be used under the terms of the GNU Free
19 ** Documentation License version 1.3 as published by the Free Software
20 ** Foundation and appearing in the file included in the packaging of
21 ** this file.  Please review the following information to ensure
22 ** the GNU Free Documentation License version 1.3 requirements
23 ** will be met: http://www.gnu.org/copyleft/fdl.html.
24 ** $QT_END_LICENSE$
25 **
26 ****************************************************************************/
27
28 /*!
29     \group string-processing
30     \title Classes for String Data
31
32     \brief Classes for working with string data.
33
34     These classes are relevant when working with string data. See the
35     \l{Unicode in Qt}{information about support for Unicode in Qt} for
36     more information.
37 */
38
39
40 /*! 
41     \page unicode.html
42     \title Unicode in Qt
43     \brief Information about support for Unicode in Qt.
44
45     \keyword Unicode
46
47     \ingroup technology-apis
48
49     Unicode is a multi-byte character set, portable across all major
50     computing platforms and with decent coverage over most of the world.
51     It is also single-locale; it includes no code pages or other
52     complexities that make software harder to write and test. There is no
53     competing character set that's reasonably cross-platform. For these
54     reasons, Unicode 4.0 is used as the native character set for Qt.
55     
56     \section1 Qt's Classes for Working with Strings
57
58     These classes are relevant when working with string data. For information
59     about rendering text, see the \l{Rich Text Processing} overview, and if
60     your string data is in XML, see the \l{XML Processing} overview.
61
62         \annotatedlist string-processing
63
64     \section1 Information about Unicode on the Web
65
66     The \l{http://www.unicode.org/}{Unicode Consortium} has a number
67     of documents available, including
68
69     \list
70
71     \i \l{http://www.unicode.org/unicode/standard/principles.html}{A
72     technical introduction to Unicode}
73     \i \l{http://www.unicode.org/unicode/standard/standard.html}{The
74     home page for the standard}
75
76     \endlist
77
78
79     \section1 The Standard
80
81     The current version of the standard is \l{http://www.unicode.org/versions/Unicode5.1.0/}{Unicode 5.1.0}.
82
83     Previous printed versions of the specification:
84
85     \list
86     \o \l{http://www.amazon.com/Unicode-Standard-Version-5-0-5th/dp/0321480910/trolltech/t}{The Unicode Standard, Version 5.0}
87     \o \l{http://www.amazon.com/exec/obidos/ASIN/0321185781/trolltech/t}{The Unicode Standard, version 4.0}  
88     \o \l{http://www.amazon.com/exec/obidos/ASIN/0201616335/trolltech/t}{The Unicode Standard, version 3.2}
89     \o \l{http://www.amazon.com/exec/obidos/ASIN/0201473459/trolltech/t}{The Unicode Standard, version 2.0} \mdash
90     see also the \l{http://www.unicode.org/unicode/reports/tr8.html}{2.1 update} and
91     \l{http://www.unicode.org/unicode/standard/versions/enumeratedversions.html#Unicode 2.1.9}{the 2.1.9 data files} at
92     \l{http://www.unicode.org}.
93     \endlist
94
95     \section1 Unicode in Qt
96
97     In Qt, and in most applications that use Qt, most or all user-visible
98     strings are stored using Unicode. Qt provides:
99
100     \list
101
102     \i Translation to/from legacy encodings for file I/O: see
103     QTextCodec and QTextStream.
104     \i Translation from Input Methods and 8-bit keyboard input.
105     \i Translation to legacy character sets for on-screen display.
106     \i A string class, QString, that stores Unicode characters, with
107     support for migrating from C strings including fast (cached)
108     translation to and from US-ASCII, and all the usual string
109     operations.
110     \i Unicode-aware widgets where appropriate.
111     \i Unicode support detection on Windows, so that Qt provides Unicode
112     even on Windows platforms that do not support it natively.
113
114     \endlist
115
116     To fully benefit from Unicode, we recommend using QString for storing
117     all user-visible strings, and performing all text file I/O using
118     QTextStream. Use QKeyEvent::text() for keyboard input in any custom
119     widgets you write; it does not make much difference for slow typists
120     in Western Europe or North America, but for fast typists or people
121     using special input methods using text() is beneficial.
122
123     All the function arguments in Qt that may be user-visible strings,
124     QLabel::setText() and a many others, take \c{const QString &}s.
125     QString provides implicit casting from \c{const char *}
126     so that things like
127
128     \snippet doc/src/snippets/code/doc_src_unicode.cpp 0
129
130     will work. There is also a function, QObject::tr(), that provides
131     translation support, like this:
132
133     \snippet doc/src/snippets/code/doc_src_unicode.cpp 1
134
135     QObject::tr() maps from \c{const char *} to a Unicode string, and
136     uses installable QTranslator objects to do the mapping.
137
138     Qt provides a number of built-in QTextCodec classes, that is,
139     classes that know how to translate between Unicode and legacy
140     encodings to support programs that must talk to other programs or
141     read/write files in legacy file formats.
142
143     By default, conversion to/from \c{const char *} uses a
144     locale-dependent codec. However, applications can easily find codecs
145     for other locales, and set any open file or network connection to use
146     a special codec. It is also possible to install new codecs, for
147     encodings that the built-in ones do not support. (At the time of
148     writing, Vietnamese/VISCII is one such example.)
149
150     Since US-ASCII and ISO-8859-1 are so common, there are also especially
151     fast functions for mapping to and from them. For example, to open an
152     application's icon one might do this:
153
154     \snippet doc/src/snippets/code/doc_src_unicode.cpp 2
155
156     or
157
158     \snippet doc/src/snippets/code/doc_src_unicode.cpp 3
159
160     Regarding output, Qt will do a best-effort conversion from
161     Unicode to whatever encoding the system and fonts provide.
162     Depending on operating system, locale, font availability, and Qt's
163     support for the characters used, this conversion may be good or bad.
164     We will extend this in upcoming versions, with emphasis on the most
165     common locales first.
166
167     \sa {Internationalization with Qt}
168 */