/****************************************************************************
**
** Copyright (C) 2007-2008 Trolltech ASA. All rights reserved.
**
** This file is part of the documentation of the Qt Toolkit.
**
** This file may be used under the terms of the GNU General Public
** License versions 2.0 or 3.0 as published by the Free Software
** Foundation and appearing in the files LICENSE.GPL2 and LICENSE.GPL3
** included in the packaging of this file.  Alternatively you may (at
** your option) use any later version of the GNU General Public
** License if such license has been publicly approved by Trolltech ASA
** (or its successors, if any) and the KDE Free Qt Foundation. In
** addition, as a special exception, Trolltech gives you certain
** additional rights. These rights are described in the Trolltech GPL
** Exception version 1.2, which can be found at
** http://www.trolltech.com/products/qt/gplexception/ and in the file
** GPL_EXCEPTION.txt in this package.
**
** Please review the following information to ensure GNU General
** Public Licensing requirements will be met:
** http://trolltech.com/products/qt/licenses/licensing/opensource/. If
** you are unsure which license is appropriate for your use, please
** review the following information:
** http://trolltech.com/products/qt/licenses/licensing/licensingoverview
** or contact the sales department at sales@trolltech.com.
**
** In addition, as a special exception, Trolltech, as the sole
** copyright holder for Qt Designer, grants users of the Qt/Eclipse
** Integration plug-in the right for the Qt/Eclipse Integration to
** link to functionality provided by Qt Designer and its related
** libraries.
**
** This file is provided "AS IS" with NO WARRANTY OF ANY KIND,
** INCLUDING THE WARRANTIES OF DESIGN, MERCHANTABILITY AND FITNESS FOR
** A PARTICULAR PURPOSE. Trolltech reserves all rights not expressly
** granted herein.
**
** This file is provided AS IS with NO WARRANTY OF ANY KIND, INCLUDING THE
** WARRANTY OF DESIGN, MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE.
**
****************************************************************************/

