source: trunk/doc/src/scripting/scripting.qdoc@ 683

/****************************************************************************
**
** Copyright (C) 2010 Nokia Corporation and/or its subsidiary(-ies).
** All rights reserved.
** Contact: Nokia Corporation ([email protected])
**
** This file is part of the documentation of the Qt Toolkit.
**
** $QT_BEGIN_LICENSE:LGPL$
** Commercial Usage
** Licensees holding valid Qt Commercial licenses may use this file in
** accordance with the Qt Commercial License Agreement provided with the
** Software or, alternatively, in accordance with the terms contained in
** a written agreement between you and Nokia.
**
** 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.
**
** GNU General Public License Usage
** Alternatively, this file may be used under the terms of the GNU
** General Public License version 3.0 as published by the Free Software
** Foundation and appearing in the file LICENSE.GPL included in the
** packaging of this file.  Please review the following information to
** ensure the GNU General Public License version 3.0 requirements will be
** met: http://www.gnu.org/copyleft/gpl.html.
**
** If you have questions regarding the use of this file, please contact
** Nokia at [email protected].
** $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,
               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

  \section2 Default Conversion from C++ to Qt Script

  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 (including custom 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.

  \section3 Returning QObject Pointers

  If you have a slot that returns a QObject pointer, you should note
  that, by default, Qt Script only handles conversion of the types
  QObject* and QWidget*. This means that if your slot is declared
  with a signature like "MyObject* getMyObject()", QtScript doesn't
  automatically know that MyObject* should be handled in the same way
  as QObject* and QWidget*. The simplest way to solve this is to only
  use QObject* and QWidget* in the method signatures of your scripting
  interface.

  Alternatively, you can register conversion functions for your custom
  type with the qScriptRegisterMetaType() function. In this way, you
  can preserve the precise typing in your C++ declarations, while
  still allowing pointers to your custom objects to flow seamlessly
  between C++ and scripts. Example:

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

  \section1 Function Objects and Native Functions

  In Qt Script, functions are first-class values; they are objects that