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

QSProject Class Reference

The QSProject class provides project management over scripts written in Qt Script for Applications. More...

#include <qsproject.h>

List of all member functions.

Public Members

Public Slots

Signals


Detailed Description

The QSProject class provides project management over scripts written in Qt Script for Applications.

The projects interpreter can be accessed through the function interpreter().

Scripts are encapsulated as instances of the class QSScript. QSScript objects are created by using the createScript() functions. It is possible to query the project for scripts using the functions scripts(), scriptNames() or script().

It is possible to associate a QSScript with a context object, meaning that the script will be evaluated in the context of that object. If a script and an object has the same name, they are grouped together.

One can add and remove objects to the project with addObject() and removeObject(). One can query the project for its objects using the functions object() and objects(). Note that objects added to the project become persistant, meaning that when the interpreter is cleared, they will still be scriptbable. This is in contrast to objects added to the interpreter through the function QSInterpreter::addTransientObject(), which will not be available after the interpreter is cleared.

A project can be stored on disk and loaded again using the functions load() and save(). It is also possible to write the project to a data buffer that can be used in union with other applications by using the functions loadFromData() and saveToData().

The project also manages editors for the scripts it holds. Editors can be created using the functions createEditor() and can be queried for using the functions editors(), editor() or activeEditor(). When text changes in the interpreter the signal editorsModified() is emitted. Before the changes are reflected in the script the function commitEditorContents() must be called. To revert the editors to the code in the scripts use revertEditorContents().

When the editors are committed, the scripts will be out of sync with the state of the interpreter. The signal scriptsModified() is emitted to notify about this.

Several actions in the interpreter will trigger re-evaluation of the project, meaning that the interpreter will be cleared and the scripts re-evaluated. These actions include modifying scripts, removing objects.

The functions addSignalHandler() and removeSignalHandler() can be used to connect and disconnect signals and slot from C++ to Qt Script.

See the Manual for more explanation and examples.

See also QSScript, QSEditor, and QSInterpreter.


Member Function Documentation

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

Constructs a QSProject with parent parent and name

QSEditor * QSProject::activeEditor () const

Returns the editor which is currently editing the project if an editor is active for this project; otherwise 0.

void QSProject::addObject ( QObject * object ) [slot]

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

If no object in the parent hierarchy of object has been added via addObject() yet, object 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 object's QObject::name() property).

If an object in the parent hierarchy of object has been made available via addObject() already, object 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.

Objects added with this function are made persistent. This means that when the interpreter is cleared, either by calling QSInterpreter::clear() or by modifying the scripts, these objects will still be made available to the scripting engine.

If a script exists in the project that has the same name as object the script will be evaluated with object as context.

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

See also QSInterpreter::addTransientObject(), removeObject(), clearObjects(), and object().

void QSProject::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:

  project->addSignalHandler( myButton, SIGNAL( clicked() ), document, "startCalculation" );
  

See also removeSignalHandler().

void QSProject::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:

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

See also removeSignalHandler().

void QSProject::clearObjects () [slot]

Removes all application objects from the list of available objects.

QSProject does not take ownership of the objects, so the objects are not cleard.

See also addObject(), removeObject(), object(), and QSInterpreter::addTransientObject().

void QSProject::commitEditorContents () [slot]

Updates the scripts with the content of the editors.

For each editor that is changed, commit() is called for it, propagating the changes in the editor onto the script it is currently editing.

After a call to commitEditorContents, the project will no longer be modified

See also editorsModified() and revertEditorContents().

QSEditor * QSProject::createEditor ( QSScript * script, QWidget * parent = 0, const char * name = 0 )

Creates a new editor for the script script with the parent parent and name name

If script does not belong to the current project, 0 is returned.

If an editor already exists for the given script the existing editor is returned.

QSScript * QSProject::createScript ( QObject * context, const QString & code = QString::null )

Creates a script with context context and source code code.

The context is added to this projects list of objects.

If a script already exists for this context, 0 is returned.

QSScript * QSProject::createScript ( const QString & name, const QString & code = QString::null )

Creates a script with the name name and source code code without a context.

If an object exists in the project with the same name as name, the object is associated with the created script and the script will be evaluated in the context of that object.

If a script already exists with this name, 0 is returned.

QSEditor * QSProject::editor ( QSScript * script ) const

Returns the editor for the script script if the editor exists; otherwise returns 0.

void QSProject::editorTextChanged () [signal]

This signal is emitted whenever text changes in one of the editors that this project currently manages

QPtrList<QSEditor> QSProject::editors () const

Returns a list of all the editors for the scripts in this project.

bool QSProject::editorsModified () const

Returns true if the project is modified.

A project enters the modified state when the editors and scripts become out of sync. This is the case when a user simply edits a script in an editor. Before the interpreter is used, this value should be checked and the application should decide to either commit or revert the changes in the editor before the project is evaluated.

See also commitEditorContents() and revertEditorContents().

QSInterpreter * QSProject::interpreter () const

Returns the interpreter which is used to evaluate code for this project.

bool QSProject::load ( const QString & projectFile ) [slot]

Reads and parses the Qt Script for Applications project contained in the file, projectFile.

If an error occurs while running or parsing the script, actions according to the errorMode() are taken and the signal error() is emitted.

After load() is called, functions and classes defined in this project can be called and used using evaluate() and call().

If the project has signal/slot connections then these connections are established as part of the open() process.

bool QSProject::loadFromData ( QByteArray projectData ) [slot]

Reads and parses the Qt Script for Applications project from projectData.

If an error occurs while running or parsing the script, actions according to the errorMode() are taken and the signal error() is emitted.

After loadFromData() is called, functions and classes defined in this project can be called and used using evaluate() and call().

If the project has signal/slot connections then these connections are established as part of the process.

QObject * QSProject::object ( const QString & name ) const

Returns the persistent object in the project with name.

QObjectList QSProject::objects () const

Returns the list of persistent objects in this this project

void QSProject::removeObject ( const QObject * object ) [slot]

Removes the persistent QObject object from the list of available objects for scripting.

Note that only the persistent projects can be removed with this function. Objects added to the interpreter using QSInterpreter::addTransientObject can not be removed with this function.

If object is the context of a script, the script will also be removed from the project.

See also addObject(), clearObjects(), and object().

void QSProject::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 QSProject::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 QSProject::revertEditorContents () [slot]

Reverts the text in the editors to the state of the scripts.

After a call to revertEditorContents, the project will no longer return TRUE from editorsModified()

See also editorsModified() and commitEditorContents().

bool QSProject::save ( const QString & projectFile = QString::null ) [slot]

Saves the scripts project to the file projectFile

The default for projectFile is QString::null, in which case the filename used during load was used.

See also load().

bool QSProject::saveToData ( QByteArray data ) [slot]

Writes the the whole project to the data block data.

This is useful for keeping the project data with a document. For example, you could take the data returned by this function and store it in a document's file. Later, when the document was opened, you could extract this data from the document and pass it to the overload of openFromData() that takes a QByteArray to reconstruct the project.

See also loadFromData().

QSScript * QSProject::script ( const QString & name ) const

Returns the script with the name name if it exists in the project; otherwise returns 0.

QSScript * QSProject::script ( QObject * context ) const

Returns the script that has context as context if it exists in the project; otherwise returns 0.

QStringList QSProject::scriptNames () const

Returns the names of all the scripts in this project

QPtrList<QSScript> QSProject::scripts () const

Returns a list of all the scripts in this project

bool QSProject::scriptsModified () const

Returns TRUE if the scripts has been modified and are out of sync with the state in the interpreter; otherwise returns FALSE.

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