Scripting Your Qt Application

1. Scripting Your Qt Application 09/25/09

2. About Me (Kent Hansen) • Working on Qt since 2005 • QtScript • Qt State Machine framework • Plays harmonica and Irish whistle 2

3. Goals For This Talk • Give overview of QtScript and things related to it • Show how to embed QtScript into your application 3

4. Agenda • What is application scripting? • QtScript tour (the essentials) • Debugger • Misc. 4

5. “Scripting Your Application”: What? • Premise: Core functionality implemented in C++ • Interface(s) exported to scripting environment • Plugin-based, interactive (console), ... 5

6. Golden Example: The Web Browser • Script loaded as part of web page • Browser exports tree-based API to page (DOM) • Script manipulates the page 6

7. What is QtScript? • A Qt module • A scripting language • An “engine” for evaluating scripts • An API for embedding into your application 7

8. The QtScript Language • Based on ECMA-262 standard –“JavaScript minus DOM” • Object-oriented, dynamically typed • Java-like syntax 8

9. Disclaimer This is not a JavaScript tutorial! 9

10. The QtScript Engine • Executes scripts • Performs C++ <--> script bridging • It's re-entrant 10

11. The QtScript API • Embed QtScript engine in your application • Expose C++ objects to script environment • Work with script values from C++ 11

12. Why should you use QtScript? • Easy to embed into any Qt application • Tight integration with rest of Qt • Easy-to-use API 12

14. QtScript tour (the essentials) • Basic embedding (example) • Working with QScriptValues • Configuring the script environment • Qt meta-object system integration 14

15. Example: Meaning of Life Calculator “Our objective: Write an application that uses QtScript to calculate the meaning of life” 15

16. QScriptEngine object QScriptEngine engine; • “Vanilla” environment • Built-in ECMA objects –Array, Math, RegExp, Error, ... –parseInt(), parseFloat(), ... • No Qt-specific script APIs 16

17. Mutating the Environment (I) 17

18. Mutating the Environment (II) • Evaluate scripts • Operate on QtScript values in C++ 18

20. QScriptValue class • Represents a QtScript (JavaScript) value • Undefined • Null • Boolean • Number • String • Object –Functions, arrays, regexps, errors, ... • Invalid (no value) 20

21. QScriptValue type checks & conversion • isXXX(): Tests if value is of a certain type • toXXX(): Converts to Qt/C++ type • qscriptvalue_cast(): Converts to C++ type 21

22. QScriptValue construction • Constructors for standard Qt/C++ types • qScriptValueFromValue() • Counterpart to qscriptvalue_cast() • QScriptEngine::newXXX() • Object, QObject, Array, RegExp 22

23. QScriptValue property access JS: myObject.foo = 123; myObject['foo'] = 123; C++: myObject.setProperty(“foo”, 123); 23

24. QScriptValue holds reference to object (I) QScriptValue object = engine.evaluate( “{ foo: 123, toString: function() { return 'MyObject(foo=' + this.foo + ')'; } }”); 24

25. QScriptValue holds reference to object (II) QScriptValue same = object; object.setProperty(“foo”, 456); qDebug() << same.toString(); 25

26. QScriptValue called as function JS: myArray.sort(); or myArray['sort'].call(myArray); C++: myArray.property(“sort”) .call(myArray); 26

27. Calling a function with arguments (I) JS: myObject.myFunction(123, “foo”); C++: myFunction.call( myObject, QScriptValueList() << 123 << “foo”); 27

28. Calling a function with arguments (II) QScriptValue adder = engine.evaluate( “(function(a, b) { return a+b; })”); QScriptValue result = adder.call( /*thisObject=*/QScriptValue(), QScriptValueList() << 41 << 1); 28

29. Calling a function as constructor (I) JS: function Point(x, y) { this.x = x; this.y = y; } ... new Point(10, 20); 29

30. Calling a function as constructor (II) C++: QScriptValue p = Point.construct( QScriptValueList() << 10 << 20); qDebug() << p.property(“x”).toNumber(); 30

31. QScriptValueIterator class QScriptValueIterator it(myObject); while (it.hasNext()) { it.next(); qDebug() << it.name(); } 31

32. Working with JavaScript Arrays (I) JS: var a = [10, 20, 30]; print(a[0], a['0']); // same property a.foo = 123; a.push(40); a[a.length] = 'appended'; 32