/*!
  \module QtScript
  \since 4.3
  \title QtScript Module
  \contentspage Qt's Modules
  \previouspage QtOpenGL
  \nextpage QtSql
  \ingroup modules
  \ingroup scripting

  \brief The QtScript module provides classes for making Qt applications scriptable.

  \tableofcontents

  \section1 Configuring the Build Process

  Applications that use Qt's Script classes need to
  be configured to be built against the QtScript module.
  To include the definitions of the module's classes, use the
  following directive:

  \snippet doc/src/snippets/code/doc.src.qtscript.qdoc 0

  To link against the module, add this line to your \l qmake \c .pro file:

  \snippet doc/src/snippets/code/doc.src.qtscript.qdoc 1

  The QtScript module is part of the \l{Qt Desktop Edition} and the
  \l{Qt Open Source Edition}.

  \section1 Language Overview

  QtScript 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 \bold{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 subclass can be made available for use with scripts.

  When a QObject is passed to the QScriptEngine::newQObject() function,
  a QtScript wrapper object is created that can be used to make the
  QObject's signals, slots, properties, and child objects available
  to scripts. Because QtScript uses Qt's meta-object system, there
  is no need to implement any additional wrappers or bindings.

  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

  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

  In C++, you can use the qScriptConnect() function to connect a C++
  signal to a script function.

  In script code, Qt Script uses a different syntax for connecting to
  and disconnecting from signals than what you're familiar with from
  C++ (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 QtScript 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
  `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

  \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, QtScript will connect to the most general
  overload, unless you refer to the signal with its full normalized
  signature.

  \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 is by default available as
  a property of the corresponding QtScript object. For example,
  if you have a QDialog with a child widget whose \c{objectName()} 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

  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}). You can change this
  behavior by specifying a different ownership mode as the
  second argument, overriding the default (QScriptEngine::QtOwnership).

  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.
  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

  Another ownership mode is QScriptEngine::AutoOwnership, where
  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 \bold{only} if it does not have a parent.

  \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 newQObject()), you should use this
  option.

  \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 by registering your own
  conversion functions with qScriptRegisterMetaType().

  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::toBoolean()
    \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 QScriptValue::toString()
    \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,
               the result is an empty QList<int>.
    \endtable

  Additionally, QtScript will handle the following cases:

  \list
  \i If the QScriptValue is a QObject and the target type name ends with
     \c * (i.e., it is a pointer), the QObject pointer will be cast to the
     target type with qobject_cast().
  \i If the QScriptValue is a QVariant and the target type name ends with
     \c * (i.e., it is a pointer), and the \l{QVariant::userType()}{userType()}
     of the QVariant is the type that the target type points to, the result
     is a pointer to the QVariant's data.
  \i If the QScriptValue is a QVariant and it can be converted to the
     target type (according to QVariant::canConvert()), the QVariant will
     be cast to the target type with qvariant_cast().
  \endlist

  The following table describes the default behavior when a QScriptValue is
  constructed from a C++ type:

    \table 80%
    \header \o C++ Type \o Default Construction
    \row    \o void \o QScriptEngine::undefinedValue()
    \row    \o bool \o QScriptValue(engine, value)
    \row    \o int \o QScriptValue(engine, value)
    \row    \o uint \o QScriptValue(engine, value)
    \row    \o float \o QScriptValue(engine, value)
    \row    \o double \o QScriptValue(engine, value)
    \row    \o short \o QScriptValue(engine, value)
    \row    \o ushort \o QScriptValue(engine, value)
    \row    \o char \o QScriptValue(engine, value)
    \row    \o uchar \o QScriptValue(engine, value)
    \row    \o QString \o QScriptValue(engine, value)
    \row    \o qlonglong \o QScriptValue(engine, qsreal(value)). Note that
               the conversion may lead to loss of precision, since not all
               64-bit integers can be represented using the qsreal type.
    \row    \o qulonglong \o QScriptValue(engine, qsreal(value)). Note that
               the conversion may lead to loss of precision, since not all
               64-bit unsigned integers can be represented using the qsreal
               type.
    \row    \o QChar \o QScriptValue(this, value.unicode())
    \row    \o QDateTime \o \l{QScriptEngine::newDate()}{QScriptEngine::newDate}(value)
    \row    \o QDate \o \l{QScriptEngine::newDate()}{QScriptEngine::newDate}(value)
    \row    \o QRegExp \o \l{QScriptEngine::newRegExp()}{QScriptEngine::newRegExp}(value)
    \row    \o QObject* \o \l{QScriptEngine::newQObject()}{QScriptEngine::newQObject}(value)
    \row    \o QWidget* \o \l{QScriptEngine::newQObject()}{QScriptEngine::newQObject}(value)
    \row    \o QVariant \o \l{QScriptEngine::newVariant()}{QScriptEngine::newVariant}(value)
    \row    \o QStringList \o A new script array (created with
               QScriptEngine::newArray()), whose elements are created using
               the QScriptValue(QScriptEngine *, QString) constructor for
               each element of the list.
    \row    \o QVariantList \o A new script array (created with
               QScriptEngine::newArray()), whose elements are created using
               QScriptEngine::newVariant() for each element of the list.
    \row    \o QVariantMap \o A new script object (created with
               QScriptEngine::newObject()), whose properties are initialized
               according to the (key, value) pairs of the map.
    \row    \o QObjectList \o A new script array (created with
               QScriptEngine::newArray()), whose elements are created using
               QScriptEngine::newQObject() for each element of the list.
    \row    \o QList<int> \o A new script array (created with
               QScriptEngine::newArray()), whose elements are created using
               the QScriptValue(QScriptEngine *, int) constructor for each
               element of the list.
    \endtable

  Other types will be wrapped using QScriptEngine::newVariant(). For null
  pointers of any type, the result is QScriptEngine::nullValue().

  \section1 How to Design and Implement Application Objects

  This section explains how to implement application objects and
  provides the necessary technical background material.

  \section2 Making a C++ object available to Scripts Written in QtScript

  Making C++ classes and objects available to a scripting language is
  not trivial because scripting languages tend to be more dynamic than
  C++, and it must be possible to introspect objects (query information
  such as function names, function signatures, properties, etc., at
  run-time). Standard C++ does not provide features for this.

  We can achieve the functionality we want by extending C++, using
  C++'s own facilities so our code is still standard C++. The Qt
  meta-object system provides the necessary additional functionality.
  It allows us to write using an extended C++ syntax, but converts this
  into standard C++ using a small utility program called \l{moc}
  (Meta-Object Compiler). Classes that wish to take advantage of the
  meta-object facilities are either subclasses of QObject, or use the
  \c{Q_OBJECT} macro. Qt has used this approach for many years and it has
  proven to be solid and reliable. QtScript uses this meta-object
  technology to provide scripters with dynamic access to C++ classes
  and objects.

  To completely understand how to make C++ objects available to Qt
  Script, some basic knowledge of the Qt meta-object system is very
  helpful. We recommend that you read the \l{Qt Object Model}. The
  information in this document and the documents it links to are very
  useful for understanding how to implement application objects.

  However, this knowledge is not essential in the simplest cases.
  To make an object available in QtScript, it must derive from
  QObject. All classes which derive from QObject can be introspected
  and can provide the information needed by the scripting engine at
  run-time; e.g., class name, functions, signatures. Because we obtain
  the information we need about classes dynamically at run-time, there
  is no need to write wrappers for QObject derived classes.

  \section2 Making C++ Class Member Functions Available in QtScript

  The meta-object system also makes information about signals and slots
  dynamically available at run-time. By default, for QObject subclasses,
  only the signals and slots are automatically made available to scripts.
  This is very convenient because, in practice, we normally only want to
  make specially chosen functions available to scripters. When you create
  a QObject subclass, make sure that the functions you want to expose to
  QtScript are public slots.

  For example, the following class definition enables scripting only for
  certain functions:

    \snippet doc/src/snippets/code/doc.src.qtscript.qdoc 19

  In the example above, aNonScriptableFunction() is not declared as a
  slot, so it will not be available in QtScript. The other three
  functions will automatically be made available in QtScript because
  they are declared in the \c{public slots} section of the class
  definition.

  It is possible to make any function script-invokable by specifying
  the \c{Q_INVOKABLE} modifier when declaring the function:

  \snippet doc/src/snippets/code/doc.src.qtscript.qdoc 20

  Once declared with \c{Q_INVOKABLE}, the method can be invoked from
  QtScript code just as if it were a slot. Although such a method is
  not a slot, you can still specify it as the target function in a
  call to \c{connect()} in script code; \c{connect()} accepts both
  native and non-native functions as targets.

  \section2 Making C++ Class Properties Available in QtScript

  In the previous example, if we wanted to get or set a property using
  QtScript we would have to write code like the following:

    \snippet doc/src/snippets/code/doc.src.qtscript.qdoc 21

  Scripting languages often provide a property syntax to modify and
  retrieve properties (in our case the enabled state) of an
  object. Many script programmers would want to write the above code
  like this:

    \snippet doc/src/snippets/code/doc.src.qtscript.qdoc 22

  To make this possible, you must define properties in the C++ QObject
  subclass. For example, the following \c MyObject class declaration
  declares a boolean property called \c enabled, which uses the function
  \c{setEnabled(bool)} as its setter function and \c{isEnabled()} as its
  getter function:

    \snippet doc/src/snippets/code/doc.src.qtscript.qdoc 23

  The only difference from the original code is the use of the macro
  \c{Q_PROPERTY}, which takes the type and name of the property, and
  the names of the setter and getter functions as arguments.

  If you don't want a property of your class to be accessible in
  QtScript, you set the \c{SCRIPTABLE} attribute to \c false when
  declaring the property; by default, the \c{SCRIPTABLE} attribute is
  \c true. For example:

  \snippet doc/src/snippets/code/doc.src.qtscript.qdoc 24

  \section2 Reacting to C++ Objects Signals in Scripts

  In the Qt object model, signals are used as a notification mechanism
  between QObjects. This means one object can connect a signal to
  another object's slot and, every time the signal is emitted, the slot
  is called. This connection is established using the QObject::connect()
  function.

  The signals and slots mechanism is also available to QtScript
  programmers. The code to declare a signal in C++ is the same,
  regardless of whether the signal will be connected to a slot in C++
  or in QtScript.

    \snippet doc/src/snippets/code/doc.src.qtscript.qdoc 25

  The only change we have made to the code in the previous section is
  to declare a signals section with the relevant signal. Now, the
  script writer can define a function and connect to the object like
  this:

    \snippet doc/src/snippets/code/doc.src.qtscript.qdoc 26

  \section2 Design of Application Objects

  The previous section described how to implement C++ objects which
  can be used in QtScript. Application objects are the same kind of
  objects, and they make your application's functionality available to
  QtScript scripters.  Since the C++ application is already written
  in Qt, many objects are already QObjects. The easiest approach would
  be to simply add all these QObjects as application objects to the
  scripting engine. For small applications this might be sufficient,
  but for larger applications this is probably not the right
  approach. The problem is that this method reveals too much of the
  internal API and gives script programmers access to application
  internals which should not be exposed.

  Generally, the best way of making application functionality available
  to scripters is to code some QObjects which define the applications
  public API using signals, slots, and properties. This gives you
  complete control of the functionality made available by the
  application. The implementations of these objects simply call the
  functions in the application which do the real work. So, instead of
  making all your QObjects available to the scripting engine, just add
  the wrapper QObjects.

  \section1 Making Use of Prototype-Based Inheritance

  In ECMAScript, inheritance is based on the concept of \bold{shared
  prototype objects}; this is quite different from the class-based
  inheritance familiar to C++ programmers. With QtScript, you can
  associate a custom prototype object with a C++ type using
  QScriptEngine::setDefaultPrototype(); this is the key to providing
  a script interface to that type. Since the QtScript module is built
  on top of Qt's meta-type system, this can be done for any C++ type.
  This section explains the underlying concepts of prototype-based
  inheritance. Once these concepts are understood, the associated
  practices can be applied throughout the QtScript API in order to
  create well-behaved, consistent bindings to C++ that will fit nicely
  into the ECMAScript universe.

  When experimenting with QtScript objects and inheritance, it can be
  helpful to use the interactive interpreter included with the QtScript
  examples, located in \c{examples/script/qscript}.

  \section2 Prototype Objects and Shared Properties

  The purpose of a QtScript \bold{prototype object} is to define
  behavior that should be shared by a set of other QtScript
  objects. We say that objects which share the same prototype object
  belong to the same \e{class} (again, on the technical side this
  should not to be confused with the class constructs of languages
  like C++ and Java; ECMAScript has no such construct).

  The basic prototype-based inheritance mechanism works as follows: Each
  QtScript object has an internal link to another object, its
  \e{prototype}. When a property is looked up in an object, and the
  object itself does not have the property, the property is looked up
  in the prototype object instead; if the prototype has the property,
  then that property is returned. Otherwise, the property is looked up
  in the prototype of the prototype object, and so on; this chain of
  objects constitutes a \bold{prototype chain}. The chain of prototype
  objects is followed until the property is found or the end of the
  chain is reached.

  For example, when you create a new object by the expression \c{new
  Object()}, the resulting object will have as its prototype the
  standard \c{Object} prototype, \c{Object.prototype}; through this
  prototype relation, the new object inherits a set of properties,
  including the \c{hasOwnProperty()} function and \c{toString()}
  function:

  \snippet doc/src/snippets/code/doc.src.qtscript.qdoc 27

  The \c{toString()} function itself is not defined in \c{o} (since we
  did not assign anything to \c{o.toString}), so instead the
  \c{toString()} function in the standard \c{Object} prototype is
  called, which returns a highly generic string representation of
  \c{o} ("[object Object]").

  Note that the properties of the prototype object are not \e{copied} to
  the new object; only a \e{link} from the new object to the prototype
  object is maintained. This means that changes done to the prototype
  object will immediately be reflected in the behavior of all objects
  that have the modified object as their prototype.

  \section2 Defining Classes in a Prototype-Based Universe

  In QtScript, a class is not defined explicitly; there is no
  \c{class} keyword. Instead, you define a new class in two steps:

  \list 1
  \i Define a \bold{constructor function} that will initialize new objects.
  \i Set up a \bold{prototype object} that defines the class interface, and
     assign this object to the public \c{prototype} property of the
     constructor function.
  \endlist

  With this arrangement, the constructor's public \c{prototype}
  property will automatically be set as the prototype of objects created
  by applying the \c{new} operator to your constructor function;
  e.g., the prototype of an object created by \c{new Foo()} will be the
  value of \c{Foo.prototype}.

  Functions that don't operate on the \c this object ("static" methods)
  are typically stored as properties of the constructor function, not
  as properties of the prototype object. The same is true for
  constants, such as enum values.

  The following code defines a simple constructor function for a class
  called \c{Person}:

  \snippet doc/src/snippets/code/doc.src.qtscript.qdoc 28

  Next, you want to set up \c{Person.prototype} as your prototype
  object; i.e., define the interface that should be common to all
  \c{Person} objects. QtScript automatically creates a default
  prototype object (by the expression \c{new Object()}) for every
  script function; you can add properties to this object, or you can
  assign your own custom object. (Generally speaking, any QtScript
  object can act as prototype for any other object.)

  Here's an example of how you might want to override the
  \c{toString()} function that \c{Person.prototype} inherits from
  \c{Object.prototype}, to give your \c{Person} objects a more
  appropriate string representation:

  \snippet doc/src/snippets/code/doc.src.qtscript.qdoc 29

  This resembles the process of reimplementing a virtual function
  in C++. Henceforth, when the property named \c{toString} is
  looked up in a \c{Person} object, it will be resolved in
  \c{Person.prototype}, not in \c{Object.prototype} as before:

  \snippet doc/src/snippets/code/doc.src.qtscript.qdoc 30

  There are also some other interesting things we can learn about a
  \c{Person} object:

  \snippet doc/src/snippets/code/doc.src.qtscript.qdoc 31

  The \c{hasOwnProperty()} function is not inherited from
  \c{Person.prototype}, but rather from \c{Object.prototype}, which is
  the prototype of \c{Person.prototype} itself; i.e., the prototype
  chain of \c{Person} objects is \c{Person.prototype} followed by
  \c{Object.prototype}. This prototype chain establishes a \e{class
  hierarchy}, as demonstrated by applying the \c{instanceof} operator;
  \c{instanceof} checks if the value of the public \c{prototype}
  property of the constructor function on the right-hand side is
  reached by following the prototype chain of the object on the
  left-hand side.

  When defining subclasses, there's a general pattern you can use. The
  following example shows how one can create a subclass of \c{Person}
  called \c{Employee}:

  \snippet doc/src/snippets/code/doc.src.qtscript.qdoc 32

  Again, you can use the \c{instanceof} to verify that the
  class relationship between \c{Employee} and \c{Person} has been
  correctly established:

  \snippet doc/src/snippets/code/doc.src.qtscript.qdoc 33

  This shows that the prototype chain of \c{Employee} objects is the
  same as that of \c{Person} objects, but with \c{Employee.prototype}
  added to the front of the chain.

  \section2 Prototype-Based Programming with the QtScript C++ API

  You can use QScriptEngine::newFunction() to wrap
  native functions. When implementing a constructor function,
  you also pass the prototype object as an argument to
  QScriptEngine::newFunction().
  You can call QScriptValue::construct() to call a constructor
  function, and you can use QScriptValue::call() from within a
  native constructor function if you need to call a base class
  constructor.

  The QScriptable class provides a convenient way to implement a
  prototype object in terms of C++ slots and properties. Take a look
  at the \l{Default Prototypes Example} to see how this is done.
  Alternatively, the prototype functionality can be implemented in
  terms of standalone native functions that you wrap with
  QScriptEngine::newFunction() and set as properties of your prototype
  object by calling QScriptValue::setProperty().

  In the implementation of your prototype functions, you use
  QScriptable::thisObject() (or QScriptContext::thisObject()) to
  obtain a reference to the QScriptValue being operated upon; then you
  call qscriptvalue_cast() to cast it to your C++ type, and perform
  the relevant operations using the usual C++ API for the type.

  You associate a prototype object with a C++ type by calling
  QScriptEngine::setDefaultPrototype(). Once this mapping is
  established, QtScript will automatically assign the correct
  prototype when a value of such a type is wrapped in a QScriptValue;
  either when you explicitly call QScriptEngine::toScriptValue(), or
  when a value of such a type is returned from a C++ slot and
  internally passed back to script code by the engine. This means you
  \e{don't} have to implement wrapper classes if you use this
  approach.

  As an example, let's consider how the \c{Person} class from the
  preceding section can be implemented in terms of the Qt Script API.
  We begin with the native constructor function:

  \snippet doc/src/snippets/code/doc.src.qtscript.qdoc 34

  Here's the native equivalent of the \c{Person.prototype.toString}
  function we saw before:

  \snippet doc/src/snippets/code/doc.src.qtscript.qdoc 35

  The \c{Person} class can then be initialized as follows:

  \snippet doc/src/snippets/code/doc.src.qtscript.qdoc 36

  The implementation of the \c{Employee} subclass is similar. We
  use QScriptValue::call() to call the super-class (Person) constructor:

  \snippet doc/src/snippets/code/doc.src.qtscript.qdoc 37

  The \c{Employee} class can then be initialized as follows:

  \snippet doc/src/snippets/code/doc.src.qtscript.qdoc 38

  When implementing the prototype object of a class, you may want to use
  the QScriptable class, as it enables you to define the API of your
  script class in terms of Qt properties, signals and slots, and
  automatically handles value conversion between the Qt Script and C++
  side.

  \section2 Implementing Prototype Objects for Value-based Types

  When implementing a prototype object for a value-based type --
  e.g. QPointF -- the same general technique applies. When values of
  the custom type are stored in QVariants -- which Qt Script does by
  default --, qscriptvalue_cast() enables you to safely cast the
  script value to a pointer to the C++ type. This makes it easy to do
  type-checking, and, for prototype functions that should modify the
  underlying C++ value, lets you modify the actual value contained in
  the script value (and not a copy of it).

  \snippet doc/src/snippets/code/doc.src.qtscript.qdoc 39

  \section1 ECMAScript Compatibility

  QtScript implements all the built-in classes and functions defined
  in ECMA-262.

  The Date parsing and string conversion functions are implemented using
  QDateTime::fromString() and QDateTime::toString(), respectively.

  The RegExp class is a wrapper around QRegExp. The QRegExp semantics
  do not precisely match the semantics for regular expressions defined
  in ECMA-262.

  \section1 QtScript Extensions to ECMAScript

  \list
  \i \c{__proto__} \br
    The prototype of an object (QScriptValue::prototype())
    can be accessed through its \c{__proto__} property in script code.
    This property has the QScriptValue::Undeletable flag set.
    For example:

  \snippet doc/src/snippets/code/doc.src.qtscript.qdoc 40

  \i \c{Object.prototype.__defineGetter__} \br
    This function installs a
    getter function for a property of an object. The first argument is
    the property name, and the second is the function to call to get
    the value of that property. When the function is invoked, the
    \c this object will be the object whose property is accessed.
    For example:

  \snippet doc/src/snippets/code/doc.src.qtscript.qdoc 41

  \i \c{Object.prototype.__defineSetter__} \br
    This function installs a
    setter function for a property of an object. The first argument is
    the property name, and the second is the function to call to set
    the value of that property.  When the function is invoked, the
    \c this object will be the object whose property is accessed.
    For example:

  \snippet doc/src/snippets/code/doc.src.qtscript.qdoc 42

  \i \c{Function.prototype.connect} \br
    This function connects
    a signal to a slot. Usage of this function is described in
    the section \l{Using Signals and Slots}.

  \i \c{Function.prototype.disconnect} \br
    This function disconnects
    a signal from a slot. Usage of this function is described in
    the section \l{Using Signals and Slots}.

  \i \c{QObject.prototype.findChild} \br
    This function is semantically equivalent to QObject::findChild().

  \i \c{QObject.prototype.findChildren} \br
    This function is semantically equivalent to QObject::findChildren().

  \i \c{QObject.prototype.toString} \br
    This function returns a default string representation of a QObject.

  \i \c{gc} \br
    This function invokes the garbage collector.

  \i \c{Error.prototype.backtrace} \br
    This function returns a human-readable backtrace, in the form of
    an array of strings.

  \i Error objects have the following additional properties:
    \list
    \i \c{lineNumber}: The line number where the error occurred.
    \i \c{fileName}: The file name where the error occurred (if a file name
    was passed to QScriptEngine::evaluate()).
    \i \c{stack}: An array of objects describing the stack. Each object has
      the following properties:
      \list
      \i \c{functionName}: The function name, if available.
      \i \c{fileName}: The file name, if available.
      \i \c{lineNumber}: The line number, if available.
      \endlist
    \endlist

  \endlist

 */
