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

[Prev: How to Make Qt Applications Scriptable] [Home] [Next: Creating Qt Scripts]

## How to Design and Implement Application Objects

### Overview

This chapter explains how to implement application objects and provides the necessary technical background material.

### Making a C++ object available to Scripts Written in Qt Script

Making C++ classes and objects available to a scripting language is not trivial since scripting languages are more dynamic than C++ and it must be possible to introspect objects (query information such as functions names, function signatures, properties, etc., at runtime). Standard C++ doesn't provide for this.

We can achieve the functionality we want by extending C++, using C++'s own facilities so our code is still standard C++. The Qt meta object system provides the necessary additional functionality. It allows us to write using an extended C++ syntax, but converts this into standard C++ using a small utility program called moc (Meta Object Compiler). Classes that wish to take advantage of the meta object facilities are either subclasses of QObject, or use the `Q_OBJECT` macro. Qt has used this approach for many years and it has proven to be solid and reliable. Qt Script for Applications uses this meta object technology to provide scripters with dynamic access to C++ classes and objects.

To completely understand how to make C++ objects available to Qt Script, some basic knowledge of the Qt meta object system is very helpful. We recommend that you read the Qt Object Model. The information in this document and the documents it links to are very useful for understanding how to implement application objects, however this knowledge is not essential.

To make an object available in Qt Script, it must derive from QObject. All classes which derive from QObject are introspective and can provide the information needed by the scripting engine, e.g. classname, functions, signatures, etc., at runtime. Because we obtain the information we need about classes dynamically at run time, there is no need to write wrappers for QObject derived classes.

#### Making C++ Class Member Functions Available in Qt Script

The meta object system makes information about slots dynamically available at runtime. This means that for QObject derived classes, only the slots are automatically made available to scripts. This is very convenient, because in practice we normally only want to make specially chosen functions available to scripters.

When you create a QObject subclass, make sure that the functions you want to be available to scripters are public slots:

    class MyObject : public QObject
    {
        Q_OBJECT

    public:
        MyObject( ... );

        void aNonScriptableFunction();

    public slots: // these functions (slots) will be available in Qt Script
        void calculate( ... );
        void setEnabled( bool enabled );
        bool isEnabled() const;

    private:
       ....

    };

In the example above, aNonScriptableFunction() is not declared as a slot, so it will not be available in Qt Script. The other three functions will automatically be made available in Qt Script.

#### Making C++ Class Properties Available in Qt Script

In the previous example, if we wanted to get or set a property using Qt Script we would have to write code like the following:

    var obj = new MyObject;
    obj.setEnabled( true );
    debug( "obj is enabled: " + obj.isEnabled() );

Scripting languages often provide a property syntax to modify and retrieve properties (in our case the enabled state) of an object. Many script programmers would want to write the above code like this:

    var obj = new MyObject;
    obj.enabled = true;
    debug( "obj is enabled: " + obj.enabled );

To make this possible, you must define properties in the C++ QObject subclass. The class declaration of `MyObject` must look like the following to declare a property `enabled` of the type `bool`, which should use the function `setEnabled(bool)` as its setter function and the function `isEnabled()` as its getter function:

    class MyObject : public QObject
    {
        Q_OBJECT
        // define the enabled property
        Q_PROPERTY( bool enabled WRITE setEnabled READ isEnabled )

    public:
        MyObject( ... );

        void aNonScriptableFunction();

    public slots: // these functions (slots) will be available in Qt Script
        void calculate( ... );
        void setEnabled( bool enabled );
        bool isEnabled() const;

    private:
       ....

    };

The only difference from the original code is the use of the macro `Q_PROPERTY`, which takes the type and name of the property, and the names of the setter and getter functions as arguments.

#### Reacting to C++ Objects Signals in Scripts

In the Qt object model, signals are used as a notification mechanism between QObjects. This means one object can connect a signal to another object's slot and every time the signal is fired (emitted) the slot is called. This connection is established using the `QObject::connect()` function. This mechanism is also available to Qt Script programmers. The C++ code for declaring a signal is no different for a C++ class that is to be used by Qt Script than a C++ class used with Qt.

    class MyObject : public QObject
    {
        Q_OBJECT
        // define the enabled property
        Q_PROPERTY( bool enabled WRITE setEnabled READ isEnabled )

    public:
        MyObject( ... );

        void aNonScriptableFunction();

    public slots: // these functions (slots) will be available in Qt Script
        void calculate( ... );
        void setEnabled( bool enabled );
        bool isEnabled() const;

    signals: // the signals
        void enabledChanged( bool newState );

    private:
       ....

    };

The only change this time is to declare a `signals` section, and declare the relevant signal in it.

Now the script writer can write a function and connect to the object like this:

    function enabledChangedHandler( b )
    {
        debug( "state changed to: " + b );
    }

    function init()
    {
        var obj = new MyObject;
        // connect a script function to the signal
        connect( obj, "enabledChanged(bool)", this, "enabledChangedHandler" );
        obj.enabled = true;
        debug( "obj is enabled: " + obj.enabled );
    }

### Design of Application Objects

The previous section described how to implement C++ objects which can be used in Qt Script. Application objects are the same kind of objects, and they make your application's functionality available to Qt Script scripters.

Since the C++ application is already written in Qt, many objects are already QObjects. The easiest approach would be to simply add all these QObjects as application objects to the scripting engine. For small applications this might be sufficient, but for larger applications this is probably not the right approach. The problem is that this method reveals too much of the internal API and gives script programmers access to application internals which should not be exposed.

Generally, the best way of making application functionality available to scripters is to code some QObjects which define the application's public API using signals, slots, and properties. This gives you complete control of the functionality you make available. The implementation of these objects simply calls the functions in the application which do the real work. So instead of making all your QObjects available to the scripting engine, just add the "wrapper QObjects". For an example of this technique, see the implementation of an application object in the `SheetInterface` (`examples/spreadsheet/sheetinterface.{cpp|h}`).

[Prev: How to Make Qt Applications Scriptable] [Home] [Next: Creating Qt Scripts]