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