diff options
Diffstat (limited to 'doc/unicode.doc')
-rw-r--r-- | doc/unicode.doc | 156 |
1 files changed, 156 insertions, 0 deletions
diff --git a/doc/unicode.doc b/doc/unicode.doc new file mode 100644 index 000000000..bf6f75452 --- /dev/null +++ b/doc/unicode.doc @@ -0,0 +1,156 @@ +/**************************************************************************** +** +** Documentation of Unicode support in Qt. +** +** Copyright (C) 1992-2008 Trolltech ASA. All rights reserved. +** +** This file is part of the Qt GUI Toolkit. +** +** This file may be used under the terms of the GNU General +** Public License versions 2.0 or 3.0 as published by the Free +** Software Foundation and appearing in the files LICENSE.GPL2 +** and LICENSE.GPL3 included in the packaging of this file. +** Alternatively you may (at your option) use any later version +** of the GNU General Public License if such license has been +** publicly approved by Trolltech ASA (or its successors, if any) +** and the KDE Free Qt Foundation. +** +** Please review the following information to ensure GNU General +** Public Licensing retquirements will be met: +** http://trolltech.com/products/qt/licenses/licensing/opensource/. +** If you are unsure which license is appropriate for your use, please +** review the following information: +** http://trolltech.com/products/qt/licenses/licensing/licensingoverview +** or contact the sales department at sales@trolltech.com. +** +** This file may be used under the terms of the Q Public License as +** defined by Trolltech ASA and appearing in the file LICENSE.QPL +** included in the packaging of this file. Licensees holding valid Qt +** Commercial licenses may use this file in accordance with the Qt +** Commercial License Agreement provided with the Software. +** +** This file is provided "AS IS" with NO WARRANTY OF ANY KIND, +** INCLUDING THE WARRANTIES OF DESIGN, MERCHANTABILITY AND FITNESS FOR +** A PARTICULAR PURPOSE. Trolltech reserves all rights not granted +** herein. +** +**********************************************************************/ + +/*! \page unicode.html + +\title About Unicode + +Unicode is a multi-byte character set, portable across all major +computing platforms and with decent coverage over most of the world. +It is also single-locale; it includes no code pages or other +complexities that make software harder to write and test. There is no +competing character set that's reasonably multiplatform. For these +reasons, Trolltech uses Unicode as the native character set for Qt +(since version 2.0). + + +\section1 Information about Unicode on the web. + +The \link http://www.unicode.org Unicode Consortium\endlink +has a number of documents available, including + +\list + +\i \link http://www.unicode.org/unicode/standard/principles.html +A technical introduction to Unicode\endlink +\i \link http://www.unicode.org/unicode/standard/standard.html +The home page for the standard\endlink + +\endlist + + +\section1 The Standard + +The current version of the standard is 3.2 + +\list + +\i \link http://www.amazon.com/exec/obidos/ASIN/0201616335/trolltech/t +The Unicode Standard, version 3.2.\endlink See also +\link http://www.unicode.org/unicode/standard/versions/ +its home page.\endlink +\i \link http://www.amazon.com/exec/obidos/ASIN/0201473459/trolltech/t +The Unicode Standard, version 2.0.\endlink See also the +\link http://www.unicode.org/unicode/reports/tr8.html 2.1 +update\endlink and +\link http://www.unicode.org/unicode/standard/versions/enumeratedversions.html#Unicode 2.1.9 the 2.1.9 data files\endlink at www.unicode.org. + +\endlist + +\section1 Unicode in Qt + +In Qt, and in most applications that use Qt, most or all user-visible +strings are stored using Unicode. Qt provides: + +\list + +\i Translation to/from legacy encodings for file I/O: see \l +QTextCodec and \l QTextStream. +\i Translation from Input Methods and 8-bit keyboard input. +\i Translation to legacy character sets for on-screen display. +\i A string class, \l QString, that stores Unicode characters, with +support for migrating from C strings including fast (cached) +translation to and from US-ASCII, and all the usual string +operations. +\i Unicode-aware widgets where appropriate. +\i Unicode support detection on Windows, so that Qt provides Unicode +even on Windows platforms that do not support it natively. + +\endlist + +To fully benefit from Unicode, we recommend using QString for storing +all user-visible strings, and performing all text file I/O using +QTextStream. Use \l QKeyEvent::text() for keyboard input in any custom +widgets you write; it does not make much difference for slow typists +in Western Europe or North America, but for fast typists or people +using special input methods using text() is beneficial. + +All the function arguments in Qt that may be user-visible strings, \l +QLabel::setText() and a many others, take \c{const QString &}s. +\l QString provides implicit casting from \c{const char *} +so that things like +\code + myLabel->setText( "Hello, Dolly!" ); +\endcode +will work. There is also a function, \l QObject::tr(), that provides +translation support, like this: +\code + myLabel->setText( tr("Hello, Dolly!") ); +\endcode + +tr() (simplifying somewhat) maps from \c{const char *} to a +Unicode string, and uses installable \l QTranslator objects to do the +mapping. + +Qt provides a number of built-in \l QTextCodec classes, that is, +classes that know how to translate between Unicode and legacy +encodings to support programs that must talk to other programs or +read/write files in legacy file formats. + +By default, conversion to/from \c{const char *} uses a +locale-dependent codec. However, applications can easily find codecs +for other locales, and set any open file or network connection to use +a special codec. It is also possible to install new codecs, for +encodings that the built-in ones do not support. (At the time of +writing, Vietnamese/VISCII is one such example.) + +Since US-ASCII and ISO-8859-1 are so common, there are also especially +fast functions for mapping to and from them. For example, to open an +application's icon one might do this: +\code + QFile f( QString::fromLatin1("appicon.png") ); +\endcode + +Regarding output, Qt will do a best-effort conversion from +Unicode to whatever encoding the system and fonts provide. +Depending on operating system, locale, font availability and Qt's +support for the characters used, this conversion may be good or bad. +We will extend this in upcoming versions, with emphasis on the most +common locales first. + +*/ |