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 */
1878