Редактирование: On the Fast Track to Application Scripting

{{Панель навигации по Qt Quarterly|Выпуск 24}}

by Kent Hansen

With the introduction of Qt Script as a standard part of Qt in version 4.3,Qt/C++ application developers have a seamlessly integrated solution foradding scripting to their applications. Qt Script is a simple, yet powerfulway of providing script authors---who don't necessarily know C++---withan interface for working in the context of your Qt application. Inthis article, we give an overview of the main steps that are involved whenembedding Qt Script into an application, and use a small example to showcasethe key techniques.
__TOC__

The ''Embedding Python into Qt Applications'' article in Qt Quarterly issue 23gives a good overview of the benefits of scripting, as well as applicationscripting and the creation of such APIs in general. Like PythonQt (the solutiondescribed in that article), the purpose of Qt Script is to provide a scriptingenvironment that application authors can embed into their Qt applications; it isnot geared towards "pure" script-based application development.

In embedded scripting, you typically make one or more "host objects"(comprising your application's scripting API) available to the scriptingenvironment; you then provide one or more mechanisms for scripts to be executedin this environment.As we shall see, Qt Script's tight integration with Qt's meta-object systemmakes both the configuration process and the subsequent communication betweenC++ and scripts straightforward.
<div id="gettingstarted"></div>
===Getting Started===

In order to use Qt Script in your application, you must first add thefollowing line to your <tt>qmake</tt> project (.pro) file:
<source lang="cpp-qt">
    QT += script

</source> 
You may then include the main <tt>QtScript</tt> header in your C++ code to gainaccess to the full Qt Script API:
<source lang="cpp-qt">
    #include <QtScript>
</source> 
The [[Qt:Документация_4.3.2/qscriptengine  | QScriptEngine]] class provides your application with an embeddedscripting environment. You can have as many script engines as you want inyour application; each engine is in effect a lightweight, self-containedvirtual machine. To execute scripts, you call the engine's <tt>evaluate()</tt>function, as in the following simple example:
<source lang="cpp-qt">
    QScriptEngine engine;
    QScriptValue result = engine.evaluate("(1+2)*3");
    qDebug() << "Result as float:" << result.toNumber();

</source> 
Thankfully, the Qt Script language is capable of more than just adding andmultiplying constants. The scripting language is based on the ECMAScript 3standard (ECMA-262), and thus sports the same core language features asJavaScript 1.x, a language that is widely used in Web-based development.
<div id="scriptingqtobjects"></div>
===Scripting Qt Objects===

With Qt Script, scripting [[Qt:Документация_4.3.2/qobject  | QObject]]s is easy.  The following C++ codeshows how to make an instance of a standard [[Qt:Документация_4.3.2/qpushbutton  | QPushButton]] widget availableto scripts:
<source lang="cpp-qt">
    QPushButton button;
    QScriptValue scriptButton = engine.newQObject(&amp;button);
    QScriptValue global = engine.globalObject();
    global.setProperty("button", scriptButton);
</source> 
[http://www.crossplatform.ru/documentation/qtdoc4.3/qscriptengine.php#newQObject QScriptEngine::newQObject()] returns a ''proxy script object'' for thegiven Qt C++ object.

In the above example, we chose to make the proxy objectavailable to scripts as a global variable. Scripts can subsequently manipulateproperties of the button and call its slots through the proxy, as in thefollowing script snippet:
<source lang="cpp-qt">
    button.checkable = true;
    button.show();

</source> 
Additionally, scripts can connect to the button's signals:
<source lang="cpp-qt">
    function clickHandler(checked) {
      print("button checked: " + checked);
    }
    
    button.clicked.connect(clickHandler);
</source> 
To define our own custom scripting API, we design [[Qt:Документация_4.3.2/qobject  | QObject]]-basedclasses, expressing the API in terms of Qt properties, signals andslots.  To configure the Qt Script environment, we just need to wrapthe scripting-related objects using new[[Qt:Документация_4.3.2/qobject  | QObject]]() and make theresulting proxy objects available to scripts, like we did withthe [[Qt:Документация_4.3.2/qpushbutton  | QPushButton]] above.

In the remainder of this article, we will study a small exampleapplication, ''CubbyHolistic'', and see how we can make it scriptable.This will illustrate the main aspects of how Qt Script and Qt/C++ playtogether.
<div id="thecubbyholisticapplication"></div>
===The CubbyHolistic Application===

The original ''CubbyHolistic'' C++ application is a simpleimplementation of the producer-consumer pattern. There is a resource,a <tt>CubbyHole</tt> object, that is shared between two threads: a<tt>ProducerThread</tt> and a <tt>ConsumerThread</tt>. The <tt>CubbyHole</tt> classdeclaration looks like this:
<source lang="cpp-qt">
    class CubbyHole : public QObject
    {
    public:
        CubbyHole(QObject *parent = 0);
    
        void depositValue(const QVariant &amp;value);
        QVariant withdrawValue();
    
    private:
    // implementation details ...
    };

</source> 
The <tt>CubbyHole</tt> class uses standard synchronization mechanisms in Qt toimplement the <tt>depositValue()</tt> and <tt>withdrawValue()</tt> functions;i.e., blocking the producer and consumer when necessary.

The <tt>run()</tt> reimplementations of <tt>ProducerThread</tt> and <tt>ConsumerThread</tt>typically look like this:
<source lang="cpp-qt">
    void ProducerThread::run()
    {
      for (int i = 0; i < 10; ++i)
        cubbyHole->depositValue(i * 4);
    }
    
    void ConsumerThread::run()
    {
        for (int i = 0; i < 10; ++i) {
            QVariant v = cubbyHole->withdrawValue();
            /* Do something with the value */
        }
    }
</source> 
The application's <tt>main()</tt> function constructs a <tt>CubbyHole</tt> object andgets the producer and consumer going:
<source lang="cpp-qt">
    int main(int argc, char **argv)
    {
        QCoreApplication app(argc, argv);
    
        CubbyHole hole;
        ProducerThread producer(&amp;hole);
        ConsumerThread consumer(&amp;hole);
    
        producer.start();
        consumer.start();
        producer.wait();
        consumer.wait();
        return 0;
    }

</source> <div id="scriptingcubbyholistic"></div>
===Scripting CubbyHolistic===

As a fun little experiment, let's change ''CubbyHolistic'' so that the producerand consumer can be provided as scripts, rather than C++ classes; that is,C++ code will no longer have to be (re)compiled in order to support differentproducers and consumers that use the common <tt>CubbyHole</tt> interface.

The <tt>CubbyHole</tt> object itself will remain wholly implemented in C++, but wewill expose a scripting API to it. To do this, we can modify the <tt>CubbyHole</tt>declaration[[#fn1 | <sup>[1]</sup>]]so that <tt>depositValue()</tt> and <tt>withdrawValue()</tt> become slots:
<source lang="cpp-qt">
    class CubbyHole : public [[Qt:Документация_4.3.2/qobject  | QObject]]
    {
        Q_OBJECT
    ...
    public slots:
        void depositValue(const QVariant &amp;value);
        QVariant withdrawValue();
    ...
    };
</source> 
This will allow scripts to call these two functions. Next, we declare a[[Qt:Документация_4.3.2/qthread  | QThread]] subclass that will be used to evaluate a script in a separatethread, in the context of a given <tt>CubbyHole</tt> object:
<source lang="cpp-qt">
    class ScriptThread : public QThread
    {
    public:
        ScriptThread(const QString &amp;fileName,
                     CubbyHole *hole);
    protected:
        void run();
    
    private:
        QString m_fileName;
        CubbyHole *m_hole;
    };

</source> 
The producer and consumer will both be represented as instances of<tt>ScriptThread</tt>; it's merely a matter of passing the appropriate file nameto the constructor.  All the work happens in the <tt>run()</tt> reimplementation:
<source lang="cpp-qt">
    void ScriptThread::run()
    {
      QScriptEngine engine;
    
      QScriptValue scriptHole = engine.newQObject(m_hole);
      QScriptValue global = engine.globalObject();
      global.setProperty("cubbyHole", scriptHole);
    
      QFile file(m_fileName);
      file.open(QIODevice::ReadOnly);
      QString contents = QTextStream(&amp;file).readAll();
      file.close();
    
      engine.evaluate(contents);
    
      if (engine.hasUncaughtException()) {
        QStringList bt = engine.uncaughtExceptionBacktrace();
        qDebug() << bt.join("\n");
      }
    }

</source> 
Each thread has its own script engine. The shared <tt>CubbyHole</tt> C++ objectis exposed as a global variable in the engine, and the contents of the scriptfile are read and passed to <tt>evaluate()</tt>. There's also a check to see if theevaluation caused a script exception (e.g., due to a syntax error in thescript); in that case, we print a backtrace to aid in debugging the problem.

The final step C++-wise is to change the application's <tt>main()</tt> functionto use the <tt>ScriptThread</tt> class to provide the producer and consumer (forsimplicity, fixed file names are used).
<source lang="cpp-qt">
    int main(int argc, char **argv)
    {
      QCoreApplication app(argc, argv);
      CubbyHole hole;
      ScriptThread producer("./producer.qs", &amp;hole);
      ScriptThread consumer("./consumer.qs", &amp;hole);
    
      producer.start();
      consumer.start();
      producer.wait();
      consumer.wait();
      return 0;
    }
</source> 
Now we are ready to start writing scripts! This is the original<tt>ProducerThread</tt> behavior expressed as a script in <tt>producer.qs</tt>:
<source lang="cpp-qt">
    for (var i = 0; i < 10; ++i)
      cubbyHole.depositValue(i * 4);
</source> 
And here is the equivalent code in <tt>consumer.qs</tt>:
<source lang="cpp-qt">
    for (var i = 0; i < 10; ++i) {
      var v = cubbyHole.withdrawValue();
      /* Do something with the value */
    }

</source> 
Here's a producer script that will generate a random sequence of Fibonaccinumbers:
<source lang="cpp-qt">
    function fibonacci(n) {
      if (n <= 1)
        return n;
      return fibonacci(n-1) + fibonacci(n-2);
    }
    
    for (var i = 0; i < 10; ++i) {
      var arg = Math.round(Math.random() * 20);
      var value = fibonacci(arg);
      cubbyHole.depositValue(value);
    }
</source> 
With a little more effort, the scripts can become "pluggable"; for example,the application could scan a folder of scripts and have the user pick orcreate the producer and consumer he or she wants to use.
<div id="furtherreading"></div>
===Further Reading===

Qt Script has features that haven't been discussed in this article, butwhich can be useful in more complex applications---such as the ability toscript non-[[Qt:Документация_4.3.2/qobject  | QObject]] types. That being said, the Qt Script C++ API itselfis quite lightweight thanks to its tight integration with Qt as a whole.The Qt documentation and examples cover the use of Qt Script in detail,including interesting use cases like how to combine Qt Script and [[Qt:Документация_4.3.2/designer-manual  | Qt Designer]] forms.<hr width="25%" />
<div id="fn1"></div><sup>[1]</sup> Modifying the C++ class API directly has been donehere for the sake of simplicity; in your application, you may want to haveseparate C++ and scripting APIs.

[http://www.forum.crossplatform.ru/index.php?showtopic=703 Обсудить...]

[[Категория:Qt_Издания]]