/****************************************************************************

**

** Copyright (C) 2010 Nokia Corporation and/or its subsidiary(-ies).

** All rights reserved.

** Contact: Nokia Corporation (qt-info@nokia.com)

**

** This file is part of the documentation of the Qt Toolkit.

**

** $QT_BEGIN_LICENSE:LGPL$

** No Commercial Usage

** This file contains pre-release code and may not be distributed.

** You may use this file in accordance with the terms and conditions

** contained in the Technology Preview License Agreement accompanying

** this package.

**

** GNU Lesser General Public License Usage

** Alternatively, this file may be used under the terms of the GNU Lesser

** General Public License version 2.1 as published by the Free Software

** Foundation and appearing in the file LICENSE.LGPL included in the

** packaging of this file.  Please review the following information to

** ensure the GNU Lesser General Public License version 2.1 requirements

** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html.

**

** In addition, as a special exception, Nokia gives you certain additional

** rights.  These rights are described in the Nokia Qt LGPL Exception

** version 1.1, included in the file LGPL_EXCEPTION.txt in this package.

**

** If you have questions regarding the use of this file, please contact

** Nokia at qt-info@nokia.com.

**

**

**

**

**

**

**

**

** $QT_END_LICENSE$

**

****************************************************************************/

/*!

    \title Moving from QSA to Qt Script

    \page porting-qsa.html

    \ingroup porting

    The purpose of this document is to map the differences between Qt

    Script for Applications (QSA) and Qt Script, the ECMAScript compatible

    engine supplied with Qt 4.3. This document is not supposed to be a

    complete function by function porting guide, but will cover the most

    obvious aspects.

    First of all it is important to realize that Qt Script is only an

    interpreter, it does not provide an editor, completion or script project

    management, like QSA does. Qt Script however does provides almost full

    compliance with the ECMAScript standard and performs significantly

    better than the script engine provided by QSA. 

    \tableofcontents

    \section1 The Scripting Language

    The scripting language used in QSA, from here on referred to as QSA,

    was derived from ECMAScript 3.0 and 4.0 and is a hybrid of these

    standards. Most of the run-time logic, such as classes and scoping

    rules, is based on the ECMAScript 4.0 proposal, while the library

    implementation is based on the ECMAScript 3.0 standard.

    Qt Script on the other hand is solely based on the ECMAScript 3.0

    standard. Though the languages look identical at first glance,

    there are a few differences that we'll cover in the sections below.

    \section2 Classes vs. Objects and Properties

    QSA implements classes and inheritance much in a familiar way to users

    of other object oriented languages, like C++ and Java. However, the

    ECMAScript 3.0 standard defines that everything is an object, and objects

    can have named properties. For instance to create an point object with

    the properties x and y one would write the following Qt Script code:

    \snippet doc/src/snippets/code/doc_src_porting-qsa.qdoc 0

    The object \c point in this case is constructed as a plain object and

    we assign two properties, \c x and \c y, to it with the values 12 and

    35. The \c point object is assigned to the "Global Object" as the

    named property \c{point}. The global object can be considered the

    global namespace of the script engine. Similarly, global functions are

    named properties of the global object; for example:

    \snippet doc/src/snippets/code/doc_src_porting-qsa.qdoc 1

    An equivalent construction that illustrates that the function is a

    property of the global object is the following assignment:

    \snippet doc/src/snippets/code/doc_src_porting-qsa.qdoc 2

    Since functions are objects, they can be assigned to objects as

    properties, becoming member functions:

    \snippet doc/src/snippets/code/doc_src_porting-qsa.qdoc 3

    In the code above, we see the first subtle difference between

    QSA and Qt Script. In QSA one would write the point class like this:

    \snippet doc/src/snippets/code/doc_src_porting-qsa.qdoc 4

    where in the \c manhattanLength() function we access \c x and \c y

    directly because, when the function is called, the \c this object is

    implicitly part of the current scope, as in C++. In Qt Script,

    however, this is not the case, and we need to explicitly access

    the \c x and \c y values via \c{this}.

    All the code above runs with QSA except the assignment of a function

    to \c{point.manhattanLength}, which we repeat here for clarity:

    \snippet doc/src/snippets/code/doc_src_porting-qsa.qdoc 5

    This is because, in QSA, the value of \c this is decided based on

    the location of the declaration of the function it is used in. In the

    code above, the function is assigned to an object, but it is declared

    in the global scope, hence there will be no valid \c this value.

    In Qt Script, the value of \c this is decided at run-time,

    hence you could have assigned the \c manhattanLength() function to any

    object that had \c x and \c y values.

    \section2 Constructors

    In the code above, we use a rather awkward method for constructing

    the objects, by first instantiating them, then manually

    assigning properties to them. In QSA, the proper way to solve this

    is to implement a constructor in the class:

    \snippet doc/src/snippets/code/doc_src_porting-qsa.qdoc 6

    The equivalent in Qt Script is to create a constructor function:

    \snippet doc/src/snippets/code/doc_src_porting-qsa.qdoc 7

    As we can see, the constructor is just a normal function. What is

    special with is how we call it, namely prefixed with the \c new

    keyword. This will create a new object and call the \c Car()

    function with the newly created object as the \c this pointer.

    So, in a sense, it is equivalent to:

    \snippet doc/src/snippets/code/doc_src_porting-qsa.qdoc 8

    This is similar to the manhattenLength() example above. Again, the

    main difference between QSA and Qt Script is that one has to

    explicitly use the keyword \c this to access the members and that

    instead of declaring the variable, \c regNumber, we just extend the

    \c this object with the property.

    \section2 Member Functions and Prototypes

    As we saw above, one way of creating member functions of a Qt Script

    object is to assign the member function to the object as a property

    and use the \c this object inside the functions. So, if we add a

    \c toString function to the \c Car class

    \snippet doc/src/snippets/code/doc_src_porting-qsa.qdoc 9

    one could write this in Qt Script as:

    \snippet doc/src/snippets/code/doc_src_porting-qsa.qdoc 10

    In QSA, the member functions were part of the class declaration,

    and were therefore shared between all instances of a given class.

    In Qt Script, each instance has a instance member for each function.

    This means that more memory is used when multiple instances are used.

    Qt Script uses prototypes to remedy this. 

    The basic prototype-based inheritance mechanism works as follows.

    Each Qt Script object has an internal link to another object, its

    prototype. When a property is looked up in an object, and the object

    itself does not have the property, the interpreter searches for the

    property in the prototype object instead; if the prototype has the

    property then that property is returned. If the prototype object does

    not have the property, the interpreter searches for the property in

    the prototype of the prototype object, and so on.

    This chain of objects constitutes a prototype chain. The chain of

    prototype objects is followed until the property is found or the end

    of the chain is reached.

    To make the \c toString() function part of the prototype, we write

    code like this:

    \snippet doc/src/snippets/code/doc_src_porting-qsa.qdoc 11

    Here, we made the \c toString() function part of the prototype so

    that, when we call \c{car.toString()} it will be resolved via the

    internal prototype object of the car object. Note, however, that the

    \c this object is still the original object that the function was

    called on, namely \c{car}.

    \section2 Inheritance

    Now that we've seen how to use prototypes to create a "class" members

    in Qt Script, let's see how we can use prototypes to create

    polymorphism. In QSA you would write

    \snippet doc/src/snippets/code/doc_src_porting-qsa.qdoc 12

    With Qt Script, we acheive the same effect by creating a prototype

    chain. The default prototype of an object is a plain \c Object

    without any special members, but it is possible to replace this

    object with another prototype object.

    \snippet doc/src/snippets/code/doc_src_porting-qsa.qdoc 13

    In the code above, we have a constructor, \c{GasolineCar}, which

    calls the "base class" implementation of the constructor to

    initialize the \c this object with the property \c{regNumber},

    based on the values passed in the constructor. The interesting line

    in this case is the line after the constructor where we change the

    default prototype for \c GasolineCar to be an instance of type

    \c{Car}. This means that all members available in a \c Car object

    are now available in all \c GasolineCar objects. In the last line,

    we replace the \c toString() function in the prototype with our own,

    thus overriding the \c toString() for all instances of

    \c{GasolineCar}.

    \section2 Static Members

    QSA allowed users to declare static members in classes, and these

    could be accessed both through instances of the class and through

    the class itself. For example, the following variable is accessed

    through the \c Car class:

    \snippet doc/src/snippets/code/doc_src_porting-qsa.qdoc 14

    The equivalent in Qt Script is to assign variables that should appear

    as static members as properties of the constructor function. For

    example:

    \snippet doc/src/snippets/code/doc_src_porting-qsa.qdoc 15

    Note that in QSA, static member variables were also accessible in

    instances of the given class. In Qt Script, with the approach

    illustrated above, the variable is a member of the constructor

    object only, and thus only accessible through \c{Car.globalCount}.

    \section1 The Built-in Functions and Library

    The built-in functions in QSA are based on those defined in the

    ECMAScript 3.0 standard, the same standard used for Qt Script, but

    QSA adds some extensions to this, specifically for the \c String

    and \c RegExp types. QSA also lacked some functions from the

    standard, most notably the \c Date type. Below we list all the

    differences. All changes made to Qt Script are to increase

    compliance with ECMAScript 3.0.

    \table

    \header \o QSA Function \o Notes about Equivalent Qt Script Functions

    \row \o eval()

    \o The eval function in QSA opened a new scope for code being

    executed in the eval function, so locally declared variables were not

    accessible outside. In Qt Script, the eval() function shares the

    current scope, making locally declared variables accessible outside

    the eval() call.

    \row \o debug()

    \o This function is not available in Qt Script. Use print() instead.

    \row \o connect()

    \o QSA had closures, meaning that a member function

    reference implicitly contained its \c this object. Qt Script does not

    support this. See the Qt Script documentation for details on using the

    connect function.

    \row \o String.arg()

    \o This function is not available in Qt Script. Use replace() or concat() instead.

    \row \o String.argDec()

    \o This function is not available in Qt Script. Use replace() or concat() instead.

    \row \o String.argInt()

    \o This function is not available in Qt Script. Use replace() or concat() instead.

    \row \o String.argStr()

    \o This function is not available in Qt Script. Use replace() or concat() instead.

    \row \o String.endsWith()

    \o This function is not available in Qt Script. Use lastIndexOf() instead.

    \row \o String.find()

    \o This function is not available in Qt Script. Use indexOf() instead.

    \row \o String.findRev()

    \o This function is not available in Qt Script. Use lastIndexOf() and length instead.

    \row \o String.isEmpty()

    \o This function is not available in Qt Script. Use length == 0 instead.

    \row \o String.left()

    \o This function is not available in Qt Script. Use substring() instead.

    \row \o String.lower()

    \o This function is not available in Qt Script. Use toLowerCase() instead.

    \row \o String.mid()

    \o This function is not available in Qt Script. Use substring() instead.

    \row \o String.right()

    \o This function is not available in Qt Script. Use substring() instead.

    \row \o String.searchRev()

    \o This function is not available in Qt Script. Use search() / match() instead.

    \row \o String.startsWith()

    \o This function is not available in Qt Script. Use indexOf() == 0 instead.

    \row \o String.upper()

    \o This function is not available in Qt Script. Use toUpperCase() instead.

    \row \o RegExp.valid

    \o This property is not available in Qt Script because it is not

       required; a \c SyntaxError exception is thrown for bad \c RegExp objects.

    \row \o RegExp.empty

    \o This property is not available in Qt Script. Use \c{toString().length == 0} instead.

    \row \o RegExp.matchedLength

    \o This property is not available in Qt Script. RegExp.exec() returns an

       array whose size is the matched length.

    \row \o RegExp.capturedTexts

    \o This property is not available in Qt Script. RegExp.exec() returns an

       array of captured texts.

    \row \o RegExp.search()

    \o This function is not available in Qt Script. Use RegExp.exec() instead.

    \row \o RegExp.searchRev()

    \o This function is not available in Qt Script. Use RegExp.exec() or

       String.search()/match() instead.

    \row \o RegExp.exactMatch()

    \o This function is not available in Qt Script. Use RegExp.exec() instead.

    \row \o RegExp.pos()

    \o This function is not available in Qt Script. Use String.match() instead.

    \row \o RegExp.cap()

    \o This function is not available in Qt Script. RegExp.exec() returns an

       array of captured texts.

    \endtable

    QSA also defined some internal Qt API which is not present in Qt

    Script. The types provided by QSA which are not provided by Qt Script are:

    \list

    \o Rect

    \o Point

    \o Size

    \o Color

    \o Palette

    \o ColorGroup

    \o Font

    \o Pixmap

    \o ByteArray

    \endlist

    \section1 The C++ API of QSA vs Qt Script

    QSA is more than just a scripting engine. It provides project

    management, an editor with completion and a minimalistic IDE to edit

    scriptable projects. Qt Script on the other hand is just a scripting

    engine. This means that equivalents to the classes \c QSEditor,

    \c QSScript, \c QSProject and \c QSWorkbench do not exist in Qt Script.

    QSA also provides some extension APIs through the \c QSUtilFactory and

    \c QSInputDialogFactory. There is also no equivalent to these classes

    in the Qt Script API.

    \section2 Making QObjects Accessible from Scripts

    There are two different ways of making \l{QObject}s accessible from

    scripts in QSA. The first method is via the

    \c QSInterpreter::addTransientObject() and \c QSProject::addObject()

    functions. In this case objects are added to the global namespace of

    the interpreter using their object names as the names of the

    variables.

    \snippet doc/src/snippets/code/doc_src_porting-qsa.qdoc 16

    The code above adds the button to the global namespace under the name

    "button". One obvious limitation here is that there is potential for

    either unnamed \l{QObject}s or objects whose names conflict. Qt Script

    provides a more flexible way of adding QObjects to the scripting

    environment.

    \snippet doc/src/snippets/code/doc_src_porting-qsa.qdoc 17

    In the code above we create a QPushButton and wrap it in a script

    value using the function, QScriptEngine::newQObject(). This gives us

    a script value that we put into the global object using the name

    "button". The concept of objects and properties discussed above is

    quite visible here in the public C++ API as well. We have no

    dependency on the object's name and we can also resolve name conflicts

    more gracefully. Here, we operate directly on QScriptValue objects.

    This is the actual object that is being passed around inside

    the script engine, so we actually have low-level access to the

    internal script data structures, far beyond that which is possible

    in QSA. Properties, signals and slots of the QObject are accessible

    to the scripter in Qt Script, just like in QSA.

    The other way to expose \l{QObject}s in QSA was to create a

    \c QSObjectFactory that made it possible to instantiate QObjects from

    scripts.

    Below is listed some code from the filter example in the QSA

    package.

    \snippet doc/src/snippets/code/doc_src_porting-qsa.qdoc 18

    The equivalent in Qt Script is written in much the same way as

    constructors are written in scripts. We register a callback C++

    function under the name "ImageSource" in the global namespace and

    return the QObject from this function:

    \snippet doc/src/snippets/code/doc_src_porting-qsa.qdoc 19

    In the Qt Script case we use the same approach that we use to expose

    a QObject, namely via QScriptEngine::newQObject(). This function also

    has the benefit that it is possible to specify if the QObject should

    expose properties and slots of its base class. It is also possible to

    specify custom ownership rules.

    The reader might question why we don't add the constructor function

    directly into the namespace, but create a meta-object script value for

    it in addition. The plain function would certainly be good enough,

    but by creating a QMetaObject based constructor we get the enums on

    QPushButton for free in the QPushButton function object. Exposing

    enums in QSA is rather painful in comparison.

    If we want to add more "static" data to the QPushButton type in Qt

    Script, we're free to add properties, similar to how we did for

    the script. It is also possible to add custom functions to a Qt Script

    QPushButton instance by setting more properties on it, such as making

    the \l{QPushButton::}{setText()} C++ function available. It is also

    possible to acheive this by installing a custom prototype, and be

    memory efficient, as discussed in the script example above.

    \section2 Accessing Non-QObjects

    In QSA, it was possible to expose non-QObjects to QSA by wrapping them

    in a QObject and using either \c QSWrapperFactory or \c QSObjectFactory

    to expose them. Deciding when to use each of these classes could be

    confusing, as one was used for script based construction and the other

    for wrapping function parameters and return values, but in essence they

    did exactly the same thing.

    In Qt Script, providing access to QObjects and non-QObjects is done in

    the same way as shown above, by creating a constructor function, and

    by adding properties or a custom prototype to the constructed object.

    \section2 Data Mapping

    QSA supported a hardcoded set of type mappings which covered most

    of the QVariant types, QObjects and primitives. For more complex type

    signatures, such as the template-based tool classes, it had rather

    limited support. Qt Script is significantly better at type mapping

    and will convert lists of template types into arrays of the

    appropriate types, given that all the types are declared to the

    meta-type system.

*/