Qt Script for Applications · Home · Tutorial · Classes · Functions · Language · QSA Workbench · Qt Documentation · www.trolltech.com

# QSInterpreter Class Reference

The QSInterpreter class provides the public API for the Qt Script for Applications script engine. More...

    #include <QSInterpreter>

- List of all members, including inherited members

### Public Types

- enum ClassFlags { AllClasses, GlobalClasses }
- enum ErrorMode { Notify, Nothing }
- enum FunctionFlags { FunctionNames, FunctionSignatures, IncludeMemberFunctions }

### Public Functions

- QSInterpreter ( QObject * parent = 0, const char * name = 0 )
- void addObjectFactory ( QSObjectFactory * factory )
- void addTransientObject ( QObject * object )
- void addTransientSignalHandler ( QObject * sender, const char * signal, const char * qtscriptFunction )
- void addTransientVariable ( const QString & variableName, const QVariant & arg, QObject * context = 0 )
- void addWrapperFactory ( QSWrapperFactory * factory )
- QVariant call ( const QString & function, const QVariantList & arguments = QVariantList(), QObject * context = 0 )
- bool checkSyntax ( const QString & code )
- QStringList classes ( ClassFlags flags = AllClasses ) const
- QStringList classes ( const QString & context ) const
- QStringList classes ( QObject * context ) const
- QObject * currentContext () const
- QString errorMessage () const
- ErrorMode errorMode () const
- QVariant evaluate ( const QString & code, QObject * context = 0, const QString & scriptName = QString::null )
- QStringList functions ( FunctionFlags flags = FunctionNames ) const
- QStringList functions ( const QString & context, uint flags = FunctionNames ) const
- QStringList functions ( QObject * context, FunctionFlags flags = FunctionNames ) const
- bool hadError () const
- bool hasClass ( const QString & className ) const
- bool hasFunction ( const QString & function ) const
- bool hasVariable ( const QString & variable ) const
- bool isRunning () const
- QObjectList presentObjects () const
- QSProject * project () const
- void removeTransientSignalHandler ( QObject * sender, const char * signal, const char * qtscriptFunction )
- void setErrorMode ( ErrorMode m )
- void setTimeoutInterval ( int msecs )
- QSStackTrace stackTrace () const
- QString stackTraceString () const
- void throwError ( const QString & message )
- int timeoutInterval () const
- QVariant variable ( const QString & variableName, QObject * context = 0 ) const
- QStringList variables () const
- QStringList variables ( const QString & context ) const
- QStringList variables ( QObject * context ) const

### Public Slots

- void clear ()
- void stopExecution ()

### Signals

- void error ( const QString & message, const QString & scriptName, int lineNumber )
- void error ( const QString & message, QObject * context, const QString & scriptName, int lineNumber )
- void timeout ( int elapsedTime )

### Static Public Members

- QSInterpreter * defaultInterpreter ()
- void registerMetaObject ( const QMetaObject * metaObject )

## Detailed Description

The QSInterpreter class provides the public API for the Qt Script for Applications script engine.

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

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`
`QList<int>` | `Array`
`QList<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 Getting Started with QSA for more explanations and examples.

## Member Type Documentation

### enum QSInterpreter::ClassFlags

The ClassFlags enum specifies which classes should be made available for introspection.

Constant | Value | Description
--- | --- | ---
`QSInterpreter::AllClasses` | `0` | All available classes in the interpreter, including those declared in QObject contexts, are matched.
`QSInterpreter::GlobalClasses` | `1` | Only classes declared in the global scope are matched.

### enum QSInterpreter::ErrorMode

The ErrorMode enum describes what happens when an error occurs while parsing or executing script code.

Constant | Value | Description
--- | --- | ---
`QSInterpreter::Notify` | `0` | Notifies the user that an error occurred via a message box. If the application is running in console mode (QApplication::Tty), the notification will be output to `stderr`.
`QSInterpreter::Nothing` | `1` | No notification is sent to the user. The interpreter still stops execution and emits the error() signal.

See also setErrorMode() and error().

