|Home | Tutorial | Classes | Functions | Qt Scripter | Language | Library | Qt API | QSA Articles Qt Script for Applications

QSInterpreter Class Reference

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

#include <qsinterpreter.h>

List of all member functions.

Public Members

Public Slots

Signals

Static Public Members

Properties


Detailed Description

The QSInterpreter class provides the public API for 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 convience reasons, 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 functionallity of the interpreter. Any containing valid Qt Script code can be executed using evaluate(), and any state built up during evaluation will be 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 for a time. 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, e.g. 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 function hadError(), errorMessage() and stackTrace() can be used to provide error information.

See the Manual for more explanation and examples.


Member Type Documentation

QSInterpreter::ClassFlags

The ClassFlags enum describe which method should be for class introspection.

QSInterpreter::ErrorMode

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

QSInterpreter::FunctionFlags

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


Member Function Documentation

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

Constructs a QSInterpreter that runs without a project.

parent describes the parent of the interpreter and name describes the name of the interpreter.

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.

void QSInterpreter::addTransientObject ( QObject * object )

Adds the object object to the interpreter.

Transient objects added to the interpreter are not persistent, meaning that when the interpreter is cleared, they are also removed. Also, when the project is re-evaluated the interpreter is also cleared and these objects removed.

Use QSProject::addObject() to add persistent objects to the interpreter.

See also QSProject::addObject().

void QSInterpreter::addWrapperFactory ( QSWrapperFactory * factory )

Adds the wrapper factory factory to the interpreter.

Using this function will clear the state of the interpreter.

QSArgument QSInterpreter::call ( const QString & function, const QSArgumentList & arguments = QSArgumentList ( ), QObject * context = 0 )

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

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 (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 is subject to re-evaluation, meaning 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 if the script code code is free of syntax errors or not. Returns TRUE if the code is free of syntax errors; otherwise FALSE.

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

Returns the classes in the interpreter.

If flags is AllClasses (the default) all classes in the interpreter are returned, also those declared in object contexts. If flags is GlobalClasses, only classes declared in the global context are returned.

See also functions() and variables().

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

Returns all classes declared in the fully qualified context context

See also functions() and variables().

QStringList QSInterpreter::classes ( QObject * context ) const

Returns all classes declared in the context context

See also functions() and variables().

void QSInterpreter::clear () [slot]

Clear the state of the interpreter.

When the interpreter is cleared, all declarations parsed using the function QSInterpreter::evaluate() is removed. The state of all variables will also cleared.

Clearing the interpreter will also remove the non persistant objects. Non persistant objects are those added with the function QSInterpreter::addObject() 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 the scriptname (if known) where the error occured, and lineNumber the line number at which the error occured..

void QSInterpreter::error ( const QString & message, QObject * context, 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, context a pointer to the QObject context in which the error occured or 0, if the context is the global context, scriptName the scriptName (if known) where the error occured, and lineNumber the line number at which the error occured.

QString QSInterpreter::errorMessage () const

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

ErrorMode QSInterpreter::errorMode () const

Returns what should happen when an error occurs. See the "errorMode" property for details.

QSArgument 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 (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 is subject to re-evaluation, meaning 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 can be used for error reporting and debugging.

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

Returns all the functions in global context.

If flags includes FunctionSignatures (not default), no signature is appended to the function name. If flags includes is FunctionSignatures then each name returned will be of the form:

  functionName( typeOfArg1, typeOfArg2, ... )
  

See also classes() and variables().

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

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

context can be fully qualified.

If flags includes FunctionSignatures (not default), no signature is appended to the function name. If flags includes is FunctionSignatures then each name returned will be of the form:

  functionName( typeOfArg1, typeOfArg2, ... )
  

If flags includes IncludeMemberFunctions and context represents a class declared in script, this function will return all functions in that class, static and non static; otherwise only static functions.

See also classes() and variables().

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

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

If flags includes FunctionSignatures (not default), no signature is appended to the function name. If flags includes is FunctionSignatures then each name returned will be of the form:

  functionName( typeOfArg1, typeOfArg2, ... )
  

See also classes() and variables().

bool QSInterpreter::hadError () const

Returns TRUE if the interpreter had an error during the last execution; otherwise FALSE

bool QSInterpreter::isRunning () const

Return TRUE if the interpreter is currently evaluating code, returns FALSE otherwise.

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::setErrorMode ( ErrorMode m )

Sets what should happen when an error occurs to m. See the "errorMode" property for details.

QSStackTrace QSInterpreter::stackTrace () const

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

void QSInterpreter::throwError ( const QString & message )

Informs the interpreter than an error occured. The error is treated like a normal Qt Script error. The error message is passed in message.

QStringList QSInterpreter::variables () const

Returns all variables declared in the global context

See also functions() and classes().

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

Returns all variables declared in the fully qualified context context

See also functions() and classes().

QStringList QSInterpreter::variables ( QObject * context ) const

Returns all variables declared in the contenxt context

See also functions() and classes().


Property Documentation

ErrorMode errorMode

This property holds what should happen when an error occurs.

Set this property's value with setErrorMode() and get this property's value with errorMode().


This file is part of Qt Script for Applications, copyright © 2001-2003 Trolltech. All Rights Reserved.


Copyright © 2001-2003 TrolltechTrademarks
QSA version 1.0.0-beta2