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

Qt Script: Library Reference

This is an early version of Qt Script for Applications and the library documentation is not finished yet. (See also the Language Reference.)

With Qt Script for Applications we provide a technology which dynamically binds QObjects (and subclasses) to the scripting language Qt Script. By using the Qt Meta Object System, the scripting engine can query all the signals, slots and properties of the QObjects at runtime, and offer these objects, signals, slots and properties to the user of the scripting language. This is extremely powerful, as QObjects can be used from the scripting language without any additional effort (no additional wrappers need to be written).

In practice, the existing signals, slots and properties are not always sufficient. Additional functions may be required by Qt Script for Applications to allow scripters to enjoy the full benefits of the classes. In our experience the number of such functions is small but shouldn't be neglected in order to make the full functionality available to the script user.

In order to solve this problem without adding any bloat to the core C++ implementation, we implemented an "add-on" technology that allows existing QObject classes to be "enriched" with additional signals, slots and properties. We haven't completed the work of thoroughly scanning through every single Qt class yet, so if you miss some functionality, please tell use about it and we will "enrich" the relevant classes accordingly. In the future we hope to provide a means by which developers can enrich classes themselves.

Those Qt classes (e.g. QFile, QSocket, etc.), which are not QObjects, but which are useful to scripters, especially since they aren't built in to Qt Script, have been provided with with wrappers to make them available to scripters. If there are classes or functions like these which you feel are missing, please tell us.

When the library reference is finished, it will provide comprehensive API documentation for the Qt library (as available to Qt Script) and the extensions specially provided for Qt Script.

For the time being, please refer to the Qt/C++ documentation for all the signals, slots and properties for the QObjects which are available to Qt Script. For the documentation of the non-QObject types which are available as native Qt Script types, refer to the language reference's 'Built-In Types' chapter.

Some other non-QObject and non-visual QObject classes are also available in Qt Script and can be instantiated using new. For example:

    var i = new QListViewItem( listView );

These classes include QObjectList, QListViewItem, QListBoxItem, DomNode, DomElement, DomText, DomDocument, QProcess, QFontDatabase, FontDatabase, Socket, Dir and File. These will be completed (API-wise) and more will be added before the final release. For the usage of some of them see the example script in the simplescript example. There is no API documentation available yet, but the API is very similar to the Qt/C++ API, so use that for reference, and also see qsa/src/extensions/quickqt*.h, for the declaration of the classes.

Qt Scripter's name completion provides the names and types of arguments, and in many cases this is sufficient.

There are also some global (static) objects besides the ones mentioned in the language reference. These are Database, MessageBox, Network, ToolTip, WhatsThis, WidgetFactory, FileDialog, ColorDialog and InputDialog. There is no API documentation available for these at the moment. They are used like this:

    var fn = FileDialog.getOpenFileName();

The completion in the Qt Scripter should provide sufficient information to use these static objects for now. Also you can look in qsa/src/extensions/quickqt*.h for the declarations of these classes.

All of Qt's widgets and layouts can be instantiated from Qt Script via new, for example:

var dialog = new QDialog;

var layout = new QHBoxLayout( dialog );

var okButton = new QPushButton( dialog );
layout.addWidget( okButton, 0 );
okButton.text = "&OK";

var closeButton = new QPushButton( dialog );
layout.addWidget( closeButton, 0 );
closeButton.text = "Close";

connect( closeButton, "clicked()", dialog, "close()" );

dialog.setGeometry( 100, 100, 200, 100 );
dialog.exec();

As parameters to the constructor a parent widget and a name can be specified.

Or similar, if you want to implement the above in a Qt Script class:

class Dialog
{
    var dialog;

    function Dialog()
    {
        dialog = new QDialog;

        var layout = new QHBoxLayout( dialog );

        var okButton = new QPushButton( dialog );
        layout.addWidget( okButton, 0 );
        okButton.text = "&OK";

        var closeButton = new QPushButton( dialog );
        layout.addWidget( closeButton, 0 );
        closeButton.text = "Close";

        connect( closeButton, "clicked()", okClicked );
    }

    function okClicked()
    {
        debug( "ok clicked" );
        dialog.accept();
    }

    function exec()
    {
        dialog.setGeometry( 100, 100, 200, 100 );
        return dialog.exec();
    }
}

function createDialog()
{
    var dia = new Dialog;
    dia.exec();
}


Copyright © 2001-2003 TrolltechTrademarks
QSA version 1.0.0-beta2