doc/src/porting/porting-qsa.qdoc

   1 /****************************************************************************
   2 **
   3 ** Copyright (C) 2015 The Qt Company Ltd.
   4 ** Contact: http://www.qt.io/licensing/
   5 **
   6 ** This file is part of the documentation of the Qt Toolkit.
   7 **
   8 ** $QT_BEGIN_LICENSE:FDL$
   9 ** Commercial License Usage
  10 ** Licensees holding valid commercial Qt licenses may use this file in
  11 ** accordance with the commercial license agreement provided with the
  12 ** Software or, alternatively, in accordance with the terms contained in
  13 ** a written agreement between you and The Qt Company. For licensing terms
  14 ** and conditions see http://www.qt.io/terms-conditions. For further
  15 ** information use the contact form at http://www.qt.io/contact-us.
  16 **
  17 ** GNU Free Documentation License Usage
  18 ** Alternatively, this file may be used under the terms of the GNU Free
  19 ** Documentation License version 1.3 as published by the Free Software
  20 ** Foundation and appearing in the file included in the packaging of
  21 ** this file.  Please review the following information to ensure
  22 ** the GNU Free Documentation License version 1.3 requirements
  23 ** will be met: http://www.gnu.org/copyleft/fdl.html.
  24 ** $QT_END_LICENSE$
  25 **
  26 ****************************************************************************/
  27
  28 /*!
  29     \title Moving from QSA to Qt Script
  30     \page porting-qsa.html
  31     \ingroup porting
  32
  33     The purpose of this document is to map the differences between Qt
  34     Script for Applications (QSA) and Qt Script, the ECMAScript compatible
  35     engine supplied with Qt 4.3. This document is not supposed to be a
  36     complete function by function porting guide, but will cover the most
  37     obvious aspects.
  38
  39     First of all it is important to realize that Qt Script is only an
  40     interpreter, it does not provide an editor, completion or script project
  41     management, like QSA does. Qt Script however does provides almost full
  42     compliance with the ECMAScript standard and performs significantly
  43     better than the script engine provided by QSA.
  44
  45     \tableofcontents
  46
  47     \section1 The Scripting Language
  48
  49     The scripting language used in QSA, from here on referred to as QSA,
  50     was derived from ECMAScript 3.0 and 4.0 and is a hybrid of these
  51     standards. Most of the run-time logic, such as classes and scoping
  52     rules, is based on the ECMAScript 4.0 proposal, while the library
  53     implementation is based on the ECMAScript 3.0 standard.
  54     Qt Script on the other hand is solely based on the ECMAScript 3.0
  55     standard. Though the languages look identical at first glance,
  56     there are a few differences that we'll cover in the sections below.
  57
  58
  59     \section2 Classes vs. Objects and Properties
  60
  61     QSA implements classes and inheritance much in a familiar way to users
  62     of other object oriented languages, like C++ and Java. However, the
  63     ECMAScript 3.0 standard defines that everything is an object, and objects
  64     can have named properties. For instance to create an point object with
  65     the properties x and y one would write the following Qt Script code:
  66
  67     \snippet doc/src/snippets/code/doc_src_porting-qsa.js 0
  68
  69     The object \c point in this case is constructed as a plain object and
  70     we assign two properties, \c x and \c y, to it with the values 12 and
  71     35. The \c point object is assigned to the "Global Object" as the
  72     named property \c{point}. The global object can be considered the
  73     global namespace of the script engine. Similarly, global functions are
  74     named properties of the global object; for example:
  75
  76     \snippet doc/src/snippets/code/doc_src_porting-qsa.js 1
  77
  78     An equivalent construction that illustrates that the function is a
  79     property of the global object is the following assignment:
  80
  81     \snippet doc/src/snippets/code/doc_src_porting-qsa.js 2
  82
  83     Since functions are objects, they can be assigned to objects as
  84     properties, becoming member functions:
  85
  86     \snippet doc/src/snippets/code/doc_src_porting-qsa.js 3
  87
  88     In the code above, we see the first subtle difference between
  89     QSA and Qt Script. In QSA one would write the point class like this:
  90
  91     \snippet doc/src/snippets/code/doc_src_porting-qsa.qdoc 4
  92
  93     where in the \c manhattanLength() function we access \c x and \c y
  94     directly because, when the function is called, the \c this object is
  95     implicitly part of the current scope, as in C++. In Qt Script,
  96     however, this is not the case, and we need to explicitly access
  97     the \c x and \c y values via \c{this}.
  98
  99     All the code above runs with QSA except the assignment of a function
 100     to \c{point.manhattanLength}, which we repeat here for clarity:
 101
 102     \snippet doc/src/snippets/code/doc_src_porting-qsa.js 5
 103
 104     This is because, in QSA, the value of \c this is decided based on
 105     the location of the declaration of the function it is used in. In the
 106     code above, the function is assigned to an object, but it is declared
 107     in the global scope, hence there will be no valid \c this value.
 108     In Qt Script, the value of \c this is decided at run-time,
 109     hence you could have assigned the \c manhattanLength() function to any
 110     object that had \c x and \c y values.
 111
 112
 113     \section2 Constructors
 114
 115     In the code above, we use a rather awkward method for constructing
 116     the objects, by first instantiating them, then manually
 117     assigning properties to them. In QSA, the proper way to solve this
 118     is to implement a constructor in the class:
 119
 120     \snippet doc/src/snippets/code/doc_src_porting-qsa.qdoc 6
 121
 122     The equivalent in Qt Script is to create a constructor function:
 123
 124     \snippet doc/src/snippets/code/doc_src_porting-qsa.qdoc 7
 125
 126     As we can see, the constructor is just a normal function. What is
 127     special with is how we call it, namely prefixed with the \c new
 128     keyword. This will create a new object and call the \c Car()
 129     function with the newly created object as the \c this pointer.
 130     So, in a sense, it is equivalent to:
 131
 132     \snippet doc/src/snippets/code/doc_src_porting-qsa.js 8
 133
 134     This is similar to the manhattenLength() example above. Again, the
 135     main difference between QSA and Qt Script is that one has to
 136     explicitly use the keyword \c this to access the members and that
 137     instead of declaring the variable, \c regNumber, we just extend the
 138     \c this object with the property.
 139
 140
 141     \section2 Member Functions and Prototypes
 142
 143     As we saw above, one way of creating member functions of a Qt Script
 144     object is to assign the member function to the object as a property
 145     and use the \c this object inside the functions. So, if we add a
 146     \c toString function to the \c Car class
 147
 148     \snippet doc/src/snippets/code/doc_src_porting-qsa.qdoc 9
 149
 150     one could write this in Qt Script as:
 151
 152     \snippet doc/src/snippets/code/doc_src_porting-qsa.js 10
 153
 154     In QSA, the member functions were part of the class declaration,
 155     and were therefore shared between all instances of a given class.
 156     In Qt Script, each instance has a instance member for each function.
 157     This means that more memory is used when multiple instances are used.
 158     Qt Script uses prototypes to remedy this.
 159
 160     The basic prototype-based inheritance mechanism works as follows.
 161     Each Qt Script object has an internal link to another object, its
 162     prototype. When a property is looked up in an object, and the object
 163     itself does not have the property, the interpreter searches for the
 164     property in the prototype object instead; if the prototype has the
 165     property then that property is returned. If the prototype object does
 166     not have the property, the interpreter searches for the property in
 167     the prototype of the prototype object, and so on.
 168
 169     This chain of objects constitutes a prototype chain. The chain of
 170     prototype objects is followed until the property is found or the end
 171     of the chain is reached.
 172
 173     To make the \c toString() function part of the prototype, we write
 174     code like this:
 175
 176     \snippet doc/src/snippets/code/doc_src_porting-qsa.js 11
 177
 178     Here, we made the \c toString() function part of the prototype so
 179     that, when we call \c{car.toString()} it will be resolved via the
 180     internal prototype object of the car object. Note, however, that the
 181     \c this object is still the original object that the function was
 182     called on, namely \c{car}.
 183
 184
 185     \section2 Inheritance
 186
 187     Now that we've seen how to use prototypes to create a "class" members
 188     in Qt Script, let's see how we can use prototypes to create
 189     polymorphism. In QSA you would write
 190
 191     \snippet doc/src/snippets/code/doc_src_porting-qsa.qdoc 12
 192
 193     With Qt Script, we acheive the same effect by creating a prototype
 194     chain. The default prototype of an object is a plain \c Object
 195     without any special members, but it is possible to replace this
 196     object with another prototype object.
 197
 198     \snippet doc/src/snippets/code/doc_src_porting-qsa.js 13
 199
 200     In the code above, we have a constructor, \c{GasolineCar}, which
 201     calls the "base class" implementation of the constructor to
 202     initialize the \c this object with the property \c{regNumber},
 203     based on the values passed in the constructor. The interesting line
 204     in this case is the line after the constructor where we change the
 205     default prototype for \c GasolineCar to be an instance of type
 206     \c{Car}. This means that all members available in a \c Car object
 207     are now available in all \c GasolineCar objects. In the last line,
 208     we replace the \c toString() function in the prototype with our own,
 209     thus overriding the \c toString() for all instances of
 210     \c{GasolineCar}.
 211
 212
 213     \section2 Static Members
 214
 215     QSA allowed users to declare static members in classes, and these
 216     could be accessed both through instances of the class and through
 217     the class itself. For example, the following variable is accessed
 218     through the \c Car class:
 219
 220     \snippet doc/src/snippets/code/doc_src_porting-qsa.qdoc 14
 221
 222     The equivalent in Qt Script is to assign variables that should appear
 223     as static members as properties of the constructor function. For
 224     example:
 225
 226     \snippet doc/src/snippets/code/doc_src_porting-qsa.js 15
 227
 228     Note that in QSA, static member variables were also accessible in
 229     instances of the given class. In Qt Script, with the approach
 230     illustrated above, the variable is a member of the constructor
 231     object only, and thus only accessible through \c{Car.globalCount}.
 232
 233
 234     \section1 The Built-in Functions and Library
 235
 236     The built-in functions in QSA are based on those defined in the
 237     ECMAScript 3.0 standard, the same standard used for Qt Script, but
 238     QSA adds some extensions to this, specifically for the \c String
 239     and \c RegExp types. QSA also lacked some functions from the
 240     standard, most notably the \c Date type. Below we list all the
 241     differences. All changes made to Qt Script are to increase
 242     compliance with ECMAScript 3.0.
 243
 244     \table
 245     \header \o QSA Function \o Notes about Equivalent Qt Script Functions
 246     \row \o eval()
 247     \o The eval function in QSA opened a new scope for code being
 248     executed in the eval function, so locally declared variables were not
 249     accessible outside. In Qt Script, the eval() function shares the
 250     current scope, making locally declared variables accessible outside
 251     the eval() call.
 252
 253     \row \o debug()
 254     \o This function is not available in Qt Script. Use print() instead.
 255
 256     \row \o connect()
 257     \o QSA had closures, meaning that a member function
 258     reference implicitly contained its \c this object. Qt Script does not
 259     support this. See the Qt Script documentation for details on using the
 260     connect function.
 261
 262     \row \o String.arg()
 263     \o This function is not available in Qt Script. Use replace() or concat() instead.
 264
 265     \row \o String.argDec()
 266     \o This function is not available in Qt Script. Use replace() or concat() instead.
 267
 268     \row \o String.argInt()
 269     \o This function is not available in Qt Script. Use replace() or concat() instead.
 270
 271     \row \o String.argStr()
 272     \o This function is not available in Qt Script. Use replace() or concat() instead.
 273
 274     \row \o String.endsWith()
 275     \o This function is not available in Qt Script. Use lastIndexOf() instead.
 276
 277     \row \o String.find()
 278     \o This function is not available in Qt Script. Use indexOf() instead.
 279
 280     \row \o String.findRev()
 281     \o This function is not available in Qt Script. Use lastIndexOf() and length instead.
 282
 283     \row \o String.isEmpty()
 284     \o This function is not available in Qt Script. Use length == 0 instead.
 285
 286     \row \o String.left()
 287     \o This function is not available in Qt Script. Use substring() instead.
 288
 289     \row \o String.lower()
 290     \o This function is not available in Qt Script. Use toLowerCase() instead.
 291
 292     \row \o String.mid()
 293     \o This function is not available in Qt Script. Use substring() instead.
 294
 295     \row \o String.right()
 296     \o This function is not available in Qt Script. Use substring() instead.
 297
 298     \row \o String.searchRev()
 299     \o This function is not available in Qt Script. Use search() / match() instead.
 300
 301     \row \o String.startsWith()
 302     \o This function is not available in Qt Script. Use indexOf() == 0 instead.
 303
 304     \row \o String.upper()
 305     \o This function is not available in Qt Script. Use toUpperCase() instead.
 306
 307     \row \o RegExp.valid
 308     \o This property is not available in Qt Script because it is not
 309        required; a \c SyntaxError exception is thrown for bad \c RegExp objects.
 310
 311     \row \o RegExp.empty
 312     \o This property is not available in Qt Script. Use \c{toString().length == 0} instead.
 313
 314     \row \o RegExp.matchedLength
 315     \o This property is not available in Qt Script. RegExp.exec() returns an
 316        array whose size is the matched length.
 317
 318     \row \o RegExp.capturedTexts
 319     \o This property is not available in Qt Script. RegExp.exec() returns an
 320        array of captured texts.
 321
 322     \row \o RegExp.search()
 323     \o This function is not available in Qt Script. Use RegExp.exec() instead.
 324
 325     \row \o RegExp.searchRev()
 326     \o This function is not available in Qt Script. Use RegExp.exec() or
 327        String.search()/match() instead.
 328
 329     \row \o RegExp.exactMatch()
 330     \o This function is not available in Qt Script. Use RegExp.exec() instead.
 331
 332     \row \o RegExp.pos()
 333     \o This function is not available in Qt Script. Use String.match() instead.
 334
 335     \row \o RegExp.cap()
 336     \o This function is not available in Qt Script. RegExp.exec() returns an
 337        array of captured texts.
 338     \endtable
 339
 340     QSA also defined some internal Qt API which is not present in Qt
 341     Script. The types provided by QSA which are not provided by Qt Script are:
 342
 343     \list
 344     \o Rect
 345     \o Point
 346     \o Size
 347     \o Color
 348     \o Palette
 349     \o ColorGroup
 350     \o Font
 351     \o Pixmap
 352     \o ByteArray
 353     \endlist
 354
 355
 356     \section1 The C++ API of QSA vs Qt Script
 357
 358     QSA is more than just a scripting engine. It provides project
 359     management, an editor with completion and a minimalistic IDE to edit
 360     scriptable projects. Qt Script on the other hand is just a scripting
 361     engine. This means that equivalents to the classes \c QSEditor,
 362     \c QSScript, \c QSProject and \c QSWorkbench do not exist in Qt Script.
 363     QSA also provides some extension APIs through the \c QSUtilFactory and
 364     \c QSInputDialogFactory. There is also no equivalent to these classes
 365     in the Qt Script API.
 366
 367
 368     \section2 Making QObjects Accessible from Scripts
 369
 370     There are two different ways of making \l{QObject}s accessible from
 371     scripts in QSA. The first method is via the
 372     \c QSInterpreter::addTransientObject() and \c QSProject::addObject()
 373     functions. In this case objects are added to the global namespace of
 374     the interpreter using their object names as the names of the
 375     variables.
 376
 377     \snippet doc/src/snippets/code/doc_src_porting-qsa.cpp 16
 378
 379     The code above adds the button to the global namespace under the name
 380     "button". One obvious limitation here is that there is potential for
 381     either unnamed \l{QObject}s or objects whose names conflict. Qt Script
 382     provides a more flexible way of adding QObjects to the scripting
 383     environment.
 384
 385     \snippet doc/src/snippets/code/doc_src_porting-qsa.cpp 17
 386
 387     In the code above we create a QPushButton and wrap it in a script
 388     value using the function, QScriptEngine::newQObject(). This gives us
 389     a script value that we put into the global object using the name
 390     "button". The concept of objects and properties discussed above is
 391     quite visible here in the public C++ API as well. We have no
 392     dependency on the object's name and we can also resolve name conflicts
 393     more gracefully. Here, we operate directly on QScriptValue objects.
 394     This is the actual object that is being passed around inside
 395     the script engine, so we actually have low-level access to the
 396     internal script data structures, far beyond that which is possible
 397     in QSA. Properties, signals and slots of the QObject are accessible
 398     to the scripter in Qt Script, just like in QSA.
 399
 400     The other way to expose \l{QObject}s in QSA was to create a
 401     \c QSObjectFactory that made it possible to instantiate QObjects from
 402     scripts.
 403
 404     Below is listed some code from the filter example in the QSA
 405     package.
 406
 407     \snippet doc/src/snippets/code/doc_src_porting-qsa.cpp 18
 408
 409     The equivalent in Qt Script is written in much the same way as
 410     constructors are written in scripts. We register a callback C++
 411     function under the name "ImageSource" in the global namespace and
 412     return the QObject from this function:
 413
 414     \snippet doc/src/snippets/code/doc_src_porting-qsa.cpp 19
 415
 416     In the Qt Script case we use the same approach that we use to expose
 417     a QObject, namely via QScriptEngine::newQObject(). This function also
 418     has the benefit that it is possible to specify if the QObject should
 419     expose properties and slots of its base class. It is also possible to
 420     specify custom ownership rules.
 421
 422     The reader might question why we don't add the constructor function
 423     directly into the namespace, but create a meta-object script value for
 424     it in addition. The plain function would certainly be good enough,
 425     but by creating a QMetaObject based constructor we get the enums on
 426     QPushButton for free in the QPushButton function object. Exposing
 427     enums in QSA is rather painful in comparison.
 428
 429     If we want to add more "static" data to the QPushButton type in Qt
 430     Script, we're free to add properties, similar to how we did for
 431     the script. It is also possible to add custom functions to a Qt Script
 432     QPushButton instance by setting more properties on it, such as making
 433     the \l{QPushButton::}{setText()} C++ function available. It is also
 434     possible to acheive this by installing a custom prototype, and be
 435     memory efficient, as discussed in the script example above.
 436
 437
 438     \section2 Accessing Non-QObjects
 439
 440     In QSA, it was possible to expose non-QObjects to QSA by wrapping them
 441     in a QObject and using either \c QSWrapperFactory or \c QSObjectFactory
 442     to expose them. Deciding when to use each of these classes could be
 443     confusing, as one was used for script based construction and the other
 444     for wrapping function parameters and return values, but in essence they
 445     did exactly the same thing.
 446
 447     In Qt Script, providing access to QObjects and non-QObjects is done in
 448     the same way as shown above, by creating a constructor function, and
 449     by adding properties or a custom prototype to the constructed object.
 450
 451
 452     \section2 Data Mapping
 453
 454     QSA supported a hardcoded set of type mappings which covered most
 455     of the QVariant types, QObjects and primitives. For more complex type
 456     signatures, such as the template-based tool classes, it had rather
 457     limited support. Qt Script is significantly better at type mapping
 458     and will convert lists of template types into arrays of the
 459     appropriate types, given that all the types are declared to the
 460     meta-type system.
 461 */