QSWrapperFactory Class

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

# QSWrapperFactory Class Reference

The QSWrapperFactory class provides a method for Qt Script to extend QObject C++ types and to automatically wrap non-QObject C++ types. More...

`#include <qswrapperfactory.h>`

List of all member functions.

## Public Members

- QSWrapperFactory ()
- virtual QObject * create ( const QString & className, void * ptr ) = 0
- void registerWrapper ( const QString & className, const QString & cppClassName = QString::null )
- void throwError ( const QString & message )

## Protected Members

- QSInterpreter * interpreter () const

## Detailed Description

The QSWrapperFactory class provides a method for Qt Script to extend QObject C++ types and to automatically wrap non-QObject C++ types.

If a C++ object which is available to Qt Script returns a pointer of a non-QObject type, by default Qt Script can't wrap it dynamically. It can store the pointer and pass it on, but no functions can be called on the object. The QSWrapperFactory class provides a means of making non-QObject types properly accessible from Qt Script.

The way QSWrapperFactory achieves this is that when a non-QObject pointer is returned, the Qt Script interpreter tries to find a wrapper for that type. A wrapper is a QObject which can wrap the non-QObject type and which makes the non-QObject type's slots, properties, etc. available to Qt Script.

In some cases even a QObject might need to be wrapped. For example, we might want to use a QObject subclass's functions which are not declared as slots in Qt Script. Qt Script only makes the slots, signals and properties of QObjects available. With QSWrapperFactory it is possible to define a QObject which extends another QObject with additional slots, properties, and signals.

To make use of this method, wrap the classes you want to make available or want to extend (see the example below). You then create a QSWrapperFactory (wrapper factory) subclass. You register your wrapper factory (or factories) with the Qt Script interpreter. When the interpreter needs an instance of a class, it checks the registered wrapper factories to see if the class has a suitable wrapper.

Call registerWrapper() for each class that this instance of QSWrapperFactory can wrap. Reimplement create() to create a wrapper for a certain type. Finally, create an instance of the QSWrapperFactory and add it to an interpreter.

The following code is an example of how to make a non-QObject C++ type known to Qt Script. We create a wrapper for a class called Process that provides a function called exec(). We then create a wrapper factory which we'll register with the interpreter. You can wrap as many classes as you like and make them all available through a single wrapper factory (although you can use as many wrapper factories as you like).

The created wrapper is deleted by the interpreter as at some point after that the interpreter determines that there are no more references to the wrapped type from script.

        class ProcessWrapper : public QObject
        {
            Q_OBJECT
        public:
            ProcessWrapper( Process *p ) : proc( p ) {}
        public slots:
            void exec( const QString &args ) { proc->exec( args ); }
        private:
            Process *proc;
        };

        class WrapperFactory : public QSWrapperFactory
        {
        public:
            WrapperFactory()
            {
                registerWrapper( "Process", "ProcessWrapper" );
            }

            QObject *create( const QString &className, void *ptr ) {
                if ( className == "Process" )
                    return new ProcessWrapper( (Process*)ptr );
                return 0;
            }
        };

Somewhere in your code, before executing any QSA related functionality, you must instantiate an instance of our new wrapper.

        interpreter->addWrapperFactory( new WrapperFactory() );

Now, whenever Qt Script comes across a Process pointer, it will look through its wrapper factories to find one that provides a wrapper for the Process class and wrap it (e.g. with ProcessWrapper). So the script writer will now be able to use all the slots, properties, and signals that ProcessWrapper provides.

To extend a QObject C++ type, you do exactly the same process: i.e. wrap the class in a class that exposes the required functionality, put the wrapper in a wrapper factory, and register the wrapper factory with the interpreter.

## Member Function Documentation

### QSWrapperFactory::QSWrapperFactory ()

This constructor creates a wrapper factory. To make the wrapper factory available to an interpreter, use QSInterpreter::addWrapperFactory()

See also QSInterpreter::addWrapperFactory().

### QObject * QSWrapperFactory::create ( const QString & className, void * ptr )`[pure virtual]`

This function is called by the Qt Script interpreter to request a wrapper for the type className. ptr is a pointer to the instance of the type className. The ptr will be passed to its related wrapper function and an instance of the wrapper will be returned.

Reimplement this function to make your wrappers available from your wrapper factory.

If ptr is invalid or any other invalid operation occurs, you can use throwError() to issue a Qt Script error.

### QSInterpreter * QSWrapperFactory::interpreter () const`[protected]`

Returns the interpreter that this wrapper factory is creating objects for.

### void QSWrapperFactory::registerWrapper ( const QString & className, const QString & cppClassName = QString::null )

Registers that this factory provides a wrapper for the type className. The cppClassName variable tells the engine which C++ class is used to represent it. This is used for better completion. \cppClassName can be null (the default) in which case the engine assumes that the script class and C++ implementation both have the same name.

### void QSWrapperFactory::throwError ( const QString & message )

Informs the interpreter that an error has occurred. The error is treated like a normal Qt Script error. The error message is passed in message.

This file is part of Qt Script for Applications, copyright © 2001-2004 Trolltech. All Rights Reserved.