Update copyright headers
[qt:qt.git] / doc / src / scripting / scripting.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     \group script
30     \title Scripting Classes and Overviews
31
32     \brief Classes that add scripting capabilities to Qt applications.
33 */
34
35 /*!
36   \page scripting.html
37   \title Making Applications Scriptable
38   \ingroup frameworks-technologies
39
40   Qt 4.3 and later provides support for application scripting with ECMAScript.
41   The following guides and references cover aspects of programming with
42   ECMAScript and Qt.
43
44   \tableofcontents
45
46   \section1 Scripting Classes
47
48   The following classes add scripting capabilities to Qt applications.
49
50   \annotatedlist script
51
52   \section1 Language Overview
53
54   Qt Script is based on the ECMAScript scripting language, as defined
55   in standard \l{ECMA-262}. Microsoft's JScript, and Netscape's
56   JavaScript are also based on the ECMAScript standard. For an
57   overview of ECMAScript, see the
58   \l{ECMAScript Reference}{ECMAScript reference}.
59   If you are not familiar with the ECMAScript language, there are
60   several existing tutorials and books that cover this subject, such
61   as \l{JavaScript: The Definitive Guide}.
62
63   Existing users of \l{Qt Script for Applications (QSA)} may find the
64   \l{Moving from QSA to Qt Script} document useful when porting
65   QSA scripts to Qt Script.
66
67   \section1 Basic Usage
68
69   To evaluate script code, you create a QScriptEngine and call its
70   evaluate() function, passing the script code (text) to evaluate
71   as argument.
72
73   \snippet doc/src/snippets/qtscript/evaluation/main.cpp 0
74
75   The return value will be the result of the evaluation (represented
76   as a QScriptValue object); this can be converted to standard C++
77   and Qt types.
78
79   Custom properties can be made available to scripts by registering
80   them with the script engine. This is most easily done by setting
81   properties of the script engine's \e{Global Object}:
82
83   \snippet doc/src/snippets/qtscript/registeringvalues/main.cpp 0
84
85   This places the properties in the script environment, thus making them
86   available to script code.
87
88   \section1 Making a QObject Available to the Script Engine
89
90   Any QObject-based instance can be made available for use with scripts.
91
92   When a QObject is passed to the QScriptEngine::newQObject() function,
93   a Qt Script wrapper object is created that can be used to make the
94   QObject's signals, slots, properties, and child objects available
95   to scripts.
96
97   Here's an example of making an instance of a QObject subclass
98   available to script code under the name \c{"myObject"}:
99
100   \snippet doc/src/snippets/qtscript/registeringobjects/main.cpp 0
101
102   This will create a global variable called \c{myObject} in the
103   script environment. The variable serves as a proxy to the
104   underlying C++ object. Note that the name of the script variable
105   can be anything; i.e., it is not dependent upon QObject::objectName().
106
107   The \l{QScriptEngine::}{newQObject()} function accepts two additional
108   optional arguments: one is the ownership mode, and the other is a
109   collection of options that allow you to control certain aspects of how
110   the QScriptValue that wraps the QObject should behave. We will come
111   back to the usage of these arguments later.
112
113   \section2 Using Signals and Slots
114
115   Qt Script adapts Qt's central \l{Signals and Slots} feature for
116   scripting. There are three principal ways to use signals and slots
117   with Qt Script:
118
119   \list
120   \i \bold{Hybrid C++/script}: C++ application code connects a
121   signal to a script function. The script function can, for example, be
122   a function that the user has typed in, or one that you have read from a
123   file. This approach is useful if you have a QObject but don't want
124   to expose the object itself to the scripting environment; you just
125   want a script to be able to define how a signal should be reacted
126   to, and leave it up to the C++ side of your application to establish
127   the connection.
128
129   \i \bold{Hybrid script/C++}: A script can connect signals and slots
130   to establish connections between pre-defined objects that the
131   application exposes to the scripting environment. In this scenario,
132   the slots themselves are still written in C++, but the definition of
133   the connections is fully dynamic (script-defined).
134
135   \i \bold{Purely script-defined}: A script can both define signal
136   handler functions (effectively "slots written in Qt Script"),
137   \e{and} set up the connections that utilize those handlers. For
138   example, a script can define a function that will handle the
139   QLineEdit::returnPressed() signal, and then connect that signal to the
140   script function.
141   \endlist
142
143   Use the qScriptConnect() function to connect a C++ signal to a
144   script function. In the following example a script signal handler is
145   defined that will handle the QLineEdit::textChanged() signal:
146
147   \snippet doc/src/snippets/code/doc_src_qtscript.cpp 47
148
149   The first two arguments to qScriptConnect() are the same
150   as you would pass to QObject::connect() to establish a normal C++
151   connection. The third argument is the script object that will act
152   as the \c this object when the signal handler is invoked; in the above
153   example we pass an invalid script value, so the \c this object will
154   be the Global Object. The fourth argument is the script function
155   ("slot") itself. The following example shows how the \c this argument
156   can be put to use:
157
158   \snippet doc/src/snippets/code/doc_src_qtscript.cpp 48
159
160   We create two QLineEdit objects and define a single signal handler
161   function. The connections use the same handler function, but the
162   function will be invoked with a different \c this object depending on
163   which object's signal was triggered, so the output of the print()
164   statement will be different for each.
165
166   In script code, Qt Script uses a different syntax for connecting to
167   and disconnecting from signals than the familiar C++ syntax; i.e.,
168   QObject::connect().
169   To connect to a signal, you reference the relevant signal as a property
170   of the sender object, and invoke its \c{connect()} function. There
171   are three overloads of \c{connect()}, each with a corresponding
172   \c{disconnect()} overload. The following subsections describe these
173   three forms.
174
175   \section3 Signal to Function Connections
176
177   \c{connect(function)}
178
179   In this form of connection, the argument to \c{connect()} is the
180   function to connect to the signal.
181
182   \snippet doc/src/snippets/code/doc_src_qtscript.js 2
183
184   The argument can be a Qt Script function, as in the above
185   example, or it can be a QObject slot, as in
186   the following example:
187
188   \snippet doc/src/snippets/code/doc_src_qtscript.js 3
189
190   When the argument is a QObject slot, the argument types of the
191   signal and slot do not necessarily have to be compatible;
192   QtScript will, if necessary, perform conversion of the signal
193   arguments to match the argument types of the slot.
194
195   To disconnect from a signal, you invoke the signal's
196   \c{disconnect()} function, passing the function to disconnect
197   as argument:
198
199   \snippet doc/src/snippets/code/doc_src_qtscript.js 4
200
201   When a script function is invoked in response to a signal, the
202   \c this object will be the Global Object.
203
204   \section3 Signal to Member Function Connections
205
206   \c{connect(thisObject, function)}
207
208   In this form of the \c{connect()} function, the first argument
209   is the object that will be bound to the variable, \c this, when
210   the function specified using the second argument is invoked.
211
212   If you have a push button in a form, you typically want to do
213   something involving the form in response to the button's
214   \c{clicked} signal; passing the form as the \c this object
215   makes sense in such a case.
216
217   \snippet doc/src/snippets/code/doc_src_qtscript.js 5
218
219   To disconnect from the signal, pass the same arguments to \c{disconnect()}:
220
221   \snippet doc/src/snippets/code/doc_src_qtscript.js 6
222
223   \section3 Signal to Named Member Function Connections
224
225   \c{connect(thisObject, functionName)}
226
227   In this form of the \c{connect()} function, the first argument is
228   the object that will be bound to the variable, \c this, when
229   a function is invoked in response to the signal. The second argument
230   specifies the name of a function that is connected to the signal,
231   and this refers to a member function of the object passed as the
232   first argument (\c thisObject in the above scheme).
233
234   Note that the function is resolved when the connection is made, not
235   when the signal is emitted.
236
237   \snippet doc/src/snippets/code/doc_src_qtscript.js 7
238
239   To disconnect from the signal, pass the same arguments to \c{disconnect()}:
240
241   \snippet doc/src/snippets/code/doc_src_qtscript.js 8
242
243   \section3 Error Handling
244
245   When \c{connect()} or \c{disconnect()} succeeds, the function will
246   return \c{undefined}; otherwise, it will throw a script exception.
247   You can obtain an error message from the resulting \c{Error} object.
248   Example:
249
250   \snippet doc/src/snippets/code/doc_src_qtscript.js 9
251
252   \section3 Emitting Signals from Scripts
253
254   To emit a signal from script code, you simply invoke the signal
255   function, passing the relevant arguments:
256
257   \snippet doc/src/snippets/code/doc_src_qtscript.js 10
258
259   It is currently not possible to define a new signal in a script;
260   i.e., all signals must be defined by C++ classes.
261
262   \section3 Overloaded Signals and Slots
263
264   When a signal or slot is overloaded, QtScript will attempt to
265   pick the right overload based on the actual types of the QScriptValue arguments
266   involved in the function invocation. For example, if your class has slots
267   \c{myOverloadedSlot(int)} and \c{myOverloadedSlot(QString)}, the following
268   script code will behave reasonably:
269
270   \snippet doc/src/snippets/code/doc_src_qtscript.js 11
271
272   You can specify a particular overload by using array-style property access
273   with the \l{QMetaObject::normalizedSignature()}{normalized signature} of
274   the C++ function as the property name:
275
276   \snippet doc/src/snippets/code/doc_src_qtscript.js 12
277
278   If the overloads have different number of arguments, QtScript will
279   pick the overload with the argument count that best matches the
280   actual number of arguments passed to the slot.
281
282   For overloaded signals, Qt Script will throw an error if you try to connect
283   to the signal by name; you have to refer to the signal with the full
284   normalized signature of the particular overload you want to connect to.
285
286   \section2 Accessing Properties
287
288   The properties of the QObject are available as properties
289   of the corresponding QtScript object. When you manipulate
290   a property in script code, the C++ get/set method for that
291   property will automatically be invoked. For example, if your
292   C++ class has a property declared as follows:
293
294   \snippet doc/src/snippets/code/doc_src_qtscript.cpp 13
295
296   then script code can do things like the following:
297
298   \snippet doc/src/snippets/code/doc_src_qtscript.js 14
299
300   \section2 Accessing Child QObjects
301
302   Every named child of the QObject (that is, for which
303   QObject::objectName() is not an empty string) is by default available as
304   a property of the QtScript wrapper object. For example,
305   if you have a QDialog with a child widget whose \c{objectName} property is
306   \c{"okButton"}, you can access this object in script code through
307   the expression
308
309   \snippet doc/src/snippets/code/doc_src_qtscript.js 15
310
311   Since \c{objectName} is itself a Q_PROPERTY, you can manipulate
312   the name in script code to, for example, rename an object:
313
314   \snippet doc/src/snippets/code/doc_src_qtscript.js 16
315
316   You can also use the functions \c{findChild()} and \c{findChildren()}
317   to find children. These two functions behave identically to
318   QObject::findChild() and QObject::findChildren(), respectively.
319
320   For example, we can use these functions to find objects using strings
321   and regular expressions:
322
323   \snippet doc/src/snippets/code/doc_src_qtscript.js 17
324
325   You typically want to use \c{findChild()} when manipulating a form
326   that uses nested layouts; that way the script is isolated from the
327   details about which particular layout a widget is located in.
328
329   \section2 Controlling QObject Ownership
330
331   Qt Script uses garbage collection to reclaim memory used by script
332   objects when they are no longer needed; an object's memory can be
333   automatically reclaimed when it is no longer referenced anywhere in
334   the scripting environment. Qt Script lets you control what happens
335   to the underlying C++ QObject when the wrapper object is reclaimed
336   (i.e., whether the QObject is deleted or not); you do this when you
337   create an object by passing an ownership mode as the second argument
338   to QScriptEngine::newQObject().
339
340   Knowing how Qt Script deals with ownership is important, since it can
341   help you avoid situations where a C++ object isn't deleted when it
342   should be (causing memory leaks), or where a C++ object \e{is}
343   deleted when it shouldn't be (typically causing a crash if C++ code
344   later tries to access that object).
345
346   \section3 Qt Ownership
347
348   By default, the script engine does not take ownership of the
349   QObject that is passed to QScriptEngine::newQObject(); the object
350   is managed according to Qt's object ownership (see
351   \l{Object Trees & Ownership}). This mode is appropriate
352   when, for example, you are wrapping C++ objects that are part of
353   your application's core; that is, they should persist regardless of
354   what happens in the scripting environment. Another way of stating
355   this is that the C++ objects should outlive the script engine.
356
357   \section3 Script Ownership
358
359   Specifying QScriptEngine::ScriptOwnership as the ownership mode
360   will cause the script engine to take full ownership of the QObject
361   and delete it when it determines that it is safe to do so
362   (i.e., when there are no more references to it in script code).
363   This ownership mode is appropriate if the QObject does not have a
364   parent object, and/or the QObject is created in the context of the
365   script engine and is not intended to outlive the script engine.
366
367   For example, a constructor function that constructs QObjects
368   only to be used in the script environment is a good candidate:
369
370   \snippet doc/src/snippets/code/doc_src_qtscript.cpp 18
371
372   \section3 Auto-Ownership
373
374   With QScriptEngine::AutoOwnership the ownership is based on whether
375   the QObject has a parent or not.
376   If the QtScript garbage collector finds that the QObject is no
377   longer referenced within the script environment, the QObject will
378   be deleted \e{only} if it does not have a parent.
379
380   \section3 What Happens When Someone Else Deletes the QObject?
381
382   It is possible that a wrapped QObject is deleted outside of
383   Qt Script's control; i.e., without regard to the ownership mode
384   specified. In this case, the wrapper object will still
385   be an object (unlike the C++ pointer it wraps, the script object
386   won't become null). Any attempt to access properties of the script
387   object will, however, result in a script exception being thrown.
388
389   Note that QScriptValue::isQObject() will still return true for a
390   deleted QObject, since it tests the type of the script object, not
391   whether the internal pointer is non-null. In other words, if
392   QScriptValue::isQObject() returns true but QScriptValue::toQObject()
393   returns a null pointer, this indicates that the QObject has been
394   deleted outside of Qt Script (perhaps accidentally).
395
396   \section2 Customizing Access to the QObject
397
398   QScriptEngine::newQObject() can take a third argument which allows
399   you to control various aspects of the access to the QObject through
400   the QtScript wrapper object it returns.
401
402   QScriptEngine::ExcludeChildObjects specifies that child objects of
403   the QObject should not appear as properties of the wrapper object.
404
405   QScriptEngine::ExcludeSuperClassProperties and
406   QScriptEngine::ExcludeSuperClassMethods can be used to avoid
407   exposing members that are inherited from the QObject's superclass.
408   This is useful for defining a "pure" interface where inherited members
409   don't make sense from a scripting perspective; e.g., you don't want
410   script authors to be able to change the \c{objectName} property of
411   the object or invoke the \c{deleteLater()} slot.
412
413   QScriptEngine::AutoCreateDynamicProperties specifies that properties
414   that don't already exist in the QObject should be created as dynamic
415   properties of the QObject, rather than as properties of the QtScript
416   wrapper object. If you want new properties to truly become persistent
417   properties of the QObject, rather than properties that are destroyed
418   along with the wrapper object (and that aren't shared if the QObject
419   is wrapped multiple times with QScriptEngine::newQObject()), you
420   should use this option.
421
422   QScriptEngine::SkipMethodsInEnumeration specifies that signals and
423   slots should be skipped when enumerating the properties of the QObject
424   wrapper in a for-in script statement. This is useful when defining
425   prototype objects, since by convention function properties of
426   prototypes should not be enumerable.
427
428   \section2 Making a QObject-based Class New-able from a Script
429
430   The QScriptEngine::newQObject() function is used to wrap an
431   existing QObject instance, so that it can be made available to
432   scripts. A different scenario is that you want scripts to be
433   able to construct new objects, not just access existing ones.
434
435   The Qt meta-type system currently does not provide dynamic
436   binding of constructors for QObject-based classes. If you want to
437   make such a class new-able from scripts, Qt Script can generate
438   a reasonable script constructor for you; see
439   QScriptEngine::scriptValueFromQMetaObject().
440
441   You can also use QScriptEngine::newFunction() to wrap your own
442   factory function, and add it to the script environment; see
443   QScriptEngine::newQMetaObject() for an example.
444
445   \section2 Enum Values
446
447   Values for enums declared with Q_ENUMS are not available as
448   properties of individual wrapper objects; rather, they are
449   properties of the QMetaObject wrapper object that can be created
450   with QScriptEngine::newQMetaObject().
451
452   \section1 Conversion Between QtScript and C++ Types
453
454   QtScript will perform type conversion when a value needs to be
455   converted from the script side to the C++ side or vice versa; for
456   instance, when a C++ signal triggers a script function, when
457   you access a QObject property in script code, or when
458   you call QScriptEngine::toScriptValue() or
459   QScriptEngine::fromScriptValue() in C++. QtScript provides default
460   conversion operations for many of the built-in Qt types. You can
461   change the conversion operation for a type (including your custom
462   C++ types) by registering your own conversion functions with
463   qScriptRegisterMetaType().
464
465   \section2 Default Conversion from Qt Script to C++
466
467   The following table describes the default conversion from a
468   QScriptValue to a C++ type.
469
470     \table 80%
471     \header \o C++ Type \o Default Conversion
472     \row    \o bool \o QScriptValue::toBool()
473     \row    \o int \o QScriptValue::toInt32()
474     \row    \o uint \o QScriptValue::toUInt32()
475     \row    \o float \o float(QScriptValue::toNumber())
476     \row    \o double \o QScriptValue::toNumber()
477     \row    \o short \o short(QScriptValue::toInt32())
478     \row    \o ushort \o QScriptValue::toUInt16()
479     \row    \o char \o char(QScriptValue::toInt32())
480     \row    \o uchar \o unsigned char(QScriptValue::toInt32())
481     \row    \o qlonglong \o qlonglong(QScriptValue::toInteger())
482     \row    \o qulonglong \o qulonglong(QScriptValue::toInteger())
483     \row    \o QString \o An empty string if the QScriptValue is null
484                or undefined; QScriptValue::toString() otherwise.
485     \row    \o QDateTime \o QScriptValue::toDateTime()
486     \row    \o QDate \o QScriptValue::toDateTime().date()
487     \row    \o QRegExp \o QScriptValue::toRegExp()
488     \row    \o QObject* \o QScriptValue::toQObject()
489     \row    \o QWidget* \o QScriptValue::toQObject()
490     \row    \o QVariant \o QScriptValue::toVariant()
491     \row    \o QChar \o If the QScriptValue is a string, the result
492                is the first character of the string, or a null QChar
493                if the string is empty; otherwise, the result is a QChar
494                constructed from the unicode obtained by converting the
495                QScriptValue to a \c{ushort}.
496     \row    \o QStringList \o If the QScriptValue is an array, the
497                result is a QStringList constructed from the result of
498                QScriptValue::toString() for each array element; otherwise,
499                the result is an empty QStringList.
500     \row    \o QVariantList \o If the QScriptValue is an array, the result
501                is a QVariantList constructed from the result of
502                QScriptValue::toVariant() for each array element; otherwise,
503                the result is an empty QVariantList.
504     \row    \o QVariantMap \o If the QScriptValue is an object, the result
505                is a QVariantMap with a (key, value) pair of the form
506                (propertyName, propertyValue.toVariant()) for each property,
507                using QScriptValueIterator to iterate over the object's
508                properties.
509     \row    \o QObjectList \o If the QScriptValue is an array, the result
510                is a QObjectList constructed from the result of
511                QScriptValue::toQObject() for each array element; otherwise,
512                the result is an empty QObjectList.
513     \row    \o QList<int> \o If the QScriptValue is an array, the result is
514                a QList<int> constructed from the result of
515                QScriptValue::toInt32() for each array element; otherwise,
516                the result is an empty QList<int>.
517     \endtable
518
519   Additionally, QtScript will handle the following cases:
520
521   \list
522   \i If the QScriptValue is a QObject and the target type name ends with
523      \c * (i.e., it is a pointer), the QObject pointer will be cast to the
524      target type with qobject_cast().
525   \i If the QScriptValue is a QVariant and the target type name ends with
526      \c * (i.e., it is a pointer), and the \l{QVariant::userType()}{userType()}
527      of the QVariant is the type that the target type points to, the result
528      is a pointer to the QVariant's data.
529   \i If the QScriptValue is a QVariant and it can be converted to the
530      target type (according to QVariant::canConvert()), the QVariant will
531      be cast to the target type with qvariant_cast().
532   \endlist
533
534   \section2 Default Conversion from C++ to Qt Script
535
536   The following table describes the default behavior when a QScriptValue is
537   constructed from a C++ type:
538
539     \table 80%
540     \header \o C++ Type \o Default Construction
541     \row    \o void \o QScriptEngine::undefinedValue()
542     \row    \o bool \o QScriptValue(engine, value)
543     \row    \o int \o QScriptValue(engine, value)
544     \row    \o uint \o QScriptValue(engine, value)
545     \row    \o float \o QScriptValue(engine, value)
546     \row    \o double \o QScriptValue(engine, value)
547     \row    \o short \o QScriptValue(engine, value)
548     \row    \o ushort \o QScriptValue(engine, value)
549     \row    \o char \o QScriptValue(engine, value)
550     \row    \o uchar \o QScriptValue(engine, value)
551     \row    \o QString \o QScriptValue(engine, value)
552     \row    \o qlonglong \o QScriptValue(engine, qsreal(value)). Note that
553                the conversion may lead to loss of precision, since not all
554                64-bit integers can be represented using the qsreal type.
555     \row    \o qulonglong \o QScriptValue(engine, qsreal(value)). Note that
556                the conversion may lead to loss of precision, since not all
557                64-bit unsigned integers can be represented using the qsreal
558                type.
559     \row    \o QChar \o QScriptValue(this, value.unicode())
560     \row    \o QDateTime \o \l{QScriptEngine::newDate()}{QScriptEngine::newDate}(value)
561     \row    \o QDate \o \l{QScriptEngine::newDate()}{QScriptEngine::newDate}(value)
562     \row    \o QRegExp \o \l{QScriptEngine::newRegExp()}{QScriptEngine::newRegExp}(value)
563     \row    \o QObject* \o \l{QScriptEngine::newQObject()}{QScriptEngine::newQObject}(value)
564     \row    \o QWidget* \o \l{QScriptEngine::newQObject()}{QScriptEngine::newQObject}(value)
565     \row    \o QVariant \o \l{QScriptEngine::newVariant()}{QScriptEngine::newVariant}(value)
566     \row    \o QStringList \o A new script array (created with
567                QScriptEngine::newArray()), whose elements are created using
568                the QScriptValue(QScriptEngine *, QString) constructor for
569                each element of the list.
570     \row    \o QVariantList \o A new script array (created with
571                QScriptEngine::newArray()), whose elements are created using
572                QScriptEngine::newVariant() for each element of the list.
573     \row    \o QVariantMap \o A new script object (created with
574                QScriptEngine::newObject()), whose properties are initialized
575                according to the (key, value) pairs of the map.
576     \row    \o QObjectList \o A new script array (created with
577                QScriptEngine::newArray()), whose elements are created using
578                QScriptEngine::newQObject() for each element of the list.
579     \row    \o QList<int> \o A new script array (created with
580                QScriptEngine::newArray()), whose elements are created using
581                the QScriptValue(QScriptEngine *, int) constructor for each
582                element of the list.
583     \endtable
584
585   Other types (including custom types) will be wrapped using
586   QScriptEngine::newVariant(). For null pointers of any type, the
587   result is QScriptEngine::nullValue().
588
589   \section1 How to Design and Implement Application Objects
590
591   This section explains how to implement application objects and
592   provides the necessary technical background material.
593
594   \section2 Making a C++ object available to Scripts Written in QtScript
595
596   Making C++ classes and objects available to a scripting language is
597   not trivial because scripting languages tend to be more dynamic than
598   C++, and it must be possible to introspect objects (query information
599   such as function names, function signatures, properties, etc., at
600   run-time). Standard C++ does not provide features for this.
601
602   We can achieve the functionality we want by extending C++, using
603   C++'s own facilities so our code is still standard C++. The Qt
604   meta-object system provides the necessary additional functionality.
605   It allows us to write using an extended C++ syntax, but converts this
606   into standard C++ using a small utility program called \l{moc}
607   (Meta-Object Compiler). Classes that wish to take advantage of the
608   meta-object facilities are either subclasses of QObject, or use the
609   \c{Q_OBJECT} macro. Qt has used this approach for many years and it has
610   proven to be solid and reliable. QtScript uses this meta-object
611   technology to provide scripters with dynamic access to C++ classes
612   and objects.
613
614   To completely understand how to make C++ objects available to Qt
615   Script, some basic knowledge of the Qt meta-object system is very
616   helpful. We recommend that you read about the Qt \l{Object Model}
617   and \l{The Meta-Object System}, which are useful for understanding
618   how to implement application objects.
619
620   However, this knowledge is not essential in the simplest cases.
621   To make an object available in QtScript, it must derive from
622   QObject. All classes which derive from QObject can be introspected
623   and can provide the information needed by the scripting engine at
624   run-time; e.g., class name, functions, signatures. Because we obtain
625   the information we need about classes dynamically at run-time, there
626   is no need to write wrappers for QObject derived classes.
627
628   \section2 Making C++ Class Member Functions Available in QtScript
629
630   The meta-object system also makes information about signals and slots
631   dynamically available at run-time. By default, for QObject subclasses,
632   only the signals and slots are automatically made available to scripts.
633   This is very convenient because, in practice, we normally only want to
634   make specially chosen functions available to scripters. When you create
635   a QObject subclass, make sure that the functions you want to expose to
636   QtScript are public slots.
637
638   For example, the following class definition enables scripting only for
639   certain functions:
640
641     \snippet doc/src/snippets/code/doc_src_qtscript.cpp 19
642
643   In the example above, aNonScriptableFunction() is not declared as a
644   slot, so it will not be available in QtScript. The other three
645   functions will automatically be made available in QtScript because
646   they are declared in the \c{public slots} section of the class
647   definition.
648
649   It is possible to make any function script-invokable by specifying
650   the \c{Q_INVOKABLE} modifier when declaring the function:
651
652   \snippet doc/src/snippets/code/doc_src_qtscript.cpp 20
653
654   Once declared with \c{Q_INVOKABLE}, the method can be invoked from
655   QtScript code just as if it were a slot. Although such a method is
656   not a slot, you can still specify it as the target function in a
657   call to \c{connect()} in script code; \c{connect()} accepts both
658   native and non-native functions as targets.
659
660   As discussed in \l{Default Conversion from Qt Script to C++}, Qt
661   Script handles conversion for many C++ types. If your function takes
662   arguments for which Qt Script does not handle conversion, you need
663   to supply conversion functions. This is done using the
664   qScriptRegisterMetaType() function.
665
666   \section2 Making C++ Class Properties Available in QtScript
667
668   In the previous example, if we wanted to get or set a property using
669   QtScript we would have to write code like the following:
670
671     \snippet doc/src/snippets/code/doc_src_qtscript.js 21
672
673   Scripting languages often provide a property syntax to modify and
674   retrieve properties (in our case the enabled state) of an
675   object. Many script programmers would want to write the above code
676   like this:
677
678     \snippet doc/src/snippets/code/doc_src_qtscript.js 22
679
680   To make this possible, you must define properties in the C++ QObject
681   subclass. For example, the following \c MyObject class declaration
682   declares a boolean property called \c enabled, which uses the function
683   \c{setEnabled(bool)} as its setter function and \c{isEnabled()} as its
684   getter function:
685
686     \snippet doc/src/snippets/code/doc_src_qtscript.cpp 23
687
688   The only difference from the original code is the use of the macro
689   \c{Q_PROPERTY}, which takes the type and name of the property, and
690   the names of the setter and getter functions as arguments.
691
692   If you don't want a property of your class to be accessible in
693   QtScript, you set the \c{SCRIPTABLE} attribute to \c false when
694   declaring the property; by default, the \c{SCRIPTABLE} attribute is
695   \c true. For example:
696
697   \snippet doc/src/snippets/code/doc_src_qtscript.cpp 24
698
699   \section2 Reacting to C++ Objects Signals in Scripts
700
701   In the Qt object model, signals are used as a notification mechanism
702   between QObjects. This means one object can connect a signal to
703   another object's slot and, every time the signal is emitted, the slot
704   is called. This connection is established using the QObject::connect()
705   function.
706
707   The signals and slots mechanism is also available to QtScript
708   programmers. The code to declare a signal in C++ is the same,
709   regardless of whether the signal will be connected to a slot in C++
710   or in QtScript.
711
712     \snippet doc/src/snippets/code/doc_src_qtscript.cpp 25
713
714   The only change we have made to the code in the previous section is
715   to declare a signals section with the relevant signal. Now, the
716   script writer can define a function and connect to the object like
717   this:
718
719     \snippet doc/src/snippets/code/doc_src_qtscript.js 26
720
721   \section2 Design of Application Objects
722
723   The previous section described how to implement C++ objects which
724   can be used in QtScript. Application objects are the same kind of
725   objects, and they make your application's functionality available to
726   QtScript scripters.  Since the C++ application is already written
727   in Qt, many objects are already QObjects. The easiest approach would
728   be to simply add all these QObjects as application objects to the
729   scripting engine. For small applications this might be sufficient,
730   but for larger applications this is probably not the right
731   approach. The problem is that this method reveals too much of the
732   internal API and gives script programmers access to application
733   internals which should not be exposed.
734
735   Generally, the best way of making application functionality available
736   to scripters is to code some QObjects which define the applications
737   public API using signals, slots, and properties. This gives you
738   complete control of the functionality made available by the
739   application. The implementations of these objects simply call the
740   functions in the application which do the real work. So, instead of
741   making all your QObjects available to the scripting engine, just add
742   the wrapper QObjects.
743
744   \section3 Returning QObject Pointers
745
746   If you have a slot that returns a QObject pointer, you should note
747   that, by default, Qt Script only handles conversion of the types
748   QObject* and QWidget*. This means that if your slot is declared
749   with a signature like "MyObject* getMyObject()", QtScript doesn't
750   automatically know that MyObject* should be handled in the same way
751   as QObject* and QWidget*. The simplest way to solve this is to only
752   use QObject* and QWidget* in the method signatures of your scripting
753   interface.
754
755   Alternatively, you can register conversion functions for your custom
756   type with the qScriptRegisterMetaType() function. In this way, you
757   can preserve the precise typing in your C++ declarations, while
758   still allowing pointers to your custom objects to flow seamlessly
759   between C++ and scripts. Example:
760
761     \snippet doc/src/snippets/code/doc_src_qtscript.cpp 43
762
763   \section1 Function Objects and Native Functions
764
765   In Qt Script, functions are first-class values; they are objects that
766   can have properties of their own, just like any other type of
767   object. They can be stored in variables and passed as arguments to
768   other functions. Knowing how function calls in Qt Script behave is
769   useful when you want to define and use your own script functions.
770   This section discusses this matter, and also explains how you can
771   implement native functions; that is, Qt Script functions written in
772   C++, as opposed to functions written in the scripting language
773   itself. Even if you will be relying mostly on the dynamic QObject
774   binding that Qt Script provides, knowing about these powerful
775   concepts and techniques is important to understand what's actually
776   going on when script functions are executed.
777
778   \section2 Calling a Qt Script Function from C++
779
780   Calling a Qt Script function from C++ is achieved with the
781   QScriptValue::call() function. A typical scenario is that you evaluate a
782   script that defines a function, and at some point you want to call that
783   function from C++, perhaps passing it some arguments, and then handle the
784   result. The following script defines a Qt Script object that has a
785   toKelvin() function:
786
787     \snippet doc/src/snippets/code/doc_src_qtscript.js 90
788
789   The toKelvin() function takes a temperature in Kelvin as argument, and
790   returns the temperature converted to Celsius. The following snippet shows
791   how the toKelvin() function might be obtained and called from C++:
792
793     \snippet doc/src/snippets/code/doc_src_qtscript.cpp 91
794
795   If a script defines a global function, you can access the function as a
796   property of QScriptEngine::globalObject(). For example, the following script
797   defines a global function add():
798
799     \snippet doc/src/snippets/code/doc_src_qtscript.js 56
800
801   C++ code might call the add() function as follows:
802
803     \snippet doc/src/snippets/code/doc_src_qtscript.cpp 92
804
805   As already mentioned, functions are just values in Qt Script; a function by
806   itself is not "tied to" a particular object. This is why you have to specify
807   a \c{this} object (the first argument to QScriptValue::call()) that the
808   function should be applied to.
809
810  If the function is supposed to act as a method (i.e. it can only be applied
811   to a certain class of objects), it is up to the function itself to check
812   that it is being called with a compatible \c{this} object.
813
814  Passing an invalid QScriptValue as the \c{this} argument to
815   QScriptValue::call() indicates that the Global Object should be used as the
816   \c{this} object; in other words, that the function should be invoked as a
817   global function.
818
819   \section2 The \c this Object
820
821   When a Qt Script function is invoked from a script, the \e{way} in which it
822   is invoked determines the \c this object when the function body is executed,
823   as the following script example illustrates:
824
825     \snippet doc/src/snippets/code/doc_src_qtscript.js 49
826
827   An important thing to note is that in Qt Script, unlike C++ and Java, the
828   \c this object is not part of the execution scope. This means that
829   member functions (i.e., functions that operate on \c this) must always
830   use the \c this keyword to access the object's properties. For example,
831   the following script probably doesn't do what you want:
832
833     \snippet doc/src/snippets/code/doc_src_qtscript.js 50
834
835   You will get a reference error saying that 'a is not defined' or, worse,
836   two totally unrelated global variables \c a and \c b will be used to
837   perform the computation, if they exist. Instead, the script should look
838   like this:
839
840     \snippet doc/src/snippets/code/doc_src_qtscript.js 51
841
842   Accidentally omitting the \c this keyword is a typical source of
843   error for programmers who are used to the scoping rules of C++ and Java.
844
845   \section2 Wrapping a Native Function
846
847   Qt Script provides QScriptEngine::newFunction() as a way of wrapping a
848   C++ function pointer; this enables you to implement a function in
849   C++ and add it to the script environment, so that scripts can invoke
850   your function as if it were a "normal" script function. Here is how the
851   previous \c{getProperty()} function can be written in C++:
852
853     \snippet doc/src/snippets/code/doc_src_qtscript.cpp 52
854
855   Call QScriptEngine::newFunction() to wrap the function. This will
856   produce a special type of function object that carries a pointer to
857   the C++ function internally. Once the resulting wrapper has been
858   added to the scripting environment (e.g., by setting it as a property
859   of the Global Object), scripts can call the function without having
860   to know nor care that it is, in fact, a native function.
861
862   Note that the name of the C++ function doesn't matter in the
863   scripting sense; the name by which the function is invoked by
864   scripts depends only on what you call the script object property
865   in which you store the function wrapper.
866
867   It is currently not possible to wrap member functions; i.e., methods
868   of a C++ class that require a \c this object.
869
870   \section2 The QScriptContext Object
871
872   A QScriptContext holds all the state associated with a particular
873   invocation of your function. Through the QScriptContext, you can:
874   \list
875   \i Get the arguments that were passed to the function.
876   \i Get the \c this object.
877   \i Find out whether the function was called with the \c new operator
878      (the significance of this will be explained later).
879   \i Throw a script error.
880   \i Get the function object that's being invoked.
881   \i Get the activation object (the object used to hold local variables).
882   \endlist
883
884   The following sections explain how to make use of this
885   functionality.
886
887   \section2 Processing Function Arguments
888
889   Two things are worth noting about function arguments:
890
891   \list 1
892   \o Any script function \mdash including native functions \mdash can
893   be invoked with any number of arguments. This means that it is up to
894   the function itself to check the argument count if necessary, and act
895   accordingly (e.g., throw an error if the number of arguments is
896   too large, or prepare a default value if the number is too small).
897   \o A value of any type can be supplied as an argument to any
898   function. This means that it is up to you to check the type of the
899   arguments if necessary, and act accordingly (e.g., throw an error
900   if an argument is not an object of a certain type).
901   \endlist
902
903   In summary: Qt Script does not automatically enforce any constraints on the
904   number or type of arguments involved in a function call.
905
906   \section3 Formal Parameters and the Arguments Object
907
908   A native Qt Script function is analogous to a script function that defines no
909   formal parameters and only uses the built-in \c arguments variable to
910   process its arguments. To see this, let's first consider how a
911   script would normally define an \c{add()} function that takes two
912   arguments, adds them together and returns the result:
913
914     \snippet doc/src/snippets/code/doc_src_qtscript.js 56
915
916   When a script function is defined with formal parameters, their
917   names can be viewed as mere aliases of properties of the \c
918   arguments object; for example, in the \c{add(a, b)} definition's
919   function body, \c a and \c arguments[0] refer to the same
920   variable. This means that the \c{add()} function can equivalently be
921   written like this:
922
923     \snippet doc/src/snippets/code/doc_src_qtscript.js 57
924
925   This latter form closely matches what a native implementation
926   typically looks like:
927
928     \snippet doc/src/snippets/code/doc_src_qtscript.cpp 58
929
930   \section3 Checking the Number of Arguments
931
932   Again, remember that the presence (or lack) of formal parameter
933   names in a function definition does not affect how the function
934   may be invoked; \c{add(1, 2, 3)} is allowed by the engine, as is
935   \c{add(42)}. In the case of the \c {add()} function, the function
936   really needs two arguments in order to do something useful. This
937   can be expressed by the script definition as follows:
938
939     \snippet doc/src/snippets/code/doc_src_qtscript.js 59
940
941   This would result in an error being thrown if a script invokes
942   \c{add()} with anything other than two arguments. The native
943   function can be modified to perform the same check:
944
945     \snippet doc/src/snippets/code/doc_src_qtscript.cpp 62
946
947   \section3 Checking the Types of Arguments
948
949   In addition to expecting a certain number of arguments, a function might
950   expect that those arguments are of certain types (e.g., that the first
951   argument is a number and that the second is a string). Such a function
952   should explicitly check the type of arguments and/or perform a conversion,
953   or throw an error if the type of an argument is incompatible.
954
955   As it is, the native implementation of \c{add()} shown above doesn't
956   have the exact same semantics as the script counterpart; this is
957   because the behavior of the Qt Script \c{+} operator depends on the
958   types of its operands (for example, if one of the operands is a string,
959   string concatenation is performed). To give the script function
960   stricter semantics (namely, that it should only add numeric
961   operands), the argument types can be tested:
962
963     \snippet doc/src/snippets/code/doc_src_qtscript.js 60
964
965   Then an invocation like \c{add("foo", new Array())} will
966   cause an error to be thrown.
967
968   The C++ version can call QScriptValue::isNumber() to perform similar
969   tests:
970
971     \snippet doc/src/snippets/code/doc_src_qtscript.cpp 63
972
973   A less strict script implementation might settle for performing an
974   explicit to-number conversion before applying the \c{+} operator:
975
976     \snippet doc/src/snippets/code/doc_src_qtscript.js 61
977
978   In a native implementation, this is equivalent to calling
979   QScriptValue::toNumber() without performing any type test first,
980   since QScriptValue::toNumber() will automatically perform a type
981   conversion if necessary.
982
983   To check if an argument is of a certain object type (class),
984   scripts can use the \c instanceof operator (e.g., \c{"arguments[0]
985   instanceof Array"} evaluates to true if the first argument is an
986   Array object); native functions can call QScriptValue::instanceOf().
987
988   To check if an argument is of a custom C++ type, you typically use
989   qscriptvalue_cast() and check if the result is valid. For object types,
990   this means casting to a pointer and checking if it is non-zero; for
991   value types, the class should have an \c{isNull()}, \c{isValid()}
992   or similar method. Alternatively, since most custom types are
993   transported in \l{QVariant}s, you can check if the script value is a
994   QVariant using QScriptValue::isVariant(), and then check if the
995   QVariant can be converted to your type using QVariant::canConvert().
996
997   \section3 Functions with Variable Numbers of Arguments
998
999   Because of the presence of the built-in \c arguments object,
1000   implementing functions that take a variable number of arguments
1001   is simple. In fact, as we have seen, in the technical sense \e{all}
1002   Qt Script functions can be seen as variable-argument functions.
1003   As an example, consider a concat() function that takes an arbitrary
1004   number of arguments, converts the arguments to their string
1005   representation and concatenates the results; for example,
1006   \c{concat("Qt", " ", "Script ", 101)} would return "Qt Script 101".
1007   A script definition of \c{concat()} might look like this:
1008
1009     \snippet doc/src/snippets/code/doc_src_qtscript.js 64
1010
1011   Here is an equivalent native implementation:
1012
1013     \snippet doc/src/snippets/code/doc_src_qtscript.cpp 65
1014
1015   A second use case for a variable number of arguments is to implement
1016   optional arguments. Here's how a script definition typically does
1017   it:
1018
1019     \snippet doc/src/snippets/code/doc_src_qtscript.js 66
1020
1021   And here's the native equivalent:
1022
1023     \snippet doc/src/snippets/code/doc_src_qtscript.cpp 67
1024
1025   A third use case for a variable number of arguments is to simulate
1026   C++ overloads. This involves checking the number of arguments and/or
1027   their type at the beginning of the function body (as already shown),
1028   and acting accordingly. It might be worth thinking twice before
1029   doing this, and instead favor unique function names; e.g., having
1030   separate \c{processNumber(number)} and \c{processString(string)}
1031   functions rather than a generic \c{process(anything)} function.
1032   On the caller side, this makes it harder for scripts to accidentally
1033   call the wrong overload (since they don't know or don't comprehend
1034   your custom sophisticated overloading resolution rules), and on the
1035   callee side, you avoid the need for potentially complex (read:
1036   error-prone) checks to resolve ambiguity.
1037
1038   \section3 Accessing the Arguments Object
1039
1040   Most native functions use the QScriptContext::argument() function to
1041   access function arguments. However, it is also possible to access
1042   the built-in \c arguments object itself (the one referred to by the
1043   \c arguments variable in script code), by calling the
1044   QScriptContext::argumentsObject() function. This has three principal
1045   applications:
1046
1047   \list
1048   \o The \c arguments object can be used to easily forward a function
1049      call to another function. In script code, this is what it
1050      typically looks like:
1051
1052     \snippet doc/src/snippets/code/doc_src_qtscript.js 68
1053
1054      For example, \c{foo(10, 20, 30)} would result in the \c{foo()} function
1055      executing the equivalent of \c{bar(10, 20, 30)}. This is useful if
1056      you want to perform some special pre- or post-processing when
1057      calling a function (e.g., to log the call to \c{bar()} without having
1058      to modify the \c{bar()} function itself, like the above example), or if
1059      you want to call a "base implementation" from a prototype
1060      function that has the exact same "signature". In C++, the forwarding
1061      function might look like this:
1062
1063      \snippet doc/src/snippets/code/doc_src_qtscript.cpp 69
1064
1065   \o The arguments object can serve as input to a QScriptValueIterator,
1066      providing a generic way to iterate over the arguments. A debugger
1067      might use this to display the arguments object in a general purpose
1068      "Qt Script Object Explorer", for example.
1069
1070   \o The arguments object can be serialized (e.g., with JSON) and transferred
1071      to another entity (e.g., a script engine running in another thread),
1072      where the object can be deserialized and passed as argument to
1073      another script function.
1074   \endlist
1075
1076   \section2 Constructor Functions
1077
1078   Some script functions are constructors; they are expected to initialize
1079   new objects. The following snippet is a small example:
1080
1081     \snippet doc/src/snippets/code/doc_src_qtscript.js 75
1082
1083   There is nothing special about constructor functions. In fact, any
1084   script function can act as a constructor function (i.e., any function
1085   can serve as the operand to \c{new}). Some functions behave differently
1086   depending on whether they are called as part of a \c{new} expression
1087   or not; for example, the expression \c{new Number(1)} will create a
1088   Number object, whereas \c{Number("123")} will perform a type
1089   conversion. Other functions, like \c{Array()}, will always create
1090   and initialize a new object (e.g., \c{new Array()} and \c{Array()} have
1091   the same effect).
1092
1093   A native Qt Script function can call the
1094   QScriptContext::isCalledAsConstructor() function to determine if it
1095   is being called as a constructor or as a regular function. When a
1096   function is called as a constructor (i.e., it is the operand in a
1097   \c{new} expression), this has two important implications:
1098
1099   \list
1100   \i The \c this object, QScriptContext::thisObject(), contains
1101      the new object to be initialized; the engine creates this
1102      new object automatically before invoking your function. This means
1103      that your native constructor function normally doesn't have to (and
1104      shouldn't) create a new object when it is called as a
1105      constructor, since the engine has already prepared a new
1106      object. Instead your function should operate on the supplied
1107      \c this object.
1108   \i The constructor function should return an undefined value,
1109      QScriptEngine::undefinedValue(), to tell the engine that the
1110      \c this object should be the final result of the \c new
1111      operator. Alternatively, the function can return the \c this
1112      object itself.
1113   \endlist
1114
1115   When QScriptContext::isCalledAsConstructor() returns false, how your
1116   constructor handles this case depends on what behavior you desire.
1117   If, like the built-in \c{Number()} function, a plain function call should
1118   perform a type conversion of its argument, then you perform the conversion
1119   and return the result. If, on the other hand, you want your constructor
1120   to behave \e{as if it was called as a constructor} (with
1121   \c{new}), you have to explicitly create a new object (that is,
1122   ignore the \c this object), initialize that object, and return it.
1123
1124   The following example implements a constructor function that always
1125   creates and initializes a new object:
1126
1127     \snippet doc/src/snippets/code/doc_src_qtscript.cpp 76
1128
1129   Given this constructor, scripts would be able to use either the
1130   expression \c{new Person("Bob")} or \c{Person("Bob")} to create a
1131   new \c{Person} object; both behave in the same way.
1132
1133   There is no equivalent way for a function defined in script
1134   code to determine whether or not it was invoked as a constructor.
1135
1136   Note that, even though it is not considered good practice, there is
1137   nothing that stops you from choosing to ignore the default
1138   constructed (\c this) object when your function is called as a
1139   constructor and creating your own object anyway; simply have the
1140   constructor return that object. The object will "override" the
1141   default object that the engine constructed (i.e., the default
1142   object will simply be discarded internally).
1143
1144   \section2 Associating Data with a Function
1145
1146   Even if a function is global \mdash i.e., not associated with any particular
1147   (type of) object \mdash you might still want to associate some data with it,
1148   so that it becomes self-contained; for example, the function could have
1149   a pointer to some C++ resource that it needs to access. If your application
1150   only uses a single script engine, or the same C++ resource can/should be
1151   shared among all script engines, you can simply use a static C++ variable
1152   and access it from within the native Qt Script function.
1153
1154   In the case where a static C++ variable or singleton class is
1155   not appropriate, you can call QScriptValue::setProperty() on the
1156   function object, but be aware that those properties will also be
1157   accessible to script code. The alternative is to use QScriptValue::setData();
1158   this data is not script-accessible. The implementation can access this
1159   internal data through the QScriptContext::callee() function, which
1160   returns the function object being invoked. The following example
1161   shows how this might be used:
1162
1163     \snippet doc/src/snippets/code/doc_src_qtscript.cpp 55
1164
1165   \section2 Native Functions as Arguments to Functions
1166
1167   As previously mentioned, a function object can be passed as argument
1168   to another function; this is also true for native functions,
1169   naturally. As an example, here's a native comparison function
1170   that compares its two arguments numerically:
1171
1172     \snippet doc/src/snippets/code/doc_src_qtscript.cpp 53
1173
1174   The above function can be passed as argument to the standard
1175   \c{Array.prototype.sort} function to sort an array numerically,
1176   as the following C++ code illustrates:
1177
1178     \snippet doc/src/snippets/code/doc_src_qtscript.cpp 54
1179
1180   Note that, in this case, we are truly treating the native function
1181   object as a value \mdash i.e., we don't store it as a property of the
1182   scripting environment \mdash we simply pass it on as an "anonymous"
1183   argument to another script function and then forget about it.
1184
1185   \section2 The Activation Object
1186
1187   Every Qt Script function invocation has an \e{activation object}
1188   associated with it; this object is accessible through the
1189   QScriptContext::activationObject() function. The activation object
1190   is a script object whose properties are the local variables
1191   associated with the invocation (including the arguments for which
1192   the script function has a corresponding formal parameter name).
1193   Thus, getting, modifying, creating and deleting local variables
1194   from C++ is done using the regular QScriptValue::property() and
1195   QScriptValue::setProperty() functions. The activation object itself
1196   is not directly accessible from script code (but it is implicitly
1197   accessed whenever a local variable is read from or written to).
1198
1199   For C++ code, there are two principal applications of the
1200   activation object:
1201
1202   \list
1203   \i The activation object provides a standard way to traverse the
1204   variables associated with a function call, by using it as the input
1205   to QScriptValueIterator. This is useful for debugging purposes.
1206
1207   \i The activation object can be used to prepare local variables
1208   that should be available when a script is evaluated inline; this
1209   can be viewed as a way of passing arguments to the script
1210   itself. This technique is typically used in conjunction with
1211   QScriptEngine::pushContext(), as in the following example:
1212
1213     \snippet doc/src/snippets/code/doc_src_qtscript.cpp 77
1214
1215   We create a temporary execution context, create a local variable
1216   for it, evaluate the script, and finally restore the old context.
1217   \endlist
1218
1219   \section2 Property Getters and Setters
1220
1221   A script object property can be defined in terms of a getter/setter
1222   function, similar to how a Qt C++ property has read and write
1223   functions associated with it. This makes it possible for a script to
1224   use expressions like \c{object.x} instead of \c{object.getX()}; the
1225   getter/setter function for \c{x} will implicitly be invoked
1226   whenever the property is accessed. To scripts, the property looks
1227   and behaves just like a regular object property.
1228
1229   A single Qt Script function can act as both getter and setter for
1230   a property. When it is called as a getter, the argument count is 0.
1231   When it is called as a setter, the argument count is 1; the argument
1232   is the new value of the property. In the following example, we
1233   define a native combined getter/setter that transforms the value
1234   slightly:
1235
1236     \snippet doc/src/snippets/code/doc_src_qtscript.cpp 78
1237
1238   The example uses the internal data of the object to store and
1239   retrieve the transformed value. Alternatively, the property
1240   could be stored in another, "hidden" property of the object itself
1241   (e.g., \c{__x__}). A native function is free to implement whatever
1242   storage scheme it wants, as long as the external behavior of the
1243   property itself is consistent (e.g., that scripts should not be able
1244   to distinguish it from a regular property).
1245
1246   The following C++ code shows how an object property can be defined
1247   in terms of the native getter/setter:
1248
1249     \snippet doc/src/snippets/code/doc_src_qtscript.cpp 79
1250
1251   When the property is accessed, like in the following script, the
1252   getter/setter does its job behind the scenes:
1253
1254     \snippet doc/src/snippets/code/doc_src_qtscript.js 80
1255
1256   \note It is important that the setter function, not just the getter,
1257   returns the value of the property; i.e., the setter should \e{not}
1258   return QScriptValue::UndefinedValue. This is because the result of
1259   the property assignment is the value returned by the setter, and
1260   not the right-hand side expression. Also note that you normally
1261   should not attempt to read the same property that the getter modifies
1262   within the getter itself, since this will cause the getter to be
1263   called recursively.
1264
1265   You can remove a property getter/setter by calling
1266   QScriptValue::setProperty(), passing an invalid QScriptValue
1267   as the getter/setter. Remember to specify the
1268   QScriptValue::PropertyGetter/QScriptValue::PropertySetter flag(s),
1269   otherwise the only thing that will happen is that the setter will be
1270   invoked with an invalid QScriptValue as its argument!
1271
1272   Property getters and setters can be defined and installed by script
1273   code as well, as in the following example:
1274
1275     \snippet doc/src/snippets/code/doc_src_qtscript.js 81
1276
1277   Getters and setters can only be used to implement "a priori
1278   properties"; i.e., the technique can't be used to react to an access
1279   to a property that the object doesn't already have. To gain total
1280   control of property access in this way, you need to subclass
1281   QScriptClass.
1282
1283   \section1 Making Use of Prototype-Based Inheritance
1284
1285   In ECMAScript, inheritance is based on the concept of \e{shared
1286   prototype objects}; this is quite different from the class-based
1287   inheritance familiar to C++ programmers. With QtScript, you can
1288   associate a custom prototype object with a C++ type using
1289   QScriptEngine::setDefaultPrototype(); this is the key to providing
1290   a script interface to that type. Since the QtScript module is built
1291   on top of Qt's meta-type system, this can be done for any C++ type.
1292
1293   You might be wondering when exactly you would need to use this
1294   functionality in your application; isn't the automatic binding
1295   provided by QScriptEngine::newQObject() enough? No, not under all
1296   circumstances.
1297   Firstly, not every C++ type is derived from QObject; types that
1298   are not QObjects cannot be introspected through Qt's meta-object
1299   system (they do not have properties, signals and slots). Secondly,
1300   even if a type is QObject-derived, the functionality you want to
1301   expose to scripts might not all be available, since it is unusual to
1302   define every function to be a slot (and it's not always
1303   possible/desirable to change the C++ API to make it so).
1304
1305   It is perfectly possible to solve this problem by using "conventional"
1306   C++ techniques. For instance, the QRect class could effectively be
1307   made scriptable by creating a QObject-based C++ wrapper class with
1308   \c{x}, \c{y}, \c{width} properties and so on, which forwarded property
1309   access and function calls to the wrapped value. However, as we shall
1310   see, by taking advantage of the ECMAScript object model and combining
1311   it with Qt's meta-object system, we can arrive at a solution that is
1312   more elegant, consistent and lightweight, supported by a small API.
1313
1314   This section explains the underlying concepts of prototype-based
1315   inheritance. Once these concepts are understood, the associated
1316   practices can be applied throughout the QtScript API in order to
1317   create well-behaved, consistent bindings to C++ that will fit nicely
1318   into the ECMAScript universe.
1319
1320   When experimenting with QtScript objects and inheritance, it can be
1321   helpful to use the interactive interpreter included with the
1322   \l{Qt Script Examples}, located in \c{examples/script/qscript}.
1323
1324   \section2 Prototype Objects and Shared Properties
1325
1326   The purpose of a QtScript \e{prototype object} is to define
1327   behavior that should be shared by a set of other QtScript
1328   objects. We say that objects which share the same prototype object
1329   belong to the same \e{class} (again, on the technical side this
1330   should not to be confused with the class constructs of languages
1331   like C++ and Java; ECMAScript has no such construct).
1332
1333   The basic prototype-based inheritance mechanism works as follows: Each
1334   QtScript object has an internal link to another object, its
1335   \e{prototype}. When a property is looked up in an object, and the
1336   object itself does not have the property, the property is looked up
1337   in the prototype object instead; if the prototype has the property,
1338   then that property is returned. Otherwise, the property is looked up
1339   in the prototype of the prototype object, and so on; this chain of
1340   objects constitutes a \e{prototype chain}. The chain of prototype
1341   objects is followed until the property is found or the end of the
1342   chain is reached.
1343
1344   For example, when you create a new object by the expression \c{new
1345   Object()}, the resulting object will have as its prototype the
1346   standard \c{Object} prototype, \c{Object.prototype}; through this
1347   prototype relation, the new object inherits a set of properties,
1348   including the \c{hasOwnProperty()} function and \c{toString()}
1349   function:
1350
1351   \snippet doc/src/snippets/code/doc_src_qtscript.js 27
1352
1353   The \c{toString()} function itself is not defined in \c{o} (since we
1354   did not assign anything to \c{o.toString}), so instead the
1355   \c{toString()} function in the standard \c{Object} prototype is
1356   called, which returns a highly generic string representation of
1357   \c{o} ("[object Object]").
1358
1359   Note that the properties of the prototype object are not \e{copied} to
1360   the new object; only a \e{link} from the new object to the prototype
1361   object is maintained. This means that changes done to the prototype
1362   object will immediately be reflected in the behavior of all objects
1363   that have the modified object as their prototype.
1364
1365   \section2 Defining Classes in a Prototype-Based Universe
1366
1367   In QtScript, a class is not defined explicitly; there is no
1368   \c{class} keyword. Instead, you define a new class in two steps:
1369
1370   \list 1
1371   \i Define a \e{constructor function} that will initialize new objects.
1372   \i Set up a \e{prototype object} that defines the class interface, and
1373      assign this object to the public \c{prototype} property of the
1374      constructor function.
1375   \endlist
1376
1377   With this arrangement, the constructor's public \c{prototype}
1378   property will automatically be set as the prototype of objects created
1379   by applying the \c{new} operator to your constructor function;
1380   e.g., the prototype of an object created by \c{new Foo()} will be the
1381   value of \c{Foo.prototype}.
1382
1383   Functions that don't operate on the \c this object ("static" methods)
1384   are typically stored as properties of the constructor function, not
1385   as properties of the prototype object. The same is true for
1386   constants, such as enum values.
1387
1388   The following code defines a simple constructor function for a class
1389   called \c{Person}:
1390
1391   \snippet doc/src/snippets/code/doc_src_qtscript.js 28
1392
1393   Next, you want to set up \c{Person.prototype} as your prototype
1394   object; i.e., define the interface that should be common to all
1395   \c{Person} objects. QtScript automatically creates a default
1396   prototype object (by the expression \c{new Object()}) for every
1397   script function; you can add properties to this object, or you can
1398   assign your own custom object. (Generally speaking, any QtScript
1399   object can act as prototype for any other object.)
1400
1401   Here's an example of how you might want to override the
1402   \c{toString()} function that \c{Person.prototype} inherits from
1403   \c{Object.prototype}, to give your \c{Person} objects a more
1404   appropriate string representation:
1405
1406   \snippet doc/src/snippets/code/doc_src_qtscript.js 29
1407
1408   This resembles the process of reimplementing a virtual function
1409   in C++. Henceforth, when the property named \c{toString} is
1410   looked up in a \c{Person} object, it will be resolved in
1411   \c{Person.prototype}, not in \c{Object.prototype} as before:
1412
1413   \snippet doc/src/snippets/code/doc_src_qtscript.js 30
1414
1415   There are also some other interesting things we can learn about a
1416   \c{Person} object:
1417
1418   \snippet doc/src/snippets/code/doc_src_qtscript.js 31
1419
1420   The \c{hasOwnProperty()} function is not inherited from
1421   \c{Person.prototype}, but rather from \c{Object.prototype}, which is
1422   the prototype of \c{Person.prototype} itself; i.e., the prototype
1423   chain of \c{Person} objects is \c{Person.prototype} followed by
1424   \c{Object.prototype}. This prototype chain establishes a \e{class
1425   hierarchy}, as demonstrated by applying the \c{instanceof} operator;
1426   \c{instanceof} checks if the value of the public \c{prototype}
1427   property of the constructor function on the right-hand side is
1428   reached by following the prototype chain of the object on the
1429   left-hand side.
1430
1431   When defining subclasses, there's a general pattern you can use. The
1432   following example shows how one can create a subclass of \c{Person}
1433   called \c{Employee}:
1434
1435   \snippet doc/src/snippets/code/doc_src_qtscript.js 32
1436
1437   Again, you can use the \c{instanceof} to verify that the
1438   class relationship between \c{Employee} and \c{Person} has been
1439   correctly established:
1440
1441   \snippet doc/src/snippets/code/doc_src_qtscript.js 33
1442
1443   This shows that the prototype chain of \c{Employee} objects is the
1444   same as that of \c{Person} objects, but with \c{Employee.prototype}
1445   added to the front of the chain.
1446
1447   \section2 Prototype-Based Programming with the QtScript C++ API
1448
1449   You can use QScriptEngine::newFunction() to wrap
1450   native functions. When implementing a constructor function,
1451   you also pass the prototype object as an argument to
1452   QScriptEngine::newFunction().
1453   You can call QScriptValue::construct() to call a constructor
1454   function, and you can use QScriptValue::call() from within a
1455   native constructor function if you need to call a base class
1456   constructor.
1457
1458   The QScriptable class provides a convenient way to implement a
1459   prototype object in terms of C++ slots and properties. Take a look
1460   at the \l{Default Prototypes Example} to see how this is done.
1461   Alternatively, the prototype functionality can be implemented in
1462   terms of standalone native functions that you wrap with
1463   QScriptEngine::newFunction() and set as properties of your prototype
1464   object by calling QScriptValue::setProperty().
1465
1466   In the implementation of your prototype functions, you use
1467   QScriptable::thisObject() (or QScriptContext::thisObject()) to
1468   obtain a reference to the QScriptValue being operated upon; then you
1469   call qscriptvalue_cast() to cast it to your C++ type, and perform
1470   the relevant operations using the usual C++ API for the type.
1471
1472   You associate a prototype object with a C++ type by calling
1473   QScriptEngine::setDefaultPrototype(). Once this mapping is
1474   established, QtScript will automatically assign the correct
1475   prototype when a value of such a type is wrapped in a QScriptValue;
1476   either when you explicitly call QScriptEngine::toScriptValue(), or
1477   when a value of such a type is returned from a C++ slot and
1478   internally passed back to script code by the engine. This means you
1479   \e{don't} have to implement wrapper classes if you use this
1480   approach.
1481
1482   As an example, let's consider how the \c{Person} class from the
1483   preceding section can be implemented in terms of the Qt Script API.
1484   We begin with the native constructor function:
1485
1486   \snippet doc/src/snippets/code/doc_src_qtscript.cpp 34
1487
1488   Here's the native equivalent of the \c{Person.prototype.toString}
1489   function we saw before:
1490
1491   \snippet doc/src/snippets/code/doc_src_qtscript.cpp 35
1492
1493   The \c{Person} class can then be initialized as follows:
1494
1495   \snippet doc/src/snippets/code/doc_src_qtscript.cpp 36
1496
1497   The implementation of the \c{Employee} subclass is similar. We
1498   use QScriptValue::call() to call the super-class (Person) constructor:
1499
1500   \snippet doc/src/snippets/code/doc_src_qtscript.cpp 37
1501
1502   The \c{Employee} class can then be initialized as follows:
1503
1504   \snippet doc/src/snippets/code/doc_src_qtscript.cpp 38
1505
1506   When implementing the prototype object of a class, you may want to use
1507   the QScriptable class, as it enables you to define the API of your
1508   script class in terms of Qt properties, signals and slots, and
1509   automatically handles value conversion between the Qt Script and C++
1510   side.
1511
1512   \section2 Implementing Prototype Objects for Value-based Types
1513
1514   When implementing a prototype object for a value-based type --
1515   e.g. QPointF -- the same general technique applies; you populate
1516   a prototype object with functionality that should be shared
1517   among instances. You then associate the prototype object with
1518   the type by calling QScriptEngine::setDefaultPrototype(). This
1519   ensures that when e.g. a value of the relevant type is returned
1520   from a slot back to the script, the prototype link of the script
1521   value will be initialized correctly.
1522
1523   When values of the custom type are stored in QVariants -- which Qt
1524   Script does by default --, qscriptvalue_cast() enables you to safely
1525   cast the script value to a pointer to the C++ type. This makes it
1526   easy to do type-checking, and, for prototype functions that should
1527   modify the underlying C++ value, lets you modify the actual value
1528   contained in the script value (and not a copy of it).
1529
1530   \snippet doc/src/snippets/code/doc_src_qtscript.cpp 39
1531
1532   \section2 Implementing Constructors for Value-based Types
1533
1534   You can implement a constructor function for a value-based type
1535   by wrapping a native factory function. For example, the following
1536   function implements a simple constructor for QPoint:
1537
1538   \snippet doc/src/snippets/code/doc_src_qtscript.cpp 44
1539
1540   In the above code we simplified things a bit, e.g. we didn't check
1541   the argument count to decide which QPoint C++ constructor to use.
1542   In your own constructors you have to do this type of resolution
1543   yourself, i.e. by checking the number of arguments passed to the
1544   native function, and/or by checking the type of the arguments and
1545   converting the arguments to the desired type. If you detect a problem
1546   with the arguments you may want to signal this by throwing a script
1547   exception; see QScriptContext::throwError().
1548
1549   \section2 Managing Non-QObject-based Objects
1550
1551   For value-based types (e.g. QPoint), the C++ object will be destroyed when
1552   the Qt Script object is garbage-collected, so managing the memory of the C++
1553   object is not an issue. For QObjects, Qt Script provides several
1554   alternatives for managing the underlying C++ object's lifetime; see the
1555   \l{Controlling QObject Ownership} section. However, for polymorphic types
1556   that don't inherit from QObject, and when you can't (or won't) wrap the type
1557   in a QObject, you have to manage the lifetime of the C++ object yourself.
1558
1559   A behavior that's often reasonable when a Qt Script object wraps a C++
1560   object, is that the C++ object is deleted when the Qt Script object is
1561   garbage-collected; this is typically the case when the objects can be
1562   constructed by scripts, as opposed to the application providing the scripts
1563   with pre-made "environment" objects. A way of making the lifetime of the C++
1564   object follow the lifetime of the Qt Script object is by using a shared
1565   pointer class, such as QSharedPointer, to hold a pointer to your object;
1566   when the Qt Script object containing the QSharedPointer is
1567   garbage-collected, the underlying C++ object will be deleted if there are no
1568   other references to the object.
1569
1570   The following snippet shows a constructor function that constructs
1571   QXmlStreamReader objects that are stored using QSharedPointer:
1572
1573     \snippet doc/src/snippets/code/doc_src_qtscript.cpp 93
1574
1575   Prototype functions can use qscriptvalue_cast() to cast the \c this object
1576   to the proper type:
1577
1578     \snippet doc/src/snippets/code/doc_src_qtscript.cpp 94
1579
1580   The prototype and constructor objects are set up in the usual way:
1581
1582     \snippet doc/src/snippets/code/doc_src_qtscript.cpp 95
1583
1584   Scripts can now construct QXmlStreamReader objects by calling the \c
1585   XmlStreamReader constructor, and when the Qt Script object is
1586   garbage-collected (or the script engine is destroyed), the QXmlStreamReader
1587   object is destroyed as well.
1588
1589   \section1 Defining Custom Script Classes with QScriptClass
1590
1591   There are cases where neither the dynamic QObject binding provided
1592   by QScriptEngine::newQObject() or the manual binding provided by
1593   QScriptEngine::newFunction() is sufficient. For example, you might
1594   want to implement a dynamic script proxy to an underlying object;
1595   or you might want to implement an array-like class (i.e. that gives
1596   special treatment to properties that are valid array indexes, and
1597   to the property "length"). In such cases, you can subclass
1598   QScriptClass to achieve the desired behavior.
1599
1600   QScriptClass allows you to handle all property access for a
1601   (class of) script object through virtual get/set property functions.
1602   Iteration of custom properties is also supported through the
1603   QScriptClassPropertyIterator class; this means you can advertise
1604   properties to be reported by for-in script statements and
1605   QScriptValueIterator.
1606
1607   \section1 Error Handling and Debugging Facilities
1608
1609   Syntax errors in scripts will be reported as soon as a script is
1610   evaluated; QScriptEngine::evaluate() will return a SyntaxError object
1611   that you can convert to a string to get a description of the error.
1612
1613   The QScriptEngine::uncaughtExceptionBacktrace() function gives you
1614   a human-readable backtrace of the last uncaught exception. In order
1615   to get useful filename information in backtraces, you should pass
1616   proper filenames to QScriptEngine::evaluate() when evaluating your
1617   scripts.
1618
1619   Often an exception doesn't happen at the time the script is evaluated,
1620   but at a later time when a function defined by the script is actually
1621   executed. For C++ signal handlers, this is tricky; consider the case
1622   where the clicked() signal of a button is connected to a script function,
1623   and that script function causes a script exception when it is handling
1624   the signal. Where is that script exception propagated to?
1625
1626   The solution is to connect to the QScriptEngine::signalHandlerException()
1627   signal; this will give you notification when a signal handler causes
1628   an exception, so that you can find out what happened and/or recover
1629   from it.
1630
1631   In Qt 4.4 the QScriptEngineAgent class was introduced. QScriptEngineAgent
1632   provides an interface for reporting low-level "events" in a script engine,
1633   such as when a function is entered or when a new script statement is
1634   reached. By subclassing QScriptEngineAgent you can be notified of these
1635   events and perform some action, if you want. QScriptEngineAgent itself
1636   doesn't provide any debugging-specific functionality (e.g. setting
1637   breakpoints), but it is the basis of tools that do.
1638
1639   The QScriptEngineDebugger class introduced in Qt 4.5 provides a 
1640   \l{Qt Script Debugger Manual}{Qt Script debugger} that can be embedded
1641   into your application.
1642
1643   \section2 Redefining print()
1644
1645   Qt Script provides a built-in print() function that can be useful for
1646   simple debugging purposes. The built-in print() function writes to
1647   standard output. You can redefine the print() function (or add your
1648   own function, e.g. debug() or log()) that redirects the text to
1649   somewhere else. The following code shows a custom print() that adds
1650   text to a QPlainTextEdit.
1651
1652   \snippet doc/src/snippets/code/doc_src_qtscript.cpp 45
1653
1654   The following code shows how the custom print() function may be
1655   initialized and used.
1656
1657   \snippet doc/src/snippets/code/doc_src_qtscript.cpp 46
1658
1659   A pointer to the QPlainTextEdit is stored as an internal property
1660   of the script function itself, so that it can be retrieved when
1661   the function is called.
1662
1663   \section1 Using QtScript Extensions
1664
1665   The QScriptEngine::importExtension() function can be used to load plugins
1666   into a script engine. Plugins typically add some extra functionality to
1667   the engine; for example, a plugin might add full bindings for the Qt
1668   Arthur painting API, so that those classes may be used from Qt Script
1669   scripts. There are currently no script plugins shipped with Qt.
1670
1671   If you are implementing some Qt Script functionality that you want other
1672   Qt application developers to be able to use, \l{Creating QtScript Extensions}
1673   {developing an extension} (e.g. by subclassing QScriptExtensionPlugin) is
1674   worth looking into.
1675
1676   \section1 Internationalization
1677
1678   Since Qt 4.5, Qt Script supports internationalization of scripts by building
1679   on the C++ internationalization functionality (see \l{Internationalization
1680   with Qt}).
1681
1682   \section2 Use qsTr() for All Literal Text
1683
1684   Wherever your script uses "quoted text" for text that will be presented to
1685   the user, ensure that it is processed by the QCoreApplication::translate()
1686   function. Essentially all that is necessary to achieve this is to use
1687   the qsTr() script function. Example:
1688
1689   \snippet doc/src/snippets/code/doc_src_qtscript.js 82
1690
1691   This accounts for 99% of the user-visible strings you're likely to write.
1692
1693   The qsTr() function uses the basename of the script's filename (see
1694   QFileInfo::baseName()) as the translation context; if the filename is not
1695   unique in your project, you should use the qsTranslate() function and pass a
1696   suitable context as the first argument. Example:
1697
1698   \snippet doc/src/snippets/code/doc_src_qtscript.js 83
1699
1700   If you need to have translatable text completely outside a function, there
1701   are two functions to help: QT_TR_NOOP() and QT_TRANSLATE_NOOP(). They merely
1702   mark the text for extraction by the \c lupdate utility described below.  At
1703   runtime, these functions simply return the text to translate unmodified.
1704
1705   Example of QT_TR_NOOP():
1706
1707   \snippet doc/src/snippets/code/doc_src_qtscript.js 84
1708
1709   Example of QT_TRANSLATE_NOOP():
1710
1711   \snippet doc/src/snippets/code/doc_src_qtscript.js 85
1712
1713   \section2 Use String.prototype.arg() for Dynamic Text
1714
1715   The String.prototype.arg() function (which is modeled after QString::arg())
1716   offers a simple means for substituting arguments:
1717
1718   \snippet doc/src/snippets/code/doc_src_qtscript.js 86
1719
1720     \section2 Produce Translations
1721
1722     Once you are using qsTr() and/or qsTranslate() throughout your scripts, you
1723     can start producing translations of the user-visible text in your program.
1724
1725     The \l{Qt Linguist manual} provides further information about
1726     Qt's translation tools, \e{Qt Linguist}, \c lupdate and \c
1727     lrelease.
1728
1729     Translation of Qt Script scripts is a three-step process:
1730
1731     \list 1
1732
1733     \o Run \c lupdate to extract translatable text from the script source code
1734     of the Qt application, resulting in a message file for translators (a TS
1735     file). The utility recognizes qsTr(), qsTranslate() and the
1736     \c{QT_TR*_NOOP()} functions described above and produces TS files
1737     (usually one per language).
1738
1739     \o Provide translations for the source texts in the TS file, using
1740     \e{Qt Linguist}. Since TS files are in XML format, you can also
1741     edit them by hand.
1742
1743     \o Run \c lrelease to obtain a light-weight message file (a QM
1744     file) from the TS file, suitable only for end use. Think of the TS
1745      files as "source files", and QM files as "object files". The
1746     translator edits the TS files, but the users of your application
1747     only need the QM files. Both kinds of files are platform and
1748     locale independent.
1749
1750     \endlist
1751
1752     Typically, you will repeat these steps for every release of your
1753     application. The \c lupdate utility does its best to reuse the
1754     translations from previous releases.
1755
1756     When running \c lupdate, you must specify the location of the script(s),
1757     and the name of the TS file to produce. Examples:
1758
1759     \snippet doc/src/snippets/code/doc_src_qtscript.qdoc 87
1760
1761     will extract translatable text from \c myscript.qs and create the
1762     translation file \c myscript_la.qs.
1763
1764     \snippet doc/src/snippets/code/doc_src_qtscript.qdoc 88
1765
1766     will extract translatable text from all files ending with \c{.qs} in the
1767     \c scripts folder and create the translation file \c scripts_la.qs.
1768
1769     Alternatively, you can create a separate qmake project file that sets up
1770     the \c SOURCES and \c TRANSLATIONS variables appropriately; then run
1771     \c lupdate with the project file as input.
1772
1773     \snippet doc/src/snippets/code/doc_src_qtscript.qdoc 89
1774
1775     When running \c lrelease, you must specify the name of the TS input
1776     file; or, if you are using a qmake project file to manage script
1777     translations, you specify the name of that file. \c lrelease will create
1778     \c myscript_la.qm, the binary representation of the translation.
1779
1780     \section2 Apply Translations
1781
1782     In your application, you must use QTranslator::load() to load the
1783     translation files appropriate for the user's language, and install them
1784     using QCoreApplication::installTranslator(). Finally, you must call
1785     QScriptEngine::installTranslatorFunctions() to make the script translation
1786     functions (qsTr(), qsTranslate() and \c{QT_TR*_NOOP()}) available to scripts
1787     that are subsequently evaluated by QScriptEngine::evaluate(). For scripts
1788     that are using the qsTr() function, the proper filename must be passed as
1789     second argument to QScriptEngine::evaluate().
1790
1791     \c linguist, \c lupdate and \c lrelease are installed in the \c bin
1792     subdirectory of the base directory Qt is installed into. Click Help|Manual
1793     in \e{Qt Linguist} to access the user's manual; it contains a tutorial
1794     to get you started.
1795
1796     See also the \l{Hello Script Example}.
1797
1798   \section1 ECMAScript Compatibility
1799
1800   QtScript implements all the built-in objects and properties defined
1801   in the \l{ECMA-262} standard; see the
1802   \l{ECMAScript Reference}{ECMAScript reference} for an overview.
1803
1804   \section1 QtScript Extensions to ECMAScript
1805
1806   \list
1807   \i \c{__proto__} \br
1808     The prototype of an object (QScriptValue::prototype())
1809     can be accessed through its \c{__proto__} property in script code.
1810     This property has the QScriptValue::Undeletable flag set.
1811     For example:
1812
1813   \snippet doc/src/snippets/code/doc_src_qtscript.js 40
1814
1815   \i \c{Object.prototype.__defineGetter__} \br
1816     This function installs a
1817     getter function for a property of an object. The first argument is
1818     the property name, and the second is the function to call to get
1819     the value of that property. When the function is invoked, the
1820     \c this object will be the object whose property is accessed.
1821     For example:
1822
1823   \snippet doc/src/snippets/code/doc_src_qtscript.js 41
1824
1825   \i \c{Object.prototype.__defineSetter__} \br
1826     This function installs a
1827     setter function for a property of an object. The first argument is
1828     the property name, and the second is the function to call to set
1829     the value of that property.  When the function is invoked, the
1830     \c this object will be the object whose property is accessed.
1831     For example:
1832
1833   \snippet doc/src/snippets/code/doc_src_qtscript.js 42
1834
1835   \i \c{Function.prototype.connect} \br
1836     This function connects
1837     a signal to a slot. Usage of this function is described in
1838     the section \l{Using Signals and Slots}.
1839
1840   \i \c{Function.prototype.disconnect} \br
1841     This function disconnects
1842     a signal from a slot. Usage of this function is described in
1843     the section \l{Using Signals and Slots}.
1844
1845   \i \c{QObject.prototype.findChild} \br
1846     This function is semantically equivalent to QObject::findChild().
1847
1848   \i \c{QObject.prototype.findChildren} \br
1849     This function is semantically equivalent to QObject::findChildren().
1850
1851   \i \c{QObject.prototype.toString} \br
1852     This function returns a default string representation of a QObject.
1853
1854   \i \c{gc} \br
1855     This function invokes the garbage collector.
1856
1857   \i \c{Error.prototype.backtrace} \br
1858     This function returns a human-readable backtrace, in the form of
1859     an array of strings.
1860
1861   \i Error objects have the following additional properties:
1862     \list
1863     \i \c{lineNumber}: The line number where the error occurred.
1864     \i \c{fileName}: The file name where the error occurred (if a file name
1865     was passed to QScriptEngine::evaluate()).
1866     \i \c{stack}: An array of objects describing the stack. Each object has
1867       the following properties:
1868       \list
1869       \i \c{functionName}: The function name, if available.
1870       \i \c{fileName}: The file name, if available.
1871       \i \c{lineNumber}: The line number, if available.
1872       \endlist
1873     \endlist
1874
1875   \endlist
1876
1877  */