Long live Qt 4.5!

1 files changed, 165 insertions, 0 deletions

diff --git a/doc/src/unicode.qdoc b/doc/src/unicode.qdoc
new file mode 100644
index 0000000..42ac5a4
--- /dev/null
+++ b/doc/src/unicode.qdoc
@@ -0,0 +1,165 @@
+/****************************************************************************
+**
+** Copyright (C) 2009 Nokia Corporation and/or its subsidiary(-ies).
+** Contact: Qt Software Information (qt-info@nokia.com)
+**
+** This file is part of the documentation of the Qt Toolkit.
+**
+** $QT_BEGIN_LICENSE:LGPL$
+** No Commercial Usage
+** This file contains pre-release code and may not be distributed.
+** You may use this file in accordance with the terms and conditions
+** contained in the either Technology Preview License Agreement or the
+** Beta Release License Agreement.
+**
+** GNU Lesser General Public License Usage
+** Alternatively, this file may be used under the terms of the GNU Lesser
+** General Public License version 2.1 as published by the Free Software
+** Foundation and appearing in the file LICENSE.LGPL included in the
+** packaging of this file.  Please review the following information to
+** ensure the GNU Lesser General Public License version 2.1 requirements
+** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html.
+**
+** In addition, as a special exception, Nokia gives you certain
+** additional rights. These rights are described in the Nokia Qt LGPL
+** Exception version 1.0, included in the file LGPL_EXCEPTION.txt in this
+** package.
+**
+** GNU General Public License Usage
+** Alternatively, this file may be used under the terms of the GNU
+** General Public License version 3.0 as published by the Free Software
+** Foundation and appearing in the file LICENSE.GPL included in the
+** packaging of this file.  Please review the following information to
+** ensure the GNU General Public License version 3.0 requirements will be
+** met: http://www.gnu.org/copyleft/gpl.html.
+**
+** If you are unsure which license is appropriate for your use, please
+** contact the sales department at qt-sales@nokia.com.
+** $QT_END_LICENSE$
+**
+****************************************************************************/
+
+/*! 
+    \page unicode.html
+    \title Unicode
+    \ingroup architecture
+    \ingroup text-processing
+    \brief Information about support for Unicode in Qt.
+
+    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 cross-platform. For these
+    reasons, Unicode 4.0 is used as the native character set for Qt.
+
+
+    \section1 Information about Unicode on the Web
+
+    The \l{http://www.unicode.org/}{Unicode Consortium} has a number
+    of documents available, including
+
+    \list
+
+    \i \l{http://www.unicode.org/unicode/standard/principles.html}{A
+    technical introduction to Unicode}
+    \i \l{http://www.unicode.org/unicode/standard/standard.html}{The
+    home page for the standard}
+
+    \endlist
+
+
+    \section1 The Standard
+
+    The current version of the standard is 4.0.0.
+
+    \list
+
+    \i \link http://www.amazon.com/exec/obidos/ASIN/0321185781/trolltech/t
+    The Unicode Standard, version 4.0.\endlink  See also
+    \link http://www.unicode.org/unicode/standard/versions/
+    its home page.\endlink
+    \i \link http://www.amazon.com/exec/obidos/ASIN/0201616335/trolltech/t
+    The Unicode Standard, version 3.2.\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
+    QTextCodec and 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, 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 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,
+    QLabel::setText() and a many others, take \c{const QString &}s.
+    QString provides implicit casting from \c{const char *}
+    so that things like
+
+    \snippet doc/src/snippets/code/doc_src_unicode.qdoc 0
+
+    will work. There is also a function, QObject::tr(), that provides
+    translation support, like this:
+
+    \snippet doc/src/snippets/code/doc_src_unicode.qdoc 1
+
+    QObject::tr() maps from \c{const char *} to a Unicode string, and
+    uses installable QTranslator objects to do the mapping.
+
+    Qt provides a number of built-in 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:
+
+    \snippet doc/src/snippets/code/doc_src_unicode.qdoc 2
+
+    or
+
+    \snippet doc/src/snippets/code/doc_src_unicode.qdoc 3
+
+    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.
+
+    \sa {Internationalization with Qt}
+*/