|Home | Tutorial | Classes | Functions | QSA Developer | 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().

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 Qt Scripter, 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, Qt Scripter 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 ( QSProject * project = 0 )

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

project specifies the QSProject, which this interpreter will work on.

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 openIDE() and closeIDE() 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.

QSInterpreter * QSInterpreter::defaultInterpreter () [static]

Returns the application-wide default interpreter.

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

Examples: spreadsheet/addscriptdialog.ui.h and spreadsheet/spreadsheet.ui.h.

void QSInterpreter::error ( const QString & message, const QString & filename, 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, filename the filename (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 & filename, 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, filename 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 openIDE() and closeIDE() 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().

bool QSInterpreter::isRunning () const

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

const QObjectList * QSInterpreter::objects () const

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

QSProject * QSInterpreter::project () const

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

Example: spreadsheet/addscriptdialog.ui.h.

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.

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


Copyright © 2001-2003 TrolltechTrademarks
QSA version 1.0.0-beta2