Development/Tutorials/Kross/Call Functions in Kross: Difference between revisions

    From KDE TechBase
    No edit summary
    m (Text replace - "<syntaxhighlight lang="make">" to "<syntaxhighlight lang="cmake">")
    (19 intermediate revisions by 3 users not shown)
    Line 1: Line 1:
    This tutorial shows how to deal with functions provided by a script. It builds upon the [[Development/Tutorials/Kross/Hello World|Kross Hello World]] tutorial.
    This tutorial shows how to deal with functions provided by a script. This tutorial is based on the [[Development/Tutorials/Kross/Hello_World|Hello World]] tutorial and extends the codebase we wrote there with new functionality to outline how calling scripting functions could be done.


    == The source files ==
    Please note, that it is recommed to use [[Development/Tutorials/Kross/Connecting_Signals_and_slots_in_Kross#Autoconnecting_Signals_and_Slots| Autoconnected Signals and Slots]] if you just like to have a bunch of scripting functions within a script that should be called on demand. That way you have a clear interface with signals that are mapped transparent to scripting functions. The "trick" here is, that Kross will automaticly connect each signal a QObject has to a matching scripting function and at the C++ side all what is
    needed is to emit a signal and behind the scene the arguments will be
    translated and a possible defined scripting function got called. A good example here is [[Development/Tutorials/SuperKaramba|SuperKaramba]] which uses the signal+slot rather then callFunction() way. All it defines is the rather huge class that inherits QObject ([http://websvn.kde.org/trunk/KDE/kdeutils/superkaramba/src/karambainterface.h?view=markup karambainterface.h]). The signals within that class are transparent mapped to scripting functions (e.g. [http://websvn.kde.org/trunk/KDE/kdeutils/superkaramba/examples/template.py?view=markup| template.py] and [http://websvn.kde.org/trunk/KDE/kdeutils/superkaramba/examples/template.js?view=markup| template.js]) while the slots are then callable from within the scripting code.
    Signals and slots are faster and more type-safe then the in this tutorial used callFunction() (see also the [http://api.kde.org/4.x-api/kdelibs-apidocs/kross/html/classKross_1_1Action.html Kross::Action] class).


    This tutorial is based on the [[Development/Tutorials/Kross/Hello_World|Hello World]] tutorial and extends the codebase we wrote there with new functionality to outline how calling scripting functions could be done.
    == The C++ Code ==


    Please note, that it is recommed to use [[Development/Tutorials/Kross/Connecting_Signals_and_slots_in_Kross#Autoconnecting_Signals_and_Slots Autoconnected Signals and Slots]] if you just like to have a bunch of scripting functions within a script that should be called on demand. That way you have a clear interface with signals that are mapped transparent to scripting functions. The "trick" here is, that Kross will automaticly connect each signal a QObject has to a matching scripting function and at the C++ side all what is
    The following code is a KDE C++ project to demonstrate how to deal with scripting functions.
    needed is to emit a signal and behind the scene the arguments will be
    translated and a possible defined scripting function got called.


    === CMakeLists.txt ===
    === CMakeLists.txt ===
    Line 13: Line 14:
    We are using cmake to build our small sample project. The CMakeLists.txt file looks like;
    We are using cmake to build our small sample project. The CMakeLists.txt file looks like;


    <code>
    <syntaxhighlight lang="cmake">
    project (krosshello)
    project (krosshello)
    find_package(KDE4 REQUIRED)
    find_package(KDE4 REQUIRED)
    Line 20: Line 21:
    kde4_add_executable(krosshello ${krosshello_SRCS})
    kde4_add_executable(krosshello ${krosshello_SRCS})
    target_link_libraries(krosshello ${KDE4_KDEUI_LIBS} ${KDE4_KROSSUI_LIBS})
    target_link_libraries(krosshello ${KDE4_KDEUI_LIBS} ${KDE4_KROSSUI_LIBS})
    </code>
    </syntaxhighlight>


    === main.cpp ===
    === main.cpp ===
    Line 26: Line 27:
    The main.cpp does create the sample application and shows the mainwindow instance.
    The main.cpp does create the sample application and shows the mainwindow instance.


    <code cpp>
    <syntaxhighlight lang="cpp">
    #include <QString>
    #include <QString>
    #include <KApplication>
    #include <KApplication>
    Line 53: Line 54:
         return app.exec();
         return app.exec();
    }
    }
    </code>
    </syntaxhighlight>


    === mainwindow.h ===
    === mainwindow.h ===
    Line 59: Line 60:
    This is the main windows class which defines some displayed widgets for our small sample application.
    This is the main windows class which defines some displayed widgets for our small sample application.


    <code cpp>
    <syntaxhighlight lang="cpp">
    #ifndef MAINWINDOW_H
    #ifndef MAINWINDOW_H
    #define MAINWINDOW_H
    #define MAINWINDOW_H
    Line 75: Line 76:
             MainWindow(QWidget *parent=0);
             MainWindow(QWidget *parent=0);
         private Q_SLOTS:
         private Q_SLOTS:
             // This slot is called when the item in the combobox is changed.
             // This slot is called when the item in the
            // interpreter-combobox is changed.
             void interpreterActivated(const QString &);
             void interpreterActivated(const QString &);
         private:
         private:
    Line 85: Line 87:


    #endif
    #endif
    </code>
    </syntaxhighlight>


    === mainwindow.cpp ===
    === mainwindow.cpp ===


    The implementation of the main window functionality. We are displaying a QLineEdit that will be passed as first argument to a scripting function named "reverseString". Those function returns a string that will then displayed in a QLabel. Just like at the [[Development/Tutorials/Kross/Hello World|Kross Hello World]] tutorial, we also display a QComboBox that does allow to choose an interpreter. Though this sample does provide only one sample script written in JavaScript to demonstrate the usage.
    The implementation of the main window functionality. We are displaying a QLineEdit that will be passed as first argument to a scripting function named "reverseString". Those function returns a string that will then displayed in a QLabel. Just like at the [[Development/Tutorials/Kross/Hello World|Kross Hello World]] tutorial, we also display a QComboBox that does allow to choose an interpreter.


    <code cpp>
    <syntaxhighlight lang="cpp">
    #include "mainwindow.h"
    #include "mainwindow.h"
    #include <QVBoxLayout>
    #include <QVBoxLayout>
    Line 107: Line 109:
         foreach(QString s, Kross::Manager::self().interpreters())
         foreach(QString s, Kross::Manager::self().interpreters())
             cmbInterpreters->addItem(s);
             cmbInterpreters->addItem(s);
         connect(cmbInterpreters, SIGNAL(activated(const QString &)),
         connect(cmbInterpreters, SIGNAL(activated(const QString &)),
                 SLOT(interpreterActivated(const QString &)));
                 SLOT(interpreterActivated(const QString &)));
    Line 117: Line 118:
         setLayout(vLayout);
         setLayout(vLayout);


         // Create the Kross::Action instance and publish some
         // Create the Kross::Action instance .
        // QObject instances.
         action = new Kross::Action(this, "MyScript");
         action = new Kross::Action(this, "MyScript");
         action->addObject(txtInputString, "MyInputString");
     
         action->addObject(cmbInterpreters, "MyInterpreter");
        // We don't need to publish any QObject instances
         action->addObject(lblMessage, "MyLabel");
        // for this sample.
         //action->addObject(txtInputString, "MyInputString");
         //action->addObject(cmbInterpreters, "MyInterpreter");
         //action->addObject(lblMessage, "MyLabel");
    }
    }


    // this slot is called when the active item of the combobox changes.
    // this slot is called when the active item of the combobox changes.
    void MainWindow::interpreterActivated(const QString &strSelectedInterpreter)
    void MainWindow::interpreterActivated(const QString &interpr)
    {
    {
         // this time we are using external script files.
         // this time we are using external script files.
         // at this sample we are only using JavaScript but
         QString filename;
         // other supported backends will work well too.
         if(interpr == "python") // Python backend
         if(strSelectedInterpreter != "javascript") {
            filename = "Testscriptfile.py";
         else if(interpr == "javascript") // JavaScript backend
            filename = "Testscriptfile.js";
        else { // no other sample script files
             lblMessage->setText("-");
             lblMessage->setText("-");
             return;
             return;
    Line 137: Line 143:


         // set the script file that should be executed
         // set the script file that should be executed
         action->setFile("Testscriptfile.js");
         action->setFile(filename);


         // execute the scripting code, i.e. preload
         // execute the scripting code, i.e. preload
    Line 144: Line 150:
         // using callFunction() or before asking what
         // using callFunction() or before asking what
         // functions are available using functionNames().
         // functions are available using functionNames().
        // also it's only needed to trigger the script
        // once and then call whatever functions should
        // be called or signals emitted or whatever.
         action->trigger();
         action->trigger();


         // now we can call arbitrary functions
         // The list of arguments passed to the function
         QVariantList args;
         QVariantList args;


         // here we pass in the QLineEdit instance as argument.
         // here we pass in the QLineEdit instance
        // as first argument
         QVariant v;
         QVariant v;
         v.setValue( (QWidget*) txtInputString );
         v.setValue( (QWidget*) txtInputString );
    Line 157: Line 167:
         args << "Hello World";
         args << "Hello World";


         // Call the function
         // Call the arbitrary function
         QVariant result = action->callFunction("reverseString", args);
         QVariant result = action->callFunction("reverseString",args);


         // Use the returnvalue of the function call
         // Use the returnvalue of the function call
         lblMessage->setText(result.toString());
         lblMessage->setText(result.toString());
    }
    }
    </code>
    </syntaxhighlight>
     
    == The Script Files ==
     
    We are then able to use supported scripting backends like Python, Ruby and JavaScript to execute a scripting function named "reverseString" and called in the mainwindow.cpp file. The "reverseString" function has a QLineEdit and a QString as arguments and returns a QString.


    === Testscriptfile.js ===
    === Testscriptfile.js ===


    The following JavaScript file does provide us the reverseString function. This function will be executed at the mainwindow.cpp file.
    The Testscriptfile.js JavaScript file does provide us the reverseString scripting function.


    <code javascript>
    <syntaxhighlight lang="javascript">
    function reverseString(lineedit, s)
    function reverseString(lineedit, s)
    {
    {
         println("reverseString lineedit=" + lineedit + " s=" + s);
         println("reverseString lineedit=" + lineedit + " s=" + s);
        s = "JsReverse: " + s;


         lineedit.setText("Text to reverse: " +s);
         lineedit.setText(s);
         //MyInputString.text = "Text to reverse: " +s;
         //MyInputString.text = s;


         return s.split("").reverse().join("");
         return s.split("").reverse().join("");
    }
    }
    </code>
    </syntaxhighlight>
     
    === Testscriptfile.py ===
     
    The Testscriptfile.py Python file does provide us the reverseString scripting function.
     
    <syntaxhighlight lang="python">
    def reverseString(lineedit, s):
        print "reverseString lineedit=%s s=%s" % (lineedit,s)
        s = "PyReverse: %s" % s
        lineedit.setText(s)
        return s[::-1]
    </syntaxhighlight>

    Revision as of 10:19, 30 June 2011

    This tutorial shows how to deal with functions provided by a script. This tutorial is based on the Hello World tutorial and extends the codebase we wrote there with new functionality to outline how calling scripting functions could be done.

    Please note, that it is recommed to use Autoconnected Signals and Slots if you just like to have a bunch of scripting functions within a script that should be called on demand. That way you have a clear interface with signals that are mapped transparent to scripting functions. The "trick" here is, that Kross will automaticly connect each signal a QObject has to a matching scripting function and at the C++ side all what is needed is to emit a signal and behind the scene the arguments will be translated and a possible defined scripting function got called. A good example here is SuperKaramba which uses the signal+slot rather then callFunction() way. All it defines is the rather huge class that inherits QObject (karambainterface.h). The signals within that class are transparent mapped to scripting functions (e.g. template.py and template.js) while the slots are then callable from within the scripting code. Signals and slots are faster and more type-safe then the in this tutorial used callFunction() (see also the Kross::Action class).

    The C++ Code

    The following code is a KDE C++ project to demonstrate how to deal with scripting functions.

    CMakeLists.txt

    We are using cmake to build our small sample project. The CMakeLists.txt file looks like;

    project (krosshello)
    find_package(KDE4 REQUIRED)
    include_directories( ${KDE4_INCLUDES} )
    set(krosshello_SRCS main.cpp mainwindow.cpp)
    kde4_add_executable(krosshello ${krosshello_SRCS})
    target_link_libraries(krosshello ${KDE4_KDEUI_LIBS} ${KDE4_KROSSUI_LIBS})
    

    main.cpp

    The main.cpp does create the sample application and shows the mainwindow instance.

    #include <QString>
    #include <KApplication>
    #include <KAboutData>
    #include <KMessageBox>
    #include <KCmdLineArgs>
    #include <KLocalizedString>
    #include "mainwindow.h"
    
    int main (int argc, char *argv[]) {
        // Used to store information about a program.
        KAboutData aboutData("krosshello",
            0,ki18n("Kross Hello World"),"1.0",
    	ki18n("Hello World application for Kross"),
    	KAboutData::License_GPL,
    	ki18n("(c) 2007"),ki18n("Some text..."),
    	"http://kross.dipe.org","[email protected]");
        // Access to the command-line arguments.
        KCmdLineArgs::init( argc, argv, &aboutData );
        // Initialize the application.
        KApplication app;
        // Create and show the main window.
        MainWindow* window = new MainWindow();
        window->show();
        // Finally execute the application.
        return app.exec();
    }
    

    mainwindow.h

    This is the main windows class which defines some displayed widgets for our small sample application.

    #ifndef MAINWINDOW_H
    #define MAINWINDOW_H
    
    #include <QComboBox>
    #include <QLabel>
    #include <QLineEdit>
    #include <kross/core/action.h>
    
    // The main window to display our combobox and the label.
    class MainWindow : public QWidget
    {
        Q_OBJECT
        public:
            MainWindow(QWidget *parent=0);
        private Q_SLOTS:
            // This slot is called when the item in the
            // interpreter-combobox is changed.
            void interpreterActivated(const QString &);
        private:
            QLineEdit* txtInputString;
    	QLabel* lblMessage;
    	QComboBox* cmbInterpreters;
    	Kross::Action* action;
    };
    
    #endif
    

    mainwindow.cpp

    The implementation of the main window functionality. We are displaying a QLineEdit that will be passed as first argument to a scripting function named "reverseString". Those function returns a string that will then displayed in a QLabel. Just like at the Kross Hello World tutorial, we also display a QComboBox that does allow to choose an interpreter.

    #include "mainwindow.h"
    #include <QVBoxLayout>
    #include <QDebug>
    #include <kross/core/manager.h>
    #include <kross/core/action.h>
    
    // the constructor.
    MainWindow::MainWindow(QWidget *parent) : QWidget(parent)
    {
        txtInputString = new QLineEdit();
        lblMessage = new QLabel("Hello");
        cmbInterpreters = new QComboBox ();
        cmbInterpreters->addItem("Choose Interpreter", "");
        foreach(QString s, Kross::Manager::self().interpreters())
            cmbInterpreters->addItem(s);
        connect(cmbInterpreters, SIGNAL(activated(const QString &)),
                SLOT(interpreterActivated(const QString &)));
    
        QVBoxLayout *vLayout = new QVBoxLayout;
        vLayout->addWidget(cmbInterpreters);
        vLayout->addWidget(txtInputString);
        vLayout->addWidget(lblMessage);
        setLayout(vLayout);
    
        // Create the Kross::Action instance .
        action = new Kross::Action(this, "MyScript");
    
        // We don't need to publish any QObject instances
        // for this sample.
        //action->addObject(txtInputString, "MyInputString");
        //action->addObject(cmbInterpreters, "MyInterpreter");
        //action->addObject(lblMessage, "MyLabel");
    }
    
    // this slot is called when the active item of the combobox changes.
    void MainWindow::interpreterActivated(const QString &interpr)
    {
        // this time we are using external script files.
        QString filename;
        if(interpr == "python") // Python backend
            filename = "Testscriptfile.py";
        else if(interpr == "javascript") // JavaScript backend
            filename = "Testscriptfile.js";
        else { // no other sample script files
            lblMessage->setText("-");
            return;
        }
    
        // set the script file that should be executed
        action->setFile(filename);
    
        // execute the scripting code, i.e. preload
        // please note, that it's needed to trigger aka
        // execute the script before calling a function
        // using callFunction() or before asking what
        // functions are available using functionNames().
        // also it's only needed to trigger the script
        // once and then call whatever functions should
        // be called or signals emitted or whatever.
        action->trigger();
    
        // The list of arguments passed to the function
        QVariantList args;
    
        // here we pass in the QLineEdit instance
        // as first argument
        QVariant v;
        v.setValue( (QWidget*) txtInputString );
        args << v;
    
        // and the second argument is a string
        args << "Hello World";
    
        // Call the arbitrary function
        QVariant result = action->callFunction("reverseString",args);
    
        // Use the returnvalue of the function call
        lblMessage->setText(result.toString());
    }
    

    The Script Files

    We are then able to use supported scripting backends like Python, Ruby and JavaScript to execute a scripting function named "reverseString" and called in the mainwindow.cpp file. The "reverseString" function has a QLineEdit and a QString as arguments and returns a QString.

    Testscriptfile.js

    The Testscriptfile.js JavaScript file does provide us the reverseString scripting function.

    function reverseString(lineedit, s)
    {
        println("reverseString lineedit=" + lineedit + " s=" + s);
        s = "JsReverse: " + s;
    
        lineedit.setText(s);
        //MyInputString.text = s;
    
        return s.split("").reverse().join("");
    }
    

    Testscriptfile.py

    The Testscriptfile.py Python file does provide us the reverseString scripting function.

    def reverseString(lineedit, s):
        print "reverseString lineedit=%s s=%s" % (lineedit,s)
        s = "PyReverse: %s" % s
        lineedit.setText(s)
        return s[::-1]