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

**

** Copyright (C) 2009 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$

**

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

/*!

    \group script

    \title Scripting Classes and Overviews

    \brief Classes that add scripting capabilities to Qt applications.

*/

/*!

  \page scripting.html

  \title Making Applications Scriptable

  \ingroup frameworks-technologies

  Qt 4.3 and later provides support for application scripting with ECMAScript.

  The following guides and references cover aspects of programming with

  ECMAScript and Qt.

  \tableofcontents

  \section1 Scripting Classes

  The following classes add scripting capabilities to Qt applications.

  \annotatedlist script

  \section1 Language Overview

  Qt Script is based on the ECMAScript scripting language, as defined

  in standard \l{ECMA-262}. Microsoft's JScript, and Netscape's

  JavaScript are also based on the ECMAScript standard. For an

  overview of ECMAScript, see the

  \l{ECMAScript Reference}{ECMAScript reference}.

  If you are not familiar with the ECMAScript language, there are

  several existing tutorials and books that cover this subject, such

  as \l{JavaScript: The Definitive Guide}.

  Existing users of \l{Qt Script for Applications (QSA)} may find the

  \l{Moving from QSA to Qt Script} document useful when porting

  QSA scripts to Qt Script.

  \section1 Basic Usage

  To evaluate script code, you create a QScriptEngine and call its

  evaluate() function, passing the script code (text) to evaluate

  as argument.

  \snippet doc/src/snippets/qtscript/evaluation/main.cpp 0

  The return value will be the result of the evaluation (represented

  as a QScriptValue object); this can be converted to standard C++

  and Qt types.

  Custom properties can be made available to scripts by registering

  them with the script engine. This is most easily done by setting

  properties of the script engine's \e{Global Object}:

  \snippet doc/src/snippets/qtscript/registeringvalues/main.cpp 0

  This places the properties in the script environment, thus making them

  available to script code.

  \section1 Making a QObject Available to the Script Engine

  Any QObject-based instance can be made available for use with scripts.

  When a QObject is passed to the QScriptEngine::newQObject() function,

  a Qt Script wrapper object is created that can be used to make the

  QObject's signals, slots, properties, and child objects available

  to scripts.

  Here's an example of making an instance of a QObject subclass

  available to script code under the name \c{"myObject"}:

  \snippet doc/src/snippets/qtscript/registeringobjects/main.cpp 0

  This will create a global variable called \c{myObject} in the

  script environment. The variable serves as a proxy to the

  underlying C++ object. Note that the name of the script variable

  can be anything; i.e., it is not dependent upon QObject::objectName().

  The \l{QScriptEngine::}{newQObject()} function accepts two additional

  optional arguments: one is the ownership mode, and the other is a

  collection of options that allow you to control certain aspects of how

  the QScriptValue that wraps the QObject should behave. We will come

  back to the usage of these arguments later.

  \section2 Using Signals and Slots

  Qt Script adapts Qt's central \l{Signals and Slots} feature for

  scripting. There are three principal ways to use signals and slots

  with Qt Script:

  \list

  \i \bold{Hybrid C++/script}: C++ application code connects a

  signal to a script function. The script function can, for example, be

  a function that the user has typed in, or one that you have read from a

  file. This approach is useful if you have a QObject but don't want

  to expose the object itself to the scripting environment; you just

  want a script to be able to define how a signal should be reacted

  to, and leave it up to the C++ side of your application to establish

  the connection.

  \i \bold{Hybrid script/C++}: A script can connect signals and slots

  to establish connections between pre-defined objects that the

  application exposes to the scripting environment. In this scenario,

  the slots themselves are still written in C++, but the definition of

  the connections is fully dynamic (script-defined).

  \i \bold{Purely script-defined}: A script can both define signal

  handler functions (effectively "slots written in Qt Script"),

  \e{and} set up the connections that utilize those handlers. For

  example, a script can define a function that will handle the

  QLineEdit::returnPressed() signal, and then connect that signal to the

  script function.

  \endlist

  Use the qScriptConnect() function to connect a C++ signal to a

  script function. In the following example a script signal handler is

  defined that will handle the QLineEdit::textChanged() signal:

  \snippet doc/src/snippets/code/doc_src_qtscript.qdoc 47

  The first two arguments to qScriptConnect() are the same

  as you would pass to QObject::connect() to establish a normal C++

  connection. The third argument is the script object that will act

  as the \c this object when the signal handler is invoked; in the above

  example we pass an invalid script value, so the \c this object will

  be the Global Object. The fourth argument is the script function

  ("slot") itself. The following example shows how the \c this argument

  can be put to use:

  \snippet doc/src/snippets/code/doc_src_qtscript.qdoc 48

  We create two QLineEdit objects and define a single signal handler

  function. The connections use the same handler function, but the

  function will be invoked with a different \c this object depending on

  which object's signal was triggered, so the output of the print()

  statement will be different for each.

  In script code, Qt Script uses a different syntax for connecting to

  and disconnecting from signals than the familiar C++ syntax; i.e.,

  QObject::connect().

  To connect to a signal, you reference the relevant signal as a property

  of the sender object, and invoke its \c{connect()} function. There

  are three overloads of \c{connect()}, each with a corresponding

  \c{disconnect()} overload. The following subsections describe these

  three forms.

  \section3 Signal to Function Connections

  \c{connect(function)}

  In this form of connection, the argument to \c{connect()} is the

  function to connect to the signal.

  \snippet doc/src/snippets/code/doc_src_qtscript.qdoc 2

  The argument can be a Qt Script function, as in the above

  example, or it can be a QObject slot, as in

  the following example:

  \snippet doc/src/snippets/code/doc_src_qtscript.qdoc 3

  When the argument is a QObject slot, the argument types of the

  signal and slot do not necessarily have to be compatible;

  QtScript will, if necessary, perform conversion of the signal

  arguments to match the argument types of the slot.

  To disconnect from a signal, you invoke the signal's

  \c{disconnect()} function, passing the function to disconnect

  as argument:

  \snippet doc/src/snippets/code/doc_src_qtscript.qdoc 4

  When a script function is invoked in response to a signal, the

  \c this object will be the Global Object.

  \section3 Signal to Member Function Connections

  \c{connect(thisObject, function)}

  In this form of the \c{connect()} function, the first argument

  is the object that will be bound to the variable, \c this, when

  the function specified using the second argument is invoked.

  If you have a push button in a form, you typically want to do

  something involving the form in response to the button's

  \c{clicked} signal; passing the form as the \c this object

  makes sense in such a case.

  \snippet doc/src/snippets/code/doc_src_qtscript.qdoc 5

  To disconnect from the signal, pass the same arguments to \c{disconnect()}:

  \snippet doc/src/snippets/code/doc_src_qtscript.qdoc 6

  \section3 Signal to Named Member Function Connections

  \c{connect(thisObject, functionName)}

  In this form of the \c{connect()} function, the first argument is

  the object that will be bound to the variable, \c this, when

  a function is invoked in response to the signal. The second argument

  specifies the name of a function that is connected to the signal,

  and this refers to a member function of the object passed as the

  first argument (\c thisObject in the above scheme).

  Note that the function is resolved when the connection is made, not

  when the signal is emitted.

  \snippet doc/src/snippets/code/doc_src_qtscript.qdoc 7

  To disconnect from the signal, pass the same arguments to \c{disconnect()}:

  \snippet doc/src/snippets/code/doc_src_qtscript.qdoc 8

  \section3 Error Handling

  When \c{connect()} or \c{disconnect()} succeeds, the function will

  return \c{undefined}; otherwise, it will throw a script exception.

  You can obtain an error message from the resulting \c{Error} object.

  Example:

  \snippet doc/src/snippets/code/doc_src_qtscript.qdoc 9

  \section3 Emitting Signals from Scripts

  To emit a signal from script code, you simply invoke the signal

  function, passing the relevant arguments:

  \snippet doc/src/snippets/code/doc_src_qtscript.qdoc 10

  It is currently not possible to define a new signal in a script;

  i.e., all signals must be defined by C++ classes.

  \section3 Overloaded Signals and Slots

  When a signal or slot is overloaded, QtScript will attempt to

  pick the right overload based on the actual types of the QScriptValue arguments

  involved in the function invocation. For example, if your class has slots

  \c{myOverloadedSlot(int)} and \c{myOverloadedSlot(QString)}, the following

  script code will behave reasonably:

  \snippet doc/src/snippets/code/doc_src_qtscript.qdoc 11

  You can specify a particular overload by using array-style property access

  with the \l{QMetaObject::normalizedSignature()}{normalized signature} of

  the C++ function as the property name:

  \snippet doc/src/snippets/code/doc_src_qtscript.qdoc 12

  If the overloads have different number of arguments, QtScript will

  pick the overload with the argument count that best matches the

  actual number of arguments passed to the slot.

  For overloaded signals, Qt Script will throw an error if you try to connect

  to the signal by name; you have to refer to the signal with the full

  normalized signature of the particular overload you want to connect to.

  \section2 Accessing Properties

  The properties of the QObject are available as properties

  of the corresponding QtScript object. When you manipulate

  a property in script code, the C++ get/set method for that

  property will automatically be invoked. For example, if your

  C++ class has a property declared as follows:

  \snippet doc/src/snippets/code/doc_src_qtscript.qdoc 13

  then script code can do things like the following:

  \snippet doc/src/snippets/code/doc_src_qtscript.qdoc 14

  \section2 Accessing Child QObjects

  Every named child of the QObject (that is, for which

  QObject::objectName() is not an empty string) is by default available as

  a property of the QtScript wrapper object. For example,

  if you have a QDialog with a child widget whose \c{objectName} property is

  \c{"okButton"}, you can access this object in script code through

  the expression

  \snippet doc/src/snippets/code/doc_src_qtscript.qdoc 15

  Since \c{objectName} is itself a Q_PROPERTY, you can manipulate

  the name in script code to, for example, rename an object:

  \snippet doc/src/snippets/code/doc_src_qtscript.qdoc 16

  You can also use the functions \c{findChild()} and \c{findChildren()}

  to find children. These two functions behave identically to

  QObject::findChild() and QObject::findChildren(), respectively.

  For example, we can use these functions to find objects using strings

  and regular expressions:

  \snippet doc/src/snippets/code/doc_src_qtscript.qdoc 17

  You typically want to use \c{findChild()} when manipulating a form

  that uses nested layouts; that way the script is isolated from the

  details about which particular layout a widget is located in.

  \section2 Controlling QObject Ownership

  Qt Script uses garbage collection to reclaim memory used by script

  objects when they are no longer needed; an object's memory can be

  automatically reclaimed when it is no longer referenced anywhere in

  the scripting environment. Qt Script lets you control what happens

  to the underlying C++ QObject when the wrapper object is reclaimed

  (i.e., whether the QObject is deleted or not); you do this when you

  create an object by passing an ownership mode as the second argument

  to QScriptEngine::newQObject().

  Knowing how Qt Script deals with ownership is important, since it can

  help you avoid situations where a C++ object isn't deleted when it

  should be (causing memory leaks), or where a C++ object \e{is}

  deleted when it shouldn't be (typically causing a crash if C++ code

  later tries to access that object).

  \section3 Qt Ownership

  By default, the script engine does not take ownership of the

  QObject that is passed to QScriptEngine::newQObject(); the object

  is managed according to Qt's object ownership (see

  \l{Object Trees and Object Ownership}). This mode is appropriate

  when, for example, you are wrapping C++ objects that are part of

  your application's core; that is, they should persist regardless of

  what happens in the scripting environment. Another way of stating

  this is that the C++ objects should outlive the script engine.

  \section3 Script Ownership

  Specifying QScriptEngine::ScriptOwnership as the ownership mode

  will cause the script engine to take full ownership of the QObject

  and delete it when it determines that it is safe to do so

  (i.e., when there are no more references to it in script code).

  This ownership mode is appropriate if the QObject does not have a

  parent object, and/or the QObject is created in the context of the

  script engine and is not intended to outlive the script engine.

  For example, a constructor function that constructs QObjects

  only to be used in the script environment is a good candidate:

  \snippet doc/src/snippets/code/doc_src_qtscript.qdoc 18

  \section3 Auto-Ownership

  With QScriptEngine::AutoOwnership the ownership is based on whether

  the QObject has a parent or not.

  If the QtScript garbage collector finds that the QObject is no

  longer referenced within the script environment, the QObject will

  be deleted \e{only} if it does not have a parent.

  \section3 What Happens When Someone Else Deletes the QObject?

  It is possible that a wrapped QObject is deleted outside of

  Qt Script's control; i.e., without regard to the ownership mode

  specified. In this case, the wrapper object will still

  be an object (unlike the C++ pointer it wraps, the script object

  won't become null). Any attempt to access properties of the script

  object will, however, result in a script exception being thrown.

  Note that QScriptValue::isQObject() will still return true for a

  deleted QObject, since it tests the type of the script object, not

  whether the internal pointer is non-null. In other words, if

  QScriptValue::isQObject() returns true but QScriptValue::toQObject()

  returns a null pointer, this indicates that the QObject has been

  deleted outside of Qt Script (perhaps accidentally).

  \section2 Customizing Access to the QObject

  QScriptEngine::newQObject() can take a third argument which allows

  you to control various aspects of the access to the QObject through

  the QtScript wrapper object it returns.

  QScriptEngine::ExcludeChildObjects specifies that child objects of

  the QObject should not appear as properties of the wrapper object.

  QScriptEngine::ExcludeSuperClassProperties and

  QScriptEngine::ExcludeSuperClassMethods can be used to avoid

  exposing members that are inherited from the QObject's superclass.

  This is useful for defining a "pure" interface where inherited members

  don't make sense from a scripting perspective; e.g., you don't want

  script authors to be able to change the \c{objectName} property of

  the object or invoke the \c{deleteLater()} slot.

  QScriptEngine::AutoCreateDynamicProperties specifies that properties

  that don't already exist in the QObject should be created as dynamic

  properties of the QObject, rather than as properties of the QtScript

  wrapper object. If you want new properties to truly become persistent

  properties of the QObject, rather than properties that are destroyed

  along with the wrapper object (and that aren't shared if the QObject

  is wrapped multiple times with QScriptEngine::newQObject()), you

  should use this option.

  QScriptEngine::SkipMethodsInEnumeration specifies that signals and

  slots should be skipped when enumerating the properties of the QObject

  wrapper in a for-in script statement. This is useful when defining

  prototype objects, since by convention function properties of

  prototypes should not be enumerable.

  \section2 Making a QObject-based Class New-able from a Script

  The QScriptEngine::newQObject() function is used to wrap an

  existing QObject instance, so that it can be made available to

  scripts. A different scenario is that you want scripts to be

  able to construct new objects, not just access existing ones.

  The Qt meta-type system currently does not provide dynamic

  binding of constructors for QObject-based classes. If you want to

  make such a class new-able from scripts, Qt Script can generate

  a reasonable script constructor for you; see

  QScriptEngine::scriptValueFromQMetaObject().

  You can also use QScriptEngine::newFunction() to wrap your own

  factory function, and add it to the script environment; see

  QScriptEngine::newQMetaObject() for an example.

  \section2 Enum Values

  Values for enums declared with Q_ENUMS are not available as

  properties of individual wrapper objects; rather, they are

  properties of the QMetaObject wrapper object that can be created

  with QScriptEngine::newQMetaObject().

  \section1 Conversion Between QtScript and C++ Types

  QtScript will perform type conversion when a value needs to be

  converted from the script side to the C++ side or vice versa; for

  instance, when a C++ signal triggers a script function, when

  you access a QObject property in script code, or when

  you call QScriptEngine::toScriptValue() or

  QScriptEngine::fromScriptValue() in C++. QtScript provides default

  conversion operations for many of the built-in Qt types. You can

  change the conversion operation for a type (including your custom

  C++ types) by registering your own conversion functions with

  qScriptRegisterMetaType().

  \section2 Default Conversion from Qt Script to C++

  The following table describes the default conversion from a

  QScriptValue to a C++ type.

    \table 80%

    \header \o C++ Type \o Default Conversion

    \row    \o bool \o QScriptValue::toBool()

    \row    \o int \o QScriptValue::toInt32()

    \row    \o uint \o QScriptValue::toUInt32()

    \row    \o float \o float(QScriptValue::toNumber())

    \row    \o double \o QScriptValue::toNumber()

    \row    \o short \o short(QScriptValue::toInt32())

    \row    \o ushort \o QScriptValue::toUInt16()

    \row    \o char \o char(QScriptValue::toInt32())

    \row    \o uchar \o unsigned char(QScriptValue::toInt32())

    \row    \o qlonglong \o qlonglong(QScriptValue::toInteger())

    \row    \o qulonglong \o qulonglong(QScriptValue::toInteger())

    \row    \o QString \o An empty string if the QScriptValue is null

               or undefined; QScriptValue::toString() otherwise.

    \row    \o QDateTime \o QScriptValue::toDateTime()

    \row    \o QDate \o QScriptValue::toDateTime().date()

    \row    \o QRegExp \o QScriptValue::toRegExp()

    \row    \o QObject* \o QScriptValue::toQObject()

    \row    \o QWidget* \o QScriptValue::toQObject()

    \row    \o QVariant \o QScriptValue::toVariant()

    \row    \o QChar \o If the QScriptValue is a string, the result

               is the first character of the string, or a null QChar

               if the string is empty; otherwise, the result is a QChar

               constructed from the unicode obtained by converting the

               QScriptValue to a \c{ushort}.

    \row    \o QStringList \o If the QScriptValue is an array, the

               result is a QStringList constructed from the result of

               QScriptValue::toString() for each array element; otherwise,

               the result is an empty QStringList.

    \row    \o QVariantList \o If the QScriptValue is an array, the result

               is a QVariantList constructed from the result of

               QScriptValue::toVariant() for each array element; otherwise,

               the result is an empty QVariantList.

    \row    \o QVariantMap \o If the QScriptValue is an object, the result

               is a QVariantMap with a (key, value) pair of the form

               (propertyName, propertyValue.toVariant()) for each property,

               using QScriptValueIterator to iterate over the object's

               properties.

    \row    \o QObjectList \o If the QScriptValue is an array, the result

               is a QObjectList constructed from the result of

               QScriptValue::toQObject() for each array element; otherwise,

               the result is an empty QObjectList.

    \row    \o QList<int> \o If the QScriptValue is an array, the result is

               a QList<int> constructed from the result of

               QScriptValue::toInt32() for each array element; otherwise,