--- /dev/null Thu Jan 01 00:00:00 1970 +0000
+++ b/doc/src/examples/arrowpad.qdoc Wed Mar 31 11:06:36 2010 +0300
@@ -0,0 +1,237 @@
+/****************************************************************************
+**
+** Copyright (C) 2010 Nokia Corporation and/or its subsidiary(-ies).
+** All rights reserved.
+** Contact: Nokia Corporation (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 Technology Preview License Agreement accompanying
+** this package.
+**
+** 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.1, included in the file LGPL_EXCEPTION.txt in this package.
+**
+** If you have questions regarding the use of this file, please contact
+** Nokia at qt-info@nokia.com.
+**
+**
+**
+**
+**
+**
+**
+**
+** $QT_END_LICENSE$
+**
+****************************************************************************/
+
+/*!
+ \example linguist/arrowpad
+ \title Arrow Pad Example
+
+ This example is a slightly more involved and introduces a key \e
+ {Qt Linguist} concept: "contexts". It also shows how to use two
+ or more languages.
+
+ \image linguist-arrowpad_en.png
+
+ We will use two translations, French and Dutch, although there is no
+ effective limit on the number of possible translations that can be used
+ with an application. The relevant lines of \c arrowpad.pro are
+
+ \snippet examples/linguist/arrowpad/arrowpad.pro 0
+ \codeline
+ \snippet examples/linguist/arrowpad/arrowpad.pro 1
+
+ Run \c lupdate; it should produce two identical message files
+ \c arrowpad_fr.ts and \c arrowpad_nl.ts. These files will contain all the source
+ texts marked for translation with \c tr() calls and their contexts.
+
+ See the \l{Qt Linguist manual} for more information about
+ translating Qt application.
+
+ \section1 Line by Line Walkthrough
+
+ In \c arrowpad.h we define the \c ArrowPad subclass which is a
+ subclass of QWidget. In the screenshot above, the central
+ widget with the four buttons is an \c ArrowPad.
+
+ \snippet examples/linguist/arrowpad/arrowpad.h 0
+ \snippet examples/linguist/arrowpad/arrowpad.h 1
+ \snippet examples/linguist/arrowpad/arrowpad.h 2
+
+ When \c lupdate is run it not only extracts the source texts but it
+ also groups them into contexts. A context is the name of the class in
+ which the source text appears. Thus, in this example, "ArrowPad" is a
+ context: it is the context of the texts in the \c ArrowPad class.
+ The \c Q_OBJECT macro defines \c tr(x) in \c ArrowPad like this:
+
+ \snippet doc/src/snippets/code/doc_src_examples_arrowpad.qdoc 0
+
+ Knowing which class each source text appears in enables \e {Qt
+ Linguist} to group texts that are logically related together, e.g.
+ all the text in a dialog will have the context of the dialog's class
+ name and will be shown together. This provides useful information for
+ the translator since the context in which text appears may influence how
+ it should be translated. For some translations keyboard
+ accelerators may need to be changed and having all the source texts in a
+ particular context (class) grouped together makes it easier for the
+ translator to perform any accelerator changes without introducing
+ conflicts.
+
+ In \c arrowpad.cpp we implement the \c ArrowPad class.
+
+ \snippet examples/linguist/arrowpad/arrowpad.cpp 0
+ \snippet examples/linguist/arrowpad/arrowpad.cpp 1
+ \snippet examples/linguist/arrowpad/arrowpad.cpp 2
+ \snippet examples/linguist/arrowpad/arrowpad.cpp 3
+
+ We call \c ArrowPad::tr() for each button's label since the labels are
+ user-visible text.
+
+ \image linguist-arrowpad_en.png
+
+ \snippet examples/linguist/arrowpad/mainwindow.h 0
+ \snippet examples/linguist/arrowpad/mainwindow.h 1
+
+ In the screenshot above, the whole window is a \c MainWindow.
+ This is defined in the \c mainwindow.h header file. Here too, we
+ use \c Q_OBJECT, so that \c MainWindow will become a context in
+ \e {Qt Linguist}.
+
+ \snippet examples/linguist/arrowpad/mainwindow.cpp 0
+
+ In the implementation of \c MainWindow, \c mainwindow.cpp, we create
+ an instance of our \c ArrowPad class.
+
+ \snippet examples/linguist/arrowpad/mainwindow.cpp 1
+
+ We also call \c MainWindow::tr() twice, once for the action and
+ once for the shortcut.
+
+ Note the use of \c tr() to support different keys in other
+ languages. "Ctrl+Q" is a good choice for Quit in English, but a
+ Dutch translator might want to use "Ctrl+A" (for Afsluiten) and a
+ German translator "Strg+E" (for Beenden). When using \c tr() for
+ \key Ctrl key accelerators, the two argument form should be used
+ with the second argument describing the function that the
+ accelerator performs.
+
+ Our \c main() function is defined in \c main.cpp as usual.
+
+ \snippet examples/linguist/arrowpad/main.cpp 2
+ \snippet examples/linguist/arrowpad/main.cpp 3
+
+ We choose which translation to use according to the current locale.
+ QLocale::system() can be influenced by setting the \c LANG
+ environment variable, for example. Notice that the use of a naming
+ convention that incorporates the locale for \c .qm message files,
+ (and TS files), makes it easy to implement choosing the
+ translation file according to locale.
+
+ If there is no QM message file for the locale chosen the original
+ source text will be used and no error raised.
+
+ \section1 Translating to French and Dutch
+
+ We'll begin by translating the example application into French. Start
+ \e {Qt Linguist} with \c arrowpad_fr.ts. You should get the seven source
+ texts ("\&Up", "\&Left", etc.) grouped in two contexts ("ArrowPad"
+ and "MainWindow").
+
+ Now, enter the following translations:
+
+ \list
+ \o \c ArrowPad
+ \list
+ \o \&Up - \&Haut
+ \o \&Left - \&Gauche
+ \o \&Right - \&Droite
+ \o \&Down - \&Bas
+ \endlist
+ \o \c MainWindow
+ \list
+ \o E\&xit - \&Quitter
+ \o Ctrl+Q - Ctrl+Q
+ \o \&File - \&Fichier
+ \endlist
+ \endlist
+
+ It's quickest to press \key{Alt+D} (which clicks the \gui {Done \& Next}
+ button) after typing each translation, since this marks the
+ translation as done and moves on to the next source text.
+
+ Save the file and do the same for Dutch working with \c arrowpad_nl.ts:
+
+ \list
+ \o \c ArrowPad
+ \list
+ \o \&Up - \&Omhoog
+ \o \&Left - \&Links
+ \o \&Right - \&Rechts
+ \o \&Down - Omlaa\&g
+ \endlist
+ \o \c MainWindow
+ \list
+ \o E\&xit - \&Afsluiten
+ \o Ctrl+Q - Ctrl+A
+ \o File - \&Bestand
+ \endlist
+ \endlist
+
+ We have to convert the \c tt1_fr.ts and \c tt1_nl.ts translation source
+ files into QM files. We could use \e {Qt Linguist} as we've done
+ before; however using the command line tool \c lrelease ensures that
+ \e all the QM files for the application are created without us
+ having to remember to load and \gui File|Release each one
+ individually from \e {Qt Linguist}.
+
+ Type
+
+ \snippet doc/src/snippets/code/doc_src_examples_arrowpad.qdoc 1
+
+ This should create both \c arrowpad_fr.qm and \c arrowpad_nl.qm. Set the \c
+ LANG environment variable to \c fr. In Unix, one of the two following
+ commands should work
+
+ \snippet doc/src/snippets/code/doc_src_examples_arrowpad.qdoc 2
+
+ In Windows, either modify \c autoexec.bat or run
+
+ \snippet doc/src/snippets/code/doc_src_examples_arrowpad.qdoc 3
+
+ When you run the program, you should now see the French version:
+
+ \image linguist-arrowpad_fr.png
+
+ Try the same with Dutch, by setting \c LANG=nl. Now the Dutch
+ version should appear:
+
+ \image linguist-arrowpad_nl.png
+
+ \section1 Exercises
+
+ Mark one of the translations in \e {Qt Linguist} as not done, i.e.
+ by unchecking the "done" checkbox; run \c lupdate, then \c lrelease,
+ then the example. What effect did this change have?
+
+ Set \c LANG=fr_CA (French Canada) and run the example program again.
+ Explain why the result is the same as with \c LANG=fr.
+
+ Change one of the accelerators in the Dutch translation to eliminate the
+ conflict between \e \&Bestand and \e \&Boven.
+*/