diff options
Diffstat (limited to 'doc/src/examples/arrowpad.qdoc')
| -rw-r--r-- | doc/src/examples/arrowpad.qdoc | 223 |
1 files changed, 223 insertions, 0 deletions
diff --git a/doc/src/examples/arrowpad.qdoc b/doc/src/examples/arrowpad.qdoc new file mode 100644 index 0000000000..5e9cc9ae5a --- /dev/null +++ b/doc/src/examples/arrowpad.qdoc @@ -0,0 +1,223 @@ +/**************************************************************************** +** +** Copyright (C) 2011 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:FDL$ +** 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 Free Documentation License +** Alternatively, this file may be used under the terms of the GNU Free +** Documentation License version 1.3 as published by the Free Software +** Foundation and appearing in the file included in the packaging of this +** file. +** +** 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.cpp 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. +*/ |