|
1 /**************************************************************************** |
|
2 ** |
|
3 ** Copyright (C) 2010 Nokia Corporation and/or its subsidiary(-ies). |
|
4 ** All rights reserved. |
|
5 ** Contact: Nokia Corporation (qt-info@nokia.com) |
|
6 ** |
|
7 ** This file is part of the documentation of the Qt Toolkit. |
|
8 ** |
|
9 ** $QT_BEGIN_LICENSE:LGPL$ |
|
10 ** No Commercial Usage |
|
11 ** This file contains pre-release code and may not be distributed. |
|
12 ** You may use this file in accordance with the terms and conditions |
|
13 ** contained in the Technology Preview License Agreement accompanying |
|
14 ** this package. |
|
15 ** |
|
16 ** GNU Lesser General Public License Usage |
|
17 ** Alternatively, this file may be used under the terms of the GNU Lesser |
|
18 ** General Public License version 2.1 as published by the Free Software |
|
19 ** Foundation and appearing in the file LICENSE.LGPL included in the |
|
20 ** packaging of this file. Please review the following information to |
|
21 ** ensure the GNU Lesser General Public License version 2.1 requirements |
|
22 ** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html. |
|
23 ** |
|
24 ** In addition, as a special exception, Nokia gives you certain additional |
|
25 ** rights. These rights are described in the Nokia Qt LGPL Exception |
|
26 ** version 1.1, included in the file LGPL_EXCEPTION.txt in this package. |
|
27 ** |
|
28 ** If you have questions regarding the use of this file, please contact |
|
29 ** Nokia at qt-info@nokia.com. |
|
30 ** |
|
31 ** |
|
32 ** |
|
33 ** |
|
34 ** |
|
35 ** |
|
36 ** |
|
37 ** |
|
38 ** $QT_END_LICENSE$ |
|
39 ** |
|
40 ****************************************************************************/ |
|
41 |
|
42 /*! |
|
43 \example script/helloscript |
|
44 \title Hello Script Example |
|
45 |
|
46 The Hello Script example shows the basic use of Qt Script: How to embed |
|
47 a script engine into the application, how to evaluate a script, and how |
|
48 to process the result of the evaluation. The example also shows how to |
|
49 apply internationalization to scripts. |
|
50 |
|
51 \snippet examples/script/helloscript/main.cpp 0 |
|
52 |
|
53 The application will load the script file to evaluate from a resource, so |
|
54 we first make sure that the resource is initialized. |
|
55 |
|
56 \snippet examples/script/helloscript/main.cpp 1 |
|
57 |
|
58 We attempt to load a translation, and install translation functions in the |
|
59 script engine. How to produce a translation is explained later. |
|
60 |
|
61 \snippet examples/script/helloscript/main.cpp 2 |
|
62 |
|
63 A push button is created and exported to the script environment as a |
|
64 global variable, \c button. Scripts will be able to access properties, |
|
65 signals and slots of the button as properties of the \c button script |
|
66 object; the script object acts as a proxy to the C++ button object. |
|
67 |
|
68 \snippet examples/script/helloscript/main.cpp 3 |
|
69 |
|
70 The contents of the script file are read. |
|
71 |
|
72 \snippet examples/script/helloscript/helloscript.js 0 |
|
73 |
|
74 The script sets the \c text (note that the qTr() function is used to allow |
|
75 for translation) and \c styleSheet properties of the button, and calls the |
|
76 button's \c show() slot. |
|
77 |
|
78 \snippet examples/script/helloscript/main.cpp 4 |
|
79 |
|
80 The script is evaluated. Note that the file name is passed as the |
|
81 (optional) second parameter; this makes it possible for the script engine |
|
82 to produce a meaningful backtrace if something goes wrong, and makes the |
|
83 qTr() function be able to resolve the translations that are associated |
|
84 with this script. |
|
85 |
|
86 \snippet examples/script/helloscript/main.cpp 5 |
|
87 |
|
88 If the result is an Error object (e.g. the script contained a syntax |
|
89 error, or tried to call a function that doesn't exist), we obtain |
|
90 the line number and string representation of the error and display |
|
91 it in a message box. |
|
92 |
|
93 \snippet examples/script/helloscript/main.cpp 6 |
|
94 |
|
95 If the evaluation went well, the application event loop is entered. |
|
96 |
|
97 \section1 Translating the Application |
|
98 |
|
99 The Qt Script internalization support builds on what Qt already provides |
|
100 for C++; see the \l{Hello tr() Example} for an introduction. |
|
101 |
|
102 Since we haven't made the translation file \c helloscript_la.qm, the |
|
103 source text is shown when we run the application ("Hello world!"). |
|
104 |
|
105 To generate the translation file, run \c lupdate as follows: |
|
106 |
|
107 \code |
|
108 lupdate helloscript.js -ts helloscript_la.ts |
|
109 \endcode |
|
110 |
|
111 You should now have a file \c helloscript_la.ts in the current |
|
112 directory. Run \c linguist to edit the translation: |
|
113 |
|
114 \code |
|
115 linguist helloscript_la.ts |
|
116 \endcode |
|
117 |
|
118 You should now see the text "helloscript.js" in the top left pane. |
|
119 Double-click it, then click on "Hello world!" and enter "Orbis, te |
|
120 saluto!" in the \gui Translation pane (the middle right of the |
|
121 window). Don't forget the exclamation mark! |
|
122 |
|
123 Click the \gui Done checkbox and choose \gui File|Save from the |
|
124 menu bar. The TS file will no longer contain |
|
125 |
|
126 \snippet doc/src/snippets/code/doc_src_examples_hellotr.qdoc 3 |
|
127 |
|
128 but instead will have |
|
129 |
|
130 \snippet doc/src/snippets/code/doc_src_examples_hellotr.qdoc 4 |
|
131 |
|
132 To see the application running in Latin, we have to generate a QM |
|
133 file from the TS file. Generating a QM file can be achieved |
|
134 either from within \e {Qt Linguist} (for a single TS file), or |
|
135 by using the command line program \c lrelease which will produce one |
|
136 QM file for each of the TS files listed in the project file. |
|
137 Generate \c hellotr_la.qm from \c hellotr_la.ts by choosing |
|
138 \gui File|Release from \e {Qt Linguist}'s menu bar and pressing |
|
139 \gui Save in the file save dialog that pops up. Now run the \c helloscript |
|
140 program again. This time the button will be labelled "Orbis, te |
|
141 saluto!". |
|
142 */ |