|Home | Tutorial | Classes | Functions | QSA Workbench | Language | Qt API | QSA Articles | Qt Script for Applications | ![]() |
The QSInterpreter class provides the public API for the Qt Script for Applications script engine. More...
#include <qsinterpreter.h>
The QSInterpreter class provides the public API for the Qt Script for Applications script engine.
This class (implemented in libqsa) provides the functionality required to make Qt/C++ applications scriptable with Qt Script.
For convenience a single instance of the QSInterpreter class exists in an application; it is available as QSInterpreter::defaultInterpreter().
The functions evaluate(), call(), addTransientObject(), and clear() provide the basic functionality of the interpreter. Any string containing valid Qt Script code can be executed using evaluate(), and any state built up during evaluation is kept between calls. The function call() can be used to call script functions from C++. The function addTransientObject() will add an object to the interpreter until the interpreter is cleared. Calling clear() will clear the state of the interpreter and remove all transient objects.
The function checkSyntax() provides syntax checking without having to execute the context of the code.
QSInterpreter provides several functions for script introspection. These functions are: classes(), functions(), and variables().
If an error occurs, for example, during the execution of a script, the error() signal is emitted. The error behavior depends on the errorMode() which is set with setErrorMode(). When the interpreter stops execution because of an error, the hadError(), errorMessage(), and stackTrace() functions can be used to provide error information.
It is possible to run QSInterpreter in a separate thread when compiling against Qt 3.3 or later. This allows you to have multiple interpreters running simultaneously. Interpreters can interact with QObjects in the same thread they are running. Note that normal restrictions for threading in Qt still apply, such as interacting with objects on other threads and the GUI thread.
When an object has been made accessible to the interpreter, such as through the functions addTransientObject() or evaluate() all its signals, slots and properties will be made accessible from script. QSA provides a series of automatic conversions between C++ types and Qt Script types. These are listed below.
The following table describes which script types are supported as function arguments when calling a C++ slot from QSA.
C++ Type | Qt Script Type |
QByteArray | ByteArray |
QByteArray* | ByteArray, undefined |
QColor | Color |
QColor* | Color, undefined |
QColorGroup | ColorGroup |
QColorGroup* | ColorGroup, undefined |
QFont | Font |
QFont* | Font, undefined |
QObject* | QObject, undefiend |
QObjectList | Array (of QObjects) |
QObjectList* | Array (of QObjects), undefined |
QPalette | Palette |
QPalette* | Palette, undefined |
QPixmap | Pixmap |
QPixmap | Pixmap, undefined |
QPoint | Point |
QPoint* | Point, undefined |
QRect | Rect |
QRect* | Rect, undefined |
QSize | Size |
QSize* | Size, undefined |
QString | String, Number, undefined |
QString* | String, Number, undefined |
QStringList | String, Array |
QStringList* | String, Array, undefined |
QValueList<int> | Array |
QValueList<int>* | Array |
QVariant | All types except QObject* and wrapped pointer. |
QVariant* | All types except QObject* and wrapped pointer. |
bool | Boolean, Number (0 is FALSE), String ("", "0" and "false" is false) |
char | Number, String (first character), undefined |
char* | String, undefined |
double | Number, Boolean, undefined |
float | Number, Boolean, undefined |
int | Number, Boolean, undefined |
long | Number, Boolean, undefined |
void* | Wrapped pointer, undefined |
short | Number, Boolean, undefined |
uchar | Number, String (first character), undefined |
uint | Number, Boolean, undefined |
ulong | Number, Boolean, undefined |
ushort | Number, Boolean, undefined |
The following table describes which C++ types are converted to Qt Script types when used as properties or used as return values from slots.
C++ Type | Qt Script Type |
QObject* | QObject |
QString | String |
QStringList | Array |
QVariant | Variant or matching type (Font, Color, etc) |
bool | Boolean |
double | Number |
int | Number |
uint | Number |
void* | Wrapped pointer |
Note that
See the Manual for more explanations and examples.
The ClassFlags enum specifies which classes should be made available for introspection.
The ErrorMode enum describes what happens when an error occurs while parsing or executing script code.
The FunctionFlags enum describes matching rules and formatting for function introspection.
The parent and name parameters are passed on to the QObject base class.
There's a default instance accessible with QSInterpreter::defaultInterpreter().
Using this function will clear the state of the interpreter, and will clear any transient objects.
Transient objects added to the interpreter are not persistent. This means that when the interpreter is cleared, or when a project is re-evaluated, the transient objects are removed.
Use QSProject::addObject() to add persistent objects to the interpreter.
Note on threading; If the interpreter is running in the non-GUI thread, object cannot be a QWidget subclass.
Warning: Every object passed to this function must have a unique name. If you want to reuse names then you need to call clear() first
See also QSProject::addObject().
Example:
interpreter->addTransientSignalHandler( myButton, SIGNAL( clicked() ), "classA.obj.calculate" );
See also removeTransientSignalHandler().
The variable will persist until the interpreter is cleared. It is for that reason not wise to use this function on an interpreter that belongs to a QSProject
See also QSProject and addTransientObject().
Using this function will clear the state of the interpreter, and will clear any transient objects.
Functions which were passed to evaluate() in previous calls or which are defined in the current project, can be called from this function.
If context is 0 (the default), the function is called in the global scope. If a context is given, the function is called in the scope of that object.
Interpreters that belong to a project are subject to re-evaluation, since the code which has been passed previously into evaluate() gets lost when calling one of these functions. This happens when the project or the scripts in it are modified.
If flags is AllClasses (the default), all the classes in the interpreter are returned, including those declared in object contexts. If flags is GlobalClasses, only those classes declared in the global context are returned.
See also functions() and variables().
See also functions() and variables().
See also functions() and variables().
When the interpreter is cleared, all declarations parsed using the function QSInterpreter::evaluate() are removed. The state of all variables will also be cleared.
Clearing the interpreter will also remove any transient objects. Transient objects are those added with the function QSInterpreter::addTransientObject() or by evaluating code in the context of a QObject using QSInterpreter::evaluate();
This function does not clear persistent application objects added by the function QSProject::addObject().
The default interpreter runs without a project.
This function will automatically create the interpreter if it doesn't already exist.
This signal is emitted if an error occurs when running or parsing a script. message contains the error message from the interpreter, scriptName contains the script name (if known) in which the error occurred, and lineNumber contains the line number at which the error occurred.
This signal is emitted if an error occurs when running or parsing a script. message contains the error message from the interpreter, context is a pointer to the QObject context in which the error occurred or 0, if the context is the global context, scriptName contains the script name (if known) in which the error occurred, and lineNumber contains the line number at which the error occurred.
Returns what happens when there is an error:. See the "errorMode" property for details.
This function executes the code passed in as code. The code can use and reference code (functions, classes, variables, etc.) which have been passed to this function previously or which are defined in the current project, if present. Also, application objects which have been added via addObject() can be accessed.
If context is 0 (the default), the code is executed as global code. If a context is given, the code is executed in the context of that object.
Interpreters that belong to a project are subject to re-evaluation, since the code which has been passed previously into evaluate() gets lost when calling one of these functions. This happens when the project or the scripts in it are modified.
scriptName is used for error reporting and debugging.
If flags includes FunctionSignatures, then each function name returned will be of the following form:
functionName( typeOfArg1, typeOfArg2, ... )Otherwise just the names will be returned (which is the default).
See also classes() and variables().
context can be fully qualified.
If flags includes FunctionSignatures, then each function name returned will be of the following form:
functionName( typeOfArg1, typeOfArg2, ... )Otherwise just the names will be returned (which is the default).
If flags includes IncludeMemberFunctions and context represents a class declared in script, this function will return both static and non-static functions; otherwise it only returns static functions.
See also classes() and variables().
If flags includes FunctionSignatures, then each function name returned will be of the following form:
functionName( typeOfArg1, typeOfArg2, ... )Otherwise just the names will be returned (which is the default).
See also classes() and variables().
The class name can be a fully qualified in the form:
myclass.innerClass
The function can be a fully qualified in the form:
myclass.function
The variable name can be fully qualified in the form:
myobject.otherobject.var
See also addTransientSignalHandler().
Sets what happens when there is an error: to m. See the "errorMode" property for details.
Sets describes the number of milliseconds between each time the timeout() signal will be emitted by the interpreter to msecs. See the "timeoutInterval" property for details.
This signal is emitted on intervals specified by timeoutInterval
The elapsedTime parameter describes the number of milliseconds the interpreter has been running.
Returns describes the number of milliseconds between each time the timeout() signal will be emitted by the interpreter. See the "timeoutInterval" property for details.
a.b.c
See also functions() and classes().
See also functions() and classes().
See also functions() and classes().
This property holds what happens when there is an error:.
Set this property's value with setErrorMode() and get this property's value with errorMode().
This property holds describes the number of milliseconds between each time the timeout() signal will be emitted by the interpreter.
The timeout can be used to perform monitoring of the interpreter, such as forcing it to terminate if it has not terminated after 10 seconds. A negative value, the default, will turn off the timeout() signal.
See also timeout().
Set this property's value with setTimeoutInterval() and get this property's value with timeoutInterval().
This file is part of Qt Script for Applications, copyright © 2001-2004 Trolltech. All Rights Reserved.
Copyright © 2001-2006 Trolltech | Trademarks | QSA version 1.1.5
|