doc/src/examples/arrowpad.qdoc

   1 /****************************************************************************
   2 **
   3 ** Copyright (C) 2015 The Qt Company Ltd.
   4 ** Contact: http://www.qt.io/licensing/
   5 **
   6 ** This file is part of the documentation of the Qt Toolkit.
   7 **
   8 ** $QT_BEGIN_LICENSE:FDL$
   9 ** Commercial License Usage
  10 ** Licensees holding valid commercial Qt licenses may use this file in
  11 ** accordance with the commercial license agreement provided with the
  12 ** Software or, alternatively, in accordance with the terms contained in
  13 ** a written agreement between you and The Qt Company. For licensing terms
  14 ** and conditions see http://www.qt.io/terms-conditions. For further
  15 ** information use the contact form at http://www.qt.io/contact-us.
  16 **
  17 ** GNU Free Documentation License Usage
  18 ** Alternatively, this file may be used under the terms of the GNU Free
  19 ** Documentation License version 1.3 as published by the Free Software
  20 ** Foundation and appearing in the file included in the packaging of
  21 ** this file.  Please review the following information to ensure
  22 ** the GNU Free Documentation License version 1.3 requirements
  23 ** will be met: http://www.gnu.org/copyleft/fdl.html.
  24 ** $QT_END_LICENSE$
  25 **
  26 ****************************************************************************/
  27
  28 /*!
  29     \example linguist/arrowpad
  30     \title Arrow Pad Example
  31
  32     \brief ThArrow Pad Linguist example is a slightly more involved and introduces a key \e
  33     {Qt Linguist} concept: "contexts". It also shows how to use two
  34     or more languages.
  35
  36     \image linguist-arrowpad_en.png
  37
  38     We will use two translations, French and Dutch, although there is no
  39     effective limit on the number of possible translations that can be used
  40     with an application. The relevant lines of \c arrowpad.pro are
  41
  42     \snippet examples/linguist/arrowpad/arrowpad.pro 0
  43     \codeline
  44     \snippet examples/linguist/arrowpad/arrowpad.pro 1
  45
  46     Run \c lupdate; it should produce two identical message files
  47     \c arrowpad_fr.ts and \c arrowpad_nl.ts. These files will contain all the source
  48     texts marked for translation with \c tr() calls and their contexts.
  49
  50     See the \l{Qt Linguist manual} for more information about
  51     translating Qt application.
  52
  53     \section1 Line by Line Walkthrough
  54
  55     In \c arrowpad.h we define the \c ArrowPad subclass which is a
  56     subclass of QWidget. In the screenshot above, the central
  57     widget with the four buttons is an \c ArrowPad.
  58
  59     \snippet examples/linguist/arrowpad/arrowpad.h 0
  60     \snippet examples/linguist/arrowpad/arrowpad.h 1
  61     \snippet examples/linguist/arrowpad/arrowpad.h 2
  62
  63     When \c lupdate is run it not only extracts the source texts but it
  64     also groups them into contexts. A context is the name of the class in
  65     which the source text appears. Thus, in this example, "ArrowPad" is a
  66     context: it is the context of the texts in the \c ArrowPad class.
  67     The \c Q_OBJECT macro defines \c tr(x) in \c ArrowPad like this:
  68
  69     \snippet doc/src/snippets/code/doc_src_examples_arrowpad.cpp 0
  70
  71     Knowing which class each source text appears in enables \e {Qt
  72     Linguist} to group texts that are logically related together, e.g.
  73     all the text in a dialog will have the context of the dialog's class
  74     name and will be shown together. This provides useful information for
  75     the translator since the context in which text appears may influence how
  76     it should be translated. For some translations keyboard
  77     accelerators may need to be changed and having all the source texts in a
  78     particular context (class) grouped together makes it easier for the
  79     translator to perform any accelerator changes without introducing
  80     conflicts.
  81
  82     In \c arrowpad.cpp we implement the \c ArrowPad class.
  83
  84     \snippet examples/linguist/arrowpad/arrowpad.cpp 0
  85     \snippet examples/linguist/arrowpad/arrowpad.cpp 1
  86     \snippet examples/linguist/arrowpad/arrowpad.cpp 2
  87     \snippet examples/linguist/arrowpad/arrowpad.cpp 3
  88
  89     We call \c ArrowPad::tr() for each button's label since the labels are
  90     user-visible text.
  91
  92     \image linguist-arrowpad_en.png
  93
  94     \snippet examples/linguist/arrowpad/mainwindow.h 0
  95     \snippet examples/linguist/arrowpad/mainwindow.h 1
  96
  97     In the screenshot above, the whole window is a \c MainWindow.
  98     This is defined in the \c mainwindow.h header file. Here too, we
  99     use \c Q_OBJECT, so that \c MainWindow will become a context in
 100     \e {Qt Linguist}.
 101
 102     \snippet examples/linguist/arrowpad/mainwindow.cpp 0
 103
 104     In the implementation of \c MainWindow, \c mainwindow.cpp, we create
 105     an instance of our \c ArrowPad class.
 106
 107     \snippet examples/linguist/arrowpad/mainwindow.cpp 1
 108
 109     We also call \c MainWindow::tr() twice, once for the action and
 110     once for the shortcut.
 111
 112     Note the use of \c tr() to support different keys in other
 113     languages. "Ctrl+Q" is a good choice for Quit in English, but a
 114     Dutch translator might want to use "Ctrl+A" (for Afsluiten) and a
 115     German translator "Strg+E" (for Beenden). When using \c tr() for
 116     \key Ctrl key accelerators, the two argument form should be used
 117     with the second argument describing the function that the
 118     accelerator performs.
 119
 120     Our \c main() function is defined in \c main.cpp as usual.
 121
 122     \snippet examples/linguist/arrowpad/main.cpp 2
 123     \snippet examples/linguist/arrowpad/main.cpp 3
 124
 125     We choose which translation to use according to the current locale.
 126     QLocale::system() can be influenced by setting the \c LANG
 127     environment variable, for example. Notice that the use of a naming
 128     convention that incorporates the locale for \c .qm message files,
 129     (and TS files), makes it easy to implement choosing the
 130     translation file according to locale.
 131
 132     If there is no QM message file for the locale chosen the original
 133     source text will be used and no error raised.
 134
 135     \section1 Translating to French and Dutch
 136
 137     We'll begin by translating the example application into French. Start
 138     \e {Qt Linguist} with \c arrowpad_fr.ts. You should get the seven source
 139     texts ("\&Up", "\&Left", etc.) grouped in two contexts ("ArrowPad"
 140     and "MainWindow").
 141
 142     Now, enter the following translations:
 143
 144     \list
 145     \o \c ArrowPad
 146          \list
 147          \o \&Up - \&Haut
 148          \o \&Left - \&Gauche
 149          \o \&Right - \&Droite
 150          \o \&Down - \&Bas
 151          \endlist
 152     \o \c MainWindow
 153          \list
 154          \o E\&xit - \&Quitter
 155          \o Ctrl+Q - Ctrl+Q
 156          \o \&File - \&Fichier
 157          \endlist
 158     \endlist
 159
 160     It's quickest to press \key{Alt+D} (which clicks the \gui {Done \& Next}
 161     button) after typing each translation, since this marks the
 162     translation as done and moves on to the next source text.
 163
 164     Save the file and do the same for Dutch working with \c arrowpad_nl.ts:
 165
 166     \list
 167     \o \c ArrowPad
 168          \list
 169          \o \&Up - \&Omhoog
 170          \o \&Left - \&Links
 171          \o \&Right - \&Rechts
 172          \o \&Down - Omlaa\&g
 173          \endlist
 174     \o \c MainWindow
 175          \list
 176          \o E\&xit - \&Afsluiten
 177          \o Ctrl+Q - Ctrl+A
 178          \o File - \&Bestand
 179          \endlist
 180     \endlist
 181
 182     We have to convert the \c tt1_fr.ts and \c tt1_nl.ts translation source
 183     files into QM files. We could use \e {Qt Linguist} as we've done
 184     before; however using the command line tool \c lrelease ensures that
 185     \e all the QM files for the application are created without us
 186     having to remember to load and \gui File|Release each one
 187     individually from \e {Qt Linguist}.
 188
 189     Type
 190
 191     \snippet doc/src/snippets/code/doc_src_examples_arrowpad.qdoc 1
 192
 193     This should create both \c arrowpad_fr.qm and \c arrowpad_nl.qm. Set the \c
 194     LANG environment variable to \c fr. In Unix, one of the two following
 195     commands should work
 196
 197     \snippet doc/src/snippets/code/doc_src_examples_arrowpad.qdoc 2
 198
 199     In Windows, either modify \c autoexec.bat or run
 200
 201     \snippet doc/src/snippets/code/doc_src_examples_arrowpad.qdoc 3
 202
 203     When you run the program, you should now see the French version:
 204
 205     \image linguist-arrowpad_fr.png
 206
 207     Try the same with Dutch, by setting \c LANG=nl. Now the Dutch
 208     version should appear:
 209
 210     \image linguist-arrowpad_nl.png
 211
 212     \section1 Exercises
 213
 214     Mark one of the translations in \e {Qt Linguist} as not done, i.e.
 215     by unchecking the "done" checkbox; run \c lupdate, then \c lrelease,
 216     then the example. What effect did this change have?
 217
 218     Set \c LANG=fr_CA (French Canada) and run the example program again.
 219     Explain why the result is the same as with \c LANG=fr.
 220
 221     Change one of the accelerators in the Dutch translation to eliminate the
 222     conflict between \e \&Bestand and \e \&Boven.
 223 */