| Tutorial | Classes | Functions | QSA Developer | Language | Library | Qt API 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().

Use addObject() to make application objects available to the interpreter for use by scripts. Such objects can be removed from the interpreter's view with removeObject().

A global function can be executed using call(). Any string containing valid Qt Script code can be executed using evaluate(). These two functions do not require a project to be open, but most other functions only work if there is a current project. Even if you don't use the QSA Developer, it is suggested to use a scripting project, only for very simple cases, where nothing more than evaluating a simple piece of code is needed, it makes sense to work without a project.

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

The list of functions available in a particular class is available from functionsOf(), and the list of global functions is returned by globalFunctions(). To introspect variables and classes in a context, use classesOf() and variablesOf().

See the Manual for more explanation and examples.


Member Type Documentation

QSInterpreter::ErrorMode

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

* If there is no project open, QSA Developer can and will not be invoked, so you will need to handle the error() signal yourself or only get a notification message box, if the errorMode() is something else than Nothing.


Member Function Documentation

QSInterpreter::QSInterpreter ()

Constructs a QSInterpreter.

Currently, only one instance of the class QSInterpreter may exist at any one time. You can access this instance with QSInterpreter::defaultInterpreter().

void QSInterpreter::addObject ( QObject * o ) [slot]

Makes the QObject o available to the scripting engine. All child objects of o are made available too.

If no object in the parent hierarchy of o has been added via addObject() yet, o will be made available as a toplevel object to the programmer and will be accessible via Application.object_name (where object_name is the value of o's QObject::name() property).

If an object in the parent hierarchy of o has been made available via addObject() already, o will not be made available as a toplevel object. It is accessible then through parent1.parent2.object_name in the scripting language, given that parent1 has been made available via addObject() previously. The reason to make an object available like this, even though it is not made available as a toplevel object, is so that code can be added in in the context of that object. See setObjectSource().

Warning: Every object passed to this function must have a name.

Example: scriptbutton/main.cpp.

void QSInterpreter::addSignalHandler ( QObject * sender, const char * signal, QObject * receiver, const char * qtscriptFunction )

Adds the Qt Script function qtscriptFunction in the context of receiver as signal handler for the C++ signal signal of the object sender.

Example:

  QSInterpreter::defaultInterpreter()->addSignalHandler( Form1.okButton, SIGNAL( clicked() ), document, "startCalculation" );
  

See also removeSignalHandler().

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

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

Example:

  QSInterpreter::defaultInterpreter()->addSignalHandler( Form1.okButton, SIGNAL( clicked() ), "classA.obj.calculate" );
  

See also removeSignalHandler().

QVariant QSInterpreter::call ( const QString & function, const QValueList<QVariant> & arguments, 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.

The functions openDeveloper() and closeDeveloper() clear the interpreter and re-evaluate the current project, meaning the code which has been passed previously into evaluate() gets lost when calling one of these functions.

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

Returns all currently declared classes.

See also functionsOf(), classesOf(), and variablesOf().

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

Returns all currently declared classes in the fully qualified context context

See also functionsOf(), classes(), globalClasses(), and variablesOf().

QStringList QSInterpreter::classesOf ( QObject * context ) const

Returns all currently declared classes in the context context

See also functionsOf(), classes(), globalClasses(), and variablesOf().

void QSInterpreter::clear () [slot]

Clears the interpreter and closes the currently opened Qt Script for Applications project, if one is open.

This function does not clear the application objects. Use clearObjects() to do that.

void QSInterpreter::clearObjects () [slot]

Removes all application objects from the list of available objects. Note that this deosn't delete the application objects!

See also removeObject().

QObject * QSInterpreter::currentContext () const

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

QSProject * QSInterpreter::currentProject () const

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

Example: spreadsheet/addscriptdialog.ui.h.

QSInterpreter * QSInterpreter::defaultInterpreter () [static]

Returns the application-wide default interpreter.

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

Example: spreadsheet/addscriptdialog.ui.h.

void QSInterpreter::error ( const QString & message, const QString & file, 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, file the filename (if known) where the error occured, and lineNumber the line number at which the error occured..

ErrorMode QSInterpreter::errorMode () const

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

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

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

The functions openDeveloper() and closeDeveloper() clear the interpreter and re-evaluate the current project, meaning the code which has been passed previously into evaluate gets lost when calling one of these functions.

QStringList QSInterpreter::functionsOf ( const QString & context, bool includeSignature = FALSE ) 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 includeSignature is FALSE (the default), no signature is appended to the function name. If includeSignature is TRUE then each name returned will be of the form:

  functionName( typeOfArg1, typeOfArg2, ... )
  

See also globalFunctions(), classes(), classesOf(), and variablesOf().

QStringList QSInterpreter::functionsOf ( QObject * context, bool includeSignature = FALSE ) const

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

If includeSignature is FALSE (the default), no signature is appended to the function name. If includeSignature is TRUE then each name returned will be of the form:

  functionName( typeOfArg1, typeOfArg2, ... )
  

See also globalFunctions(), classes(), classesOf(), and variablesOf().

QStringList QSInterpreter::globalClasses () const

Returns all currently declared classes in the global context

See also functionsOf(), classes(), classesOf(), and variablesOf().

QStringList QSInterpreter::globalFunctions ( bool includeSignature = FALSE ) const

If a project is open, then all the names of all the global functions in that project are returned. If no project is open, then all the names of all the global functions created with evaluate() are returned.

If includeSignature is FALSE (the default), no signature is appended to the function name. If includeSignature is TRUE then each name returned will be of the form:

 functionName( typeOfArg1, typeOfArg2, ... )
 

See also functionsOf(), classes(), classesOf(), and variablesOf().

Example: spreadsheet/addscriptdialog.ui.h.

QStringList QSInterpreter::globalVariables () const

Returns all currently declared variables in the global context

See also functionsOf(), classes(), classesOf(), and variablesOf().

QString QSInterpreter::objectSource ( QObject * object ) const

Returns the code of the object object

const QObjectList * QSInterpreter::objects () const

Returns the list of available objects for scripting.

void QSInterpreter::removeObject ( QObject * o ) [slot]

Removes the QObject o from the list of available objects for scripting.

See also clearObjects().

void QSInterpreter::removeSignalHandler ( QObject * sender, const char * signal, QObject * receiver, const char * qtscriptFunction )

Removes the connection between the signal signal of the object sender and the the signal handler qtscriptFunction in the context receiver.

See also addSignalHandler().

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

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

See also addSignalHandler().

void QSInterpreter::setErrorMode ( ErrorMode m )

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

void QSInterpreter::setObjectSource ( QObject * object, const QString & code, bool append = FALSE ) [slot]

Adds the script code code in the context of object. object must have been available to the scripting language via addObject() before.

If there has been set code already for that object object, code is appended to this code if append is TRUE, otherwise the currently set code is replaced with code.

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

Returns all currently declared variables in the fully qualified context context

See also functionsOf(), classes(), classesOf(), and globalFunctions().

QStringList QSInterpreter::variablesOf ( QObject * context ) const

Returns all currently declared variables in the contenxt context

See also functionsOf(), classes(), classesOf(), and globalFunctions().


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-2002 Trolltech. All Rights Reserved.


Copyright © 2001-2002 TrolltechTrademarks
QSA version 1.0.0-beta1