Revision control
++ // Copyright (C) 2016 The Qt Company Ltd.
++ // SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only
++
++ /*!
++ \example arrowpad
++ \ingroup examples-linguist
++ \examplecategory {User Interface Components}
++
++ \title Arrow Pad Example
++
++ \brief Understanding the Qt Linguist \e contexts concept and using two
++ or more languages.
++
++ \image linguist-arrowpad_en.png {Screenshot of Arrow Pad in English}
++
++ 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.
++
++ When using qmake, the relevant lines in \c arrowpad.pro are:
++
++ \snippet arrowpad/arrowpad.pro 0
++ \codeline
++ \snippet arrowpad/arrowpad.pro 1
++
++ When using CMake, the relevant lines in \c CMakeLists.txt are:
++ \snippet arrowpad/CMakeLists.txt 0
++ \codeline
++ \snippet arrowpad/CMakeLists.txt 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.
++
++ When using qmake, \c lupdate must be run manually:
++
++ \snippet doc/snippets/doc_src_examples_arrowpad.qdoc 0
++
++ When using CMake, build the \c update_translations target to run \c lupdate:
++
++ \snippet doc/snippets/doc_src_examples_arrowpad.qdoc 4
++
++ See the \l{Qt Linguist Manual} for more information about
++ translating Qt applications.
++
++ \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 arrowpad/arrowpad.h 0
++ \snippet arrowpad/arrowpad.h 1
++ \snippet 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/snippets/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 arrowpad/arrowpad.cpp 0
++ \snippet arrowpad/arrowpad.cpp 1
++ \snippet arrowpad/arrowpad.cpp 2
++ \snippet 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 {Screenshot of Arrow Pad in English}
++
++ \snippet arrowpad/mainwindow.h 0
++ \snippet 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 arrowpad/mainwindow.cpp 0
++
++ In the implementation of \c MainWindow, \c mainwindow.cpp, we create
++ an instance of our \c ArrowPad class.
++
++ \snippet 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
++ \uicontrol 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 arrowpad/main.cpp 2
++ \snippet 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
++ \li \c ArrowPad
++ \list
++ \li \&Up - \&Haut
++ \li \&Left - \&Gauche
++ \li \&Right - \&Droite
++ \li \&Down - \&Bas
++ \endlist
++ \li \c MainWindow
++ \list
++ \li E\&xit - \&Quitter
++ \li Ctrl+Q - Ctrl+Q
++ \li \&File - \&Fichier
++ \endlist
++ \endlist
++
++ The \uicontrol {Done \& Next} button marks the
++ translation as done and moves on to the next source text.
++ It's quicker to use its short cut (see the Translation menu bar)
++ after typing each translation.
++
++ Save the file and do the same for Dutch working with \c arrowpad_nl.ts:
++
++ \list
++ \li \c ArrowPad
++ \list
++ \li \&Up - \&Omhoog
++ \li \&Left - \&Links
++ \li \&Right - \&Rechts
++ \li \&Down - Omlaa\&g
++ \endlist
++ \li \c MainWindow
++ \list
++ \li E\&xit - \&Afsluiten
++ \li Ctrl+Q - Ctrl+A
++ \li 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 \uicontrol File|Release each one
++ individually from \e {Qt Linguist}.
++
++ Type
++
++ \snippet doc/snippets/doc_src_examples_arrowpad.qdoc 1
++
++ when using CMake, type
++
++ \snippet doc/snippets/doc_src_examples_arrowpad.qdoc 5
++
++ This should create both \c arrowpad_fr.qm and \c arrowpad_nl.qm.
++
++ To use \c arrowpad_fr.qm, change your system language to French.
++ In Unix, one of the two following commands should work:
++
++ \snippet doc/snippets/doc_src_examples_arrowpad.qdoc 2
++
++ In Windows or Mac, set your display language to French.
++
++ When you run the program, you should now see the French version:
++
++ \image linguist-arrowpad_fr.png {Screenshot of Arrow Pad in French}
++
++ Try the same with Dutch (use \c LANG=nl in Unix). Now the Dutch
++ version should appear:
++
++ \image linguist-arrowpad_nl.png {Screenshot of Arrow Pad in Dutch}
++
++ \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.
++ */