### enum QSInterpreter::FunctionFlags

The FunctionFlags enum describes matching rules and formatting for function introspection.

Constant | Value | Description
--- | --- | ---
`QSInterpreter::FunctionNames` | `0` | Returns function names only.
`QSInterpreter::FunctionSignatures` | `1` | Returns the functions with signatures.
`QSInterpreter::IncludeMemberFunctions` | `2` | Matches member functions also, when the context to match in is a script class.

## Member Function Documentation

### QSInterpreter::QSInterpreter ( QObject * parent = 0, const char * name = 0 )

Constructs a QSInterpreter that runs without a project.

The parent and name parameters are passed on to the QObject base class.

There's a default instance accessible with QSInterpreter::defaultInterpreter().

### void QSInterpreter::addObjectFactory ( QSObjectFactory * factory )

Adds the object factory factory to the interpreter.

Using this function will clear the state of the interpreter, and will clear any transient objects.

### void QSInterpreter::addTransientObject ( QObject * object )

Adds the object object to the interpreter.

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 object name. If you want to reuse names then you need to call clear() first

See also QSProject::addObject().

### void QSInterpreter::addTransientSignalHandler ( QObject * sender, const char * signal, const char * qtscriptFunction )

Adds the Qt Script function qtscriptFunction (fully qualified) as a transient signal handler for the C++ signal signal of the object sender.

Example:

        interpreter->addTransientSignalHandler(myButton, SIGNAL(clicked()), "classA.obj.calculate");

See also removeTransientSignalHandler().

### void QSInterpreter::addTransientVariable ( const QString & variableName, const QVariant & arg, QObject * context = 0 )

Adds the variable variableName to the scope context. The variable is given the value arg. If no context is specified, the global scope is used.

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

### void QSInterpreter::addWrapperFactory ( QSWrapperFactory * factory )

Adds the wrapper factory factory to the interpreter.

Using this function will clear the state of the interpreter, and will clear any transient objects.

### QVariant QSInterpreter::call ( const QString & function, const QVariantList & arguments = QVariantList(), QObject * context = 0 )

Calls the function function with the given arguments. The arguments are first converted into Qt Script datatypes.

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.

### bool QSInterpreter::checkSyntax ( const QString & code )

Checks whether the script code code is free of syntax errors. Returns true if the code is free of syntax errors; otherwise returns false.

### QStringList QSInterpreter::classes ( ClassFlags flags = AllClasses ) const

Returns the classes in the interpreter.

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

### QStringList QSInterpreter::classes ( const QString & context ) const

This is an overloaded member function, provided for convenience. It behaves essentially like the above function.

Returns all the classes declared in the fully qualified context context.

See also functions() and variables().

### QStringList QSInterpreter::classes ( QObject * context ) const

This is an overloaded member function, provided for convenience. It behaves essentially like the above function.

Returns all the classes declared in the context context.

See also functions() and variables().

### void QSInterpreter::clear () `[slot]`

Clears the state of the interpreter.

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

### QObject * QSInterpreter::currentContext () const

Returns the current execution context of the interpreter. This is either a QObject pointer or 0.

### QSInterpreter * QSInterpreter::defaultInterpreter () `[static]`

Returns the default interpreter.

The default interpreter runs without a project.

This function will automatically create the interpreter if it doesn't already exist.

### void QSInterpreter::error ( const QString & message, const QString & scriptName, int lineNumber ) `[signal]`

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.

### void QSInterpreter::error ( const QString & message, QObject * context, const QString & scriptName, int lineNumber ) `[signal]`

This is an overloaded member function, provided for convenience. It behaves essentially like the above function.

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.

### QString QSInterpreter::errorMessage () const

Returns the error message that was last reported if there was an error; otherwise returns QString::null

### ErrorMode QSInterpreter::errorMode () const

the interpreters current error mode

### QVariant QSInterpreter::evaluate ( const QString & code, QObject * context = 0, const QString & scriptName = QString::null )

Executes the string of Qt Script in code and returns any value produced by that code.

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.

### QStringList QSInterpreter::functions ( FunctionFlags flags = FunctionNames ) const

Returns all the functions in the global context.

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

### QStringList QSInterpreter::functions ( const QString & context, uint flags = FunctionNames ) const

This is an overloaded member function, provided for convenience. It behaves essentially like the above function.

Returns all the script functions in the context context (this can be for example, a class or a form). If context is empty, the functions of the global context (global functions) are returned.

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

### QStringList QSInterpreter::functions ( QObject * context, FunctionFlags flags = FunctionNames ) const

This is an overloaded member function, provided for convenience. It behaves essentially like the above function.

Returns all script functions which have been defined in the context context.

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

### bool QSInterpreter::hadError () const

Returns true if the interpreter had an error during the last execution; otherwise returns false.

### bool QSInterpreter::hasClass ( const QString & className ) const

Returns true if the class className exists; otherwise returns false.

The class name can be a fully qualified in the form:

        myclass.innerClass

### bool QSInterpreter::hasFunction ( const QString & function ) const

Returns true if the function function exists; otherwise returns false.

The function can be a fully qualified in the form:

        myclass.function

### bool QSInterpreter::hasVariable ( const QString & variable ) const

Returns true if the variable variable exists; otherwise returns false.

The variable name can be fully qualified in the form:

        myobject.otherobject.var

### bool QSInterpreter::isRunning () const

Return true if the interpreter is currently evaluating code; otherwise returns false.

### QObjectList QSInterpreter::presentObjects () const

Returns the list of objects currently available for scripting in this interpreter.

### QSProject * QSInterpreter::project () const

Returns the current project of the interpreter or 0 if there is no project.

### void QSInterpreter::registerMetaObject ( const QMetaObject * metaObject ) `[static]`

Registers a metaObject with the interpreter runtime.

In Qt 3, all meta objects were registered in a global map. QSA used this map to decide wether or it could cast return types of that were pointers to QObjects. In Qt 4 this map is not available anymore so for QSA to treat any given subclass of QObject properly we register known meta objects.

Common widgets, such as QLabel and QPushButton, are already registered by default.

### void QSInterpreter::removeTransientSignalHandler ( QObject * sender, const char * signal, const char * qtscriptFunction )

Removes the connection between the signal signal of the object sender and the fully qualified signal handler qtscriptFunction.

See also addTransientSignalHandler().

### void QSInterpreter::setErrorMode ( ErrorMode m )

### void QSInterpreter::setTimeoutInterval ( int msecs )

### QSStackTrace QSInterpreter::stackTrace () const

Returns the stack trace describing the call stack of the last reported error if there was an error; otherwise returns an empty stack trace.

### QString QSInterpreter::stackTraceString () const

Convenience function for describing the stack trace.

Each stack frame has the following format:

        function(scriptName:lineNumber) context

### void QSInterpreter::stopExecution () `[slot]`

Stops a running interpreter by throwing an error.

### void QSInterpreter::throwError ( const QString & message )

Informs the interpreter that an error has occurred. The error is treated like a normal Qt Script error. The error message is passed in message.

### void QSInterpreter::timeout ( int elapsedTime ) `[signal]`

This signal is emitted on intervals specified by timeoutInterval()

The elapsedTime parameter describes the number of milliseconds the interpreter has been running.

### int QSInterpreter::timeoutInterval () const

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

### QVariant QSInterpreter::variable ( const QString & variableName, QObject * context = 0 ) const

Returns the value of the variableName in the scope of context. If the context is 0 (the default) the global scope is used. The variable name can be fully qualified in the form:

        a.b.c

### QStringList QSInterpreter::variables () const

Returns all the variables declared in the global context.

See also functions() and classes().

### QStringList QSInterpreter::variables ( const QString & context ) const

This is an overloaded member function, provided for convenience. It behaves essentially like the above function.

Returns all the variables declared in the fully qualified context context.

See also functions() and classes().

### QStringList QSInterpreter::variables ( QObject * context ) const

This is an overloaded member function, provided for convenience. It behaves essentially like the above function.

Returns all the variables declared in the context context.

See also functions() and classes().