Add Qt3 development HEAD version

1 files changed, 593 insertions, 0 deletions

diff --git a/doc/i18n.doc b/doc/i18n.doc
new file mode 100644
index 0000000..02bb195
--- /dev/null
+++ b/doc/i18n.doc
@@ -0,0 +1,593 @@
+/****************************************************************************
+**
+** Explanation of moc and the meta object system
+**
+** 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 requirements 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.
+**
+**********************************************************************/
+
+/*! \defgroup i18n
+
+\title Internationalization with Qt
+
+\keyword internationalization
+\keyword i18n
+
+The internationalization of an application is the process of making
+the application usable by people in countries other than one's own. 
+
+\tableofcontents
+
+In some cases internationalization is simple, for example, making a US
+application accessible to Australian or British users may require
+little more than a few spelling corrections. But to make a US
+application usable by Japanese users, or a Korean application usable
+by German users, will require that the software operate not only in
+different languages, but use different input techniques, character
+encodings and presentation conventions.
+
+Qt tries to make internationalization as painless as possible for
+developers. All input widgets and text drawing methods in Qt offer
+built-in support for all supported languages. The built-in font engine
+is capable of correctly and attractively rendering text that contains
+characters from a variety of different writing systems at the same
+time.
+
+Qt supports most languages in use today, in particular:
+\list
+\i All East Asian languages (Chinese, Japanese and Korean)
+\i All Western languages (using Latin script)
+\i Arabic
+\i Cyrillic languages (Russian)
+\i Greek
+\i Hebrew
+\i Thai and Lao
+\i All scripts in Unicode 3.2 that do not require special processing
+\endlist
+
+On Windows NT/2000/XP and Unix/X11 with Xft (client side font support)
+the following languages are also supported:
+\list
+\i Bengali
+\i Devanagari
+\i Dhivehi (Thaana)
+\i Gujarati
+\i Gurmukhi
+\i Kannada
+\i Khmer
+\i Malayalam (X11 only)
+\i Myanmar (X11 only)
+\i Syriac
+\i Tamil
+\i Telugu
+\i Tibetan (X11 only)
+\endlist
+
+Many of these writing systems exhibit special features:
+
+\list
+
+\i <b>Special line breaking behavior.</b> Some of the Asian languages are
+written without spaces between words. Line breaking can occur either
+after every character (with exceptions) as in Chinese, Japanese and
+Korean, or after logical word boundaries as in Thai.
+
+\i <b>Bidirectional writing.</b> Arabic and Hebrew are written from right to
+left, except for numbers and embedded English text which is written
+left to right. The exact behavior is defined in the \link
+http://www.unicode.org/unicode/reports/tr9/ Unicode Technical Report
+#9 \endlink.
+
+\i <b>Non spacing or diacritical marks</b> (accents or umlauts in European
+languages). Some languages such as Vietnamese make extensive use of
+these marks and some characters can have more than one mark at the
+same time to clarify pronunciation.
+
+\i <b>Ligatures.</b> In special contexts, some pairs of characters get
+replaced by a combined glyph forming a ligature. Common examples are
+the fl and fi ligatures used in typesetting US and European books.
+
+\endlist
+
+Qt tries to take care of all the special features listed above. You
+usually don't have to worry about these features so long as you use
+Qt's input widgets (e.g. QLineEdit, QTextEdit, and derived classes)
+and Qt's display widgets (e.g. QLabel).
+
+Support for these writing systems is transparent to the programmer
+and completely encapsulated in Qt's text engine. This means that you
+don't need to have any knowledge about the writing system used in a
+particular language, except for the following small points:
+\list
+
+\i QPainter::drawText( int x, int y, const QString &str ) will always
+draw the string with it's left edge at the position specified with
+the x, y parameters. This will usually give you left aligned strings.
+Arabic and Hebrew application strings are usually right
+aligned, so for these languages use the version of drawText() that
+takes a QRect since this will align in accordance with the language.
+
+\i When you write your own text input controls, use \l
+QFontMetrics::charWidth() to determine the width of a character in a
+string. In some languages (e.g. Arabic or languages from the Indian
+subcontinent), the width and shape of a glyph changes depending on the
+surrounding characters. Writing input controls usually requires a
+certain knowledge of the scripts it is going to be used in. Usually
+the easiest way is to subclass QLineEdit or QTextEdit.
+
+\endlist
+
+The following sections give some information on the status
+of the internationalization (i18n) support in Qt.
+
+See also the \link linguist-manual.book Qt Linguist\endlink manual.
+
+\section1 Step by Step
+
+Writing multi-platform international software with Qt is a gentle,
+incremental process. Your software can become internationalized in
+the following stages:
+
+\section2 Use QString for all User-visible Text
+
+Since QString uses the Unicode encoding internally, every
+language in the world can be processed transparently using
+familiar text processing operations. Also, since all Qt
+functions that present text to the user take a QString as a
+parameter, there is no char* to QString conversion overhead.
+
+Strings that are in "programmer space" (such as QObject names
+and file format texts) need not use QString; the traditional
+char* or the QCString class will suffice.
+
+You're unlikely to notice that you are using Unicode;
+QString, and QChar are just like easier versions of the crude
+const char* and char from traditional C.
+
+\section2 Use tr() for all Literal Text
+
+Wherever your program uses \c{"quoted text"} for text that will
+be presented to the user, ensure that it is processed by the \l
+QApplication::translate() function. Essentially all that is necessary
+to achieve this is to use \l QObject::tr(). For example, assuming the
+\c LoginWidget is a subclass of QWidget:
+
+\code
+    LoginWidget::LoginWidget()
+    {
+        QLabel *label = new QLabel( tr("Password:"), this );
+        ...
+    }
+\endcode
+
+This accounts for 99% of the user-visible strings you're likely to
+write.
+
+If the quoted text is not in a member function of a
+QObject subclass, use either the tr() function of an
+appropriate class, or the QApplication::translate() function
+directly:
+
+\code
+    void some_global_function( LoginWidget *logwid )
+    {
+        QLabel *label = new QLabel(
+                LoginWidget::tr("Password:"), logwid );
+    }
+
+    void same_global_function( LoginWidget *logwid )
+    {
+        QLabel *label = new QLabel(
+                qApp->translate("LoginWidget", "Password:"),
+                logwid );
+    }
+\endcode
+
+If you need to have translatable text completely
+outside a function, there are two macros to help: QT_TR_NOOP()
+and QT_TRANSLATE_NOOP(). They merely mark the text for
+extraction by the \e lupdate utility described below.
+The macros expand to just the text (without the context).
+
+Example of QT_TR_NOOP():
+\code
+    QString FriendlyConversation::greeting( int greet_type )
+    {
+        static const char* greeting_strings[] = {
+            QT_TR_NOOP( "Hello" ),
+            QT_TR_NOOP( "Goodbye" )
+        };
+        return tr( greeting_strings[greet_type] );
+    }
+\endcode
+
+Example of QT_TRANSLATE_NOOP():
+\code
+    static const char* greeting_strings[] = {
+        QT_TRANSLATE_NOOP( "FriendlyConversation", "Hello" ),
+        QT_TRANSLATE_NOOP( "FriendlyConversation", "Goodbye" )
+    };
+
+    QString FriendlyConversation::greeting( int greet_type )
+    {
+        return tr( greeting_strings[greet_type] );
+    }
+
+    QString global_greeting( int greet_type )
+    {
+        return qApp->translate( "FriendlyConversation",
+                                greeting_strings[greet_type] );
+    }
+\endcode
+
+If you disable the const char* to QString automatic conversion
+by compiling your software with the macro QT_NO_CAST_ASCII
+defined, you'll be very likely to catch any strings you are
+missing. See QString::fromLatin1() for more information.
+Disabling the conversion can make programming a bit cumbersome.
+
+If your source language uses characters outside Latin-1, you
+might find QObject::trUtf8() more convenient than
+QObject::tr(), as tr() depends on the
+QApplication::defaultCodec(), which makes it more fragile than
+QObject::trUtf8().
+
+\section2 Use QKeySequence() for Accelerator Values
+
+Accelerator values such as Ctrl+Q or Alt+F need to be
+translated too. If you hardcode \c CTRL+Key_Q for "Quit" in
+your application, translators won't be able to override
+it. The correct idiom is
+
+\code
+    QPopupMenu *file = new QPopupMenu( this );
+    file->insertItem( tr("&Quit"), this, SLOT(quit()),
+                      QKeySequence(tr("Ctrl+Q", "File|Quit")) );
+\endcode
+
+\section2 Use QString::arg() for Dynamic Text
+
+The QString::arg() functions offer a simple means for substituting
+arguments:
+\code
+    void FileCopier::showProgress( int done, int total,
+                                   const QString& current_file )
+    {
+        label.setText( tr("%1 of %2 files copied.\nCopying: %3")
+                        .arg(done)
+                        .arg(total)
+                        .arg(current_file) );
+    }
+\endcode
+
+In some languages the order of arguments may need to change, and this
+can easily be achieved by changing the order of the % arguments. For
+example:
+\code
+    QString s1 = "%1 of %2 files copied. Copying: %3";
+    QString s2 = "Kopierer nu %3. Av totalt %2 filer er %1 kopiert.";
+
+    qDebug( s1.arg(5).arg(10).arg("somefile.txt").ascii() );
+    qDebug( s2.arg(5).arg(10).arg("somefile.txt").ascii() );
+\endcode
+
+produces the correct output in English and Norwegian:
+\code
+5 of 10 files copied. Copying: somefile.txt
+Kopierer nu somefile.txt. Av totalt 10 filer er 5 kopiert.
+\endcode
+
+\section2 Produce Translations
+
+Once you are using tr() throughout an application, you can start
+producing translations of the user-visible text in your program.
+
+\link linguist-manual.book Qt Linguist\endlink's manual provides
+further information about Qt's translation tools, \e{Qt Linguist}, \e
+lupdate and \e lrelease.
+
+Translation of a Qt application is a three-step process:
+
+\list 1
+
+\i Run \e lupdate to extract translatable text from the C++ source
+code of the Qt application, resulting in a message file for
+translators (a \c .ts file). The utility recognizes the tr() construct
+and the QT_*_NOOP macros described above and produces \c .ts files
+(usually one per language).
+
+\i Provide translations for the source texts in the \c .ts file, using
+\e{Qt Linguist}. Since \c .ts files are in XML format, you can also
+edit them by hand.
+
+\i Run \e lrelease to obtain a light-weight message file (a \c .qm
+file) from the \c .ts file, suitable only for end use. Think of the \c
+.ts files as "source files", and \c .qm files as "object files". The
+translator edits the \c .ts files, but the users of your application
+only need the \c .qm files. Both kinds of files are platform and
+locale independent.
+
+\endlist
+
+Typically, you will repeat these steps for every release of your
+application. The \e lupdate utility does its best to reuse the
+translations from previous releases.
+
+Before you run \e lupdate, you should prepare a project file. Here's
+an example project file (\c .pro file):
+
+\code
+    HEADERS         = funnydialog.h \
+                      wackywidget.h
+    SOURCES         = funnydialog.cpp \
+                      main.cpp \
+                      wackywidget.cpp
+    FORMS           = fancybox.ui
+    TRANSLATIONS    = superapp_dk.ts \
+                      superapp_fi.ts \
+                      superapp_no.ts \
+                      superapp_se.ts
+\endcode
+
+When you run \e lupdate or \e lrelease, you must give the name of the
+project file as a command-line argument.
+
+In this example, four exotic languages are supported: Danish, Finnish,
+Norwegian and Swedish. If you use \link qmake-manual.book
+qmake\endlink, you usually don't need an extra project
+file for \e lupdate; your \c qmake project file will work fine once
+you add the \c TRANSLATIONS entry.
+
+In your application, you must \l QTranslator::load() the translation
+files appropriate for the user's language, and install them using \l
+QApplication::installTranslator().
+
+If you have been using the old Qt tools (\c findtr, \c msg2qm and \c
+mergetr), you can use \e qm2ts to convert your old \c .qm files.
+
+\e linguist, \e lupdate and \e lrelease are installed in the \c bin
+subdirectory of the base directory Qt is installed into. Click Help|Manual
+in \e{Qt Linguist} to access the user's manual; it contains a tutorial
+to get you started.
+
+While these utilities offer a convenient way to create \c .qm files,
+any system that writes \c .qm files is sufficient. You could make an
+application that adds translations to a QTranslator with
+QTranslator::insert() and then writes a \c .qm file with
+QTranslator::save(). This way the translations can come from any
+source you choose.
+
+\target qt-itself
+Qt itself contains over 400 strings that will also need to be
+translated into the languages that you are targeting. You will find
+translation files for French and German in \c $QTDIR/translations as
+well as a template for translating to other languages. (This directory
+also contains some additional unsupported translations which may be
+useful.)
+
+Typically, your application's main() function will look like this:
+\code
+    int main( int argc, char **argv )
+    {
+        QApplication app( argc, argv );
+
+        // translation file for Qt
+        QTranslator qt( 0 );
+        qt.load( QString( "qt_" ) + QTextCodec::locale(), "." );
+        app.installTranslator( &qt );
+
+        // translation file for application strings
+        QTranslator myapp( 0 );
+        myapp.load( QString( "myapp_" ) + QTextCodec::locale(), "." );
+        app.installTranslator( &myapp );
+
+        ...
+
+        return app.exec();
+    }
+\endcode
+
+\section2 Support for Encodings
+
+The QTextCodec class and the facilities in QTextStream make it easy to
+support many input and output encodings for your users' data. When an
+application starts, the locale of the machine will determine the 8-bit
+encoding used when dealing with 8-bit data: such as for font
+selection, text display, 8-bit text I/O and character input.
+
+The application may occasionally require encodings other than the
+default local 8-bit encoding. For example, an application in a
+Cyrillic KOI8-R locale (the de-facto standard locale in Russia) might
+need to output Cyrillic in the ISO 8859-5 encoding. Code for this
+would be:
+
+\code
+    QString string = ...; // some Unicode text
+
+    QTextCodec* codec = QTextCodec::codecForName( "ISO 8859-5" );
+    QCString encoded_string = codec->fromUnicode( string );
+
+    ...; // use encoded_string in 8-bit operations
+\endcode
+
+For converting Unicode to local 8-bit encodings, a shortcut is
+available: the \link QString::local8Bit() local8Bit\endlink() method
+of QString returns such 8-bit data. Another useful shortcut is the
+\link QString::utf8() utf8\endlink() method, which returns text in the
+8-bit UTF-8 encoding: this perfectly preserves Unicode information
+while looking like plain US-ASCII if the text is wholly US-ASCII.
+
+For converting the other way, there are the QString::fromUtf8() and
+QString::fromLocal8Bit() convenience functions, or the general code,
+demonstrated by this conversion from ISO 8859-5 Cyrillic to Unicode
+conversion:
+
+\code
+    QCString encoded_string = ...; // Some ISO 8859-5 encoded text.
+
+    QTextCodec* codec = QTextCodec::codecForName("ISO 8859-5");
+    QString string = codec->toUnicode(encoded_string);
+
+    ...; // Use string in all of Qt's QString operations.
+\endcode
+
+Ideally Unicode I/O should be used as this maximizes the portability
+of documents between users around the world, but in reality it is
+useful to support all the appropriate encodings that your users will
+need to process existing documents. In general, Unicode (UTF-16 or
+UTF-8) is best for information transferred between arbitrary people,
+while within a language or national group, a local standard is often
+more appropriate. The most important encoding to support is the one
+returned by QTextCodec::codecForLocale(), as this is the one the user
+is most likely to need for communicating with other people and
+applications (this is the codec used by local8Bit()).
+
+Qt supports most of the more frequently used encodings natively. For a
+complete list of supported encodings see the \l QTextCodec
+documentation.
+
+In some cases and for less frequently used encodings it may be
+necessary to write your own QTextCodec subclass. Depending on the
+urgency, it may be useful to contact Trolltech technical support or
+ask on the \c qt-interest mailing list to see if someone else is
+already working on supporting the encoding. A useful interim measure
+can be to use the QTextCodec::loadCharmapFile() function to build a
+data-driven codec, although this approach has a memory and speed
+penalty, especially with dynamically loaded libraries. For details of
+writing your own QTextCodec, see the main QTextCodec class
+documentation.
+
+\keyword localization
+
+\section2 Localize
+
+Localization is the process of adapting to local conventions, for
+example presenting dates and times using the locally preferred
+formats. Such localizations can be accomplished using appropriate tr()
+strings.
+
+\code
+    void Clock::setTime(const QTime& t)
+    {
+        if ( tr("AMPM") == "AMPM" ) {
+            // 12-hour clock
+        } else {
+            // 24-hour clock
+        }
+    }
+\endcode
+
+In the example, for the US we would leave the translation of "AMPM" as
+it is and thereby use the 12-hour clock branch; but in Europe we would
+translate it as something else (anything else, e.g. "EU") and this
+will make the code use the 24-hour clock branch.
+
+Localizing images is not recommended. Choose clear icons that are
+appropriate for all localities, rather than relying on local puns or
+stretched metaphors.
+
+\section1 Dynamic Translation
+
+Some applications, such as Qt Linguist, must be able to support changes
+to the user's language settings while they are still running. To make
+widgets aware of changes to the system language, implement a public
+slot called \c languageChange() in each widget that needs to be notified.
+In this slot, you should update the text displayed by widgets using the
+\l{QObject::tr()}{tr()} function in the usual way; for example:
+
+\code
+void MyWidget::languageChange()
+{
+    titleLabel->setText(tr("Document Title"));
+    ...
+    okPushButton->setText(tr("&OK"));
+}
+\endcode
+
+The default event handler for QWidget subclasses responds to the
+\link QEvent::Type LanguageChange\endlink event, and will call this slot
+when necessary; other application components can also connect signals
+to this slot to force widgets to update themselves.
+
+\section1 System Support
+
+Some of the operating systems and windowing systems that Qt runs on
+only have limited support for Unicode. The level of support available
+in the underlying system has some influence on the support that Qt can
+provide on those platforms, although in general Qt applications need
+not be too concerned with platform-specific limitations.
+
+\section2 Unix/X11
+
+\list
+\i Locale-oriented fonts and input methods. Qt hides these and
+    provides Unicode input and output.
+\i Filesystem conventions such as
+    \link http://www.ietf.org/rfc/rfc2279.txt UTF-8 \endlink
+    are under development
+    in some Unix variants. All Qt file functions allow Unicode,
+    but convert filenames to the local 8-bit encoding, as
+    this is the Unix convention
+    (see QFile::setEncodingFunction()
+        to explore alternative encodings).
+\i File I/O defaults to the local 8-bit encoding,
+    with Unicode options in QTextStream.
+\endlist
+
+\section2 Windows
+
+\list
+\i Qt provides full Unicode support, including input methods, fonts,
+    clipboard, drag-and-drop and file names.
+\i File I/O defaults to Latin-1, with Unicode options in QTextStream.
+    Note that some Windows programs do not understand big-endian
+    Unicode text files even though that is the order prescribed by
+    the Unicode Standard in the absence of higher-level protocols.
+\i Unlike programs written with MFC or plain winlib, Qt programs
+    are portable between Windows 95/98 and Windows NT.
+    \e {You do not need different binaries to support Unicode.}
+\endlist
+
+\section1 Note about Locales on X11
+
+Many Unix distributions contain only partial support for some locales.
+For example, if you have a \c /usr/share/locale/ja_JP.EUC directory,
+this does not necessarily mean you can display Japanese text; you also
+need JIS encoded fonts (or Unicode fonts), and the \c
+/usr/share/locale/ja_JP.EUC directory needs to be complete. For best
+results, use complete locales from your system vendor.
+
+\section1 Relevant Qt Classes
+
+These classes are relevant to internationalizing Qt applications.
+*/