33. Working with JavaScript Arrays (II) C++: QScriptValue a = engine.evaluate( “[10, 20, 30]”); // array literal qDebug() << a.property(“length”).toInt32(); qDebug() << a.property(“0”).toNumber(); // for convenience + speed qDebug() << a.property(0).toNumber(); 33

34. Error Handling (I) // Uh-oh, this script will throw an error! QScriptValue result = engine.evaluate( “noSuchVariable”); 34

35. Error Handling (II) if (result.isError()) { QString message = result.toString(); // Notify user about the problem ... } 35

36. QScriptValue API Summary • isXXX(), toXXX() • property() and setProperty() • call(), construct() • QScriptValueIterator for introspection 36

38. The Global Object • A built-in script object • Every QScriptEngine has one • QScriptEngine::globalObject() • Initially contains properties defined by ECMA-262 38

39. Tailoring Scripting to Your Application • Design “contract” of C++ <--> script interaction • Set properties of Global Object • Evaluate scripts that use your API • (Optional: Call back into script objects as appropriate) 39

40. Example: Meaning of Life Environment C++: QScriptEngine engine; QScriptValue global = engine.globalObject(); global.setProperty(“meaningOfLife”, 42, QScriptValue::ReadOnly); JS: var myMeaningOfLife = Math.sqrt(meaningOfLife); 40

41. Example: Fake Navigator Object C++: QScriptValue navigator = engine.newObject(); navigator.setProperty(“appVersion”, 1); navigator.setProperty(“appMinorVersion”, 1); navigator.setProperty(“cookieEnabled”, false); navigator.setProperty(“browserLanguage”, “en_US”); navigator.setProperty(“platform”, “No Such OS”); navigator.setProperty(“userAgent”, “007”); global.setProperty(“navigator”, navigator); 41

43. Qt Meta-Object System • In Qt, QObject-based classes can be introspected at runtime • Properties • Signals & slots • QObject::connect() • Qt Designer property editor • ... 43

44. Relax! Leave it to magic 44

45. QtScript <--> QObject Integration (I) • QScriptEngine::newQObject(QObject*) • Returns a script object that acts as proxy • Proxy delegates property access to QObject::property() and QObject::setProperty() 45

46. QtScript <--> QObject Integration (II) • Proxy provides signals and slots as properties • Proxy provides named child objects as properties 46

47. QtScript <--> QObject Integration (III) • Ownership control • Customize proxy behavior • Don't expose child objects • Don't expose super class contents 47

48. Example: Scripting a QLineEdit 48

49. qScriptConnect() function • Connect a signal to a script function • Let scripts define signal handlers • Application does the “plumbing” 49

50. Summary of “API essentials” • QScriptValue • QScriptEngine • evaluate() • globalObject() • newQObject() • qScriptConnect() 50

52. The QtScript Debugger • Graphical debugger • Introduced in Qt 4.5 • To make the API available in your application: QT += scripttools #include <QtScriptTools> 52

53. Debugger Demo Look at the pretty little demo! 53

54. The QtScript Debugger API (I) One class in public API: QScriptEngineDebugger QScriptEngine engine; QScriptEngineDebugger debugger; debugger.attachTo(&engine); // evaluate scripts ... 54

55. The QtScript Debugger API (II) • Debugger actions can be programmatically triggered • Individual debugger widgets are accessible 55

56. Invoking the Debugger from a Script • Use the debugger keyword • Becomes no-op if no debugger is attached JS: var a = Math.random(); debugger; // synchronously run debugger var b = Math.random(); debugger; return a + b; 56

58. Prototypes...? 58

59. Prototype-based Inheritance (I) 59

60. Prototype-based Inheritance: Why care? • Not every QObject member is a property / signal / slot • Not everything is a QObject • Not everything should/needs to be a QObject • JS developers are familiar with prototypes 60

61. Prototype-based Inheritance: How? • Create a prototype object for the C++ type • Register the type with Qt's meta-type system • Associate prototype object with meta-type ID • Create QScriptValues from the C++ type (qScriptValueFromValue()) 61

62. Bindings for Qt's APIs (I) • Available as stand-alone project • qtscriptgenerator on Qt Labs (http://labs.qt.nokia.com) 62

63. Bindings for Qt's APIs (II) • Creates plugins that can be imported into a script engine • Provides bindings for most of Qt's classes • Makes it possible to write pure script applications 63

64. Summary • It's easy to make your Qt application scriptable with QtScript • There's a QtScript debugger (also part of Qt) • You can achieve a lot by mastering a small API 64

65. Thank You! Questions? 65

Scripting Your Qt Application

account inactive

Scripting Your Qt Application