View source for User:Dipesh/Kross-Tutorial

{{Improve}}

* [[Development/Languages/Kross|Kross Overview]]
* [http://kross.dipe.org Kross Homepage]

==Intro==

The purpose of this tutorial is to offer a step-by-step introduction how to integrate Kross into your application. While you can integrate Kross also in non-kpartified applications, it's easier to do with the KPart system. This tutorial will assume that you have a kpart application and what we will do is to go step by step through the process of creating a KPart plugin that integrates into your application and provides all the scripting. The scripting functionality is strictly separated from the application. The plugin that implements scripting is optional and the application does not need to know any details about what the plugin does.

This tutorial needs kdelibs4 based on Qt 4.2. While Kross and the KDE Javascript backend are included in kdelibs4, it is needed to compile kdebindings to install the Ruby and Python support.

The whole sourcecode we will produce within this tutorial could also be downloaded as [http://kross.dipe.org/kross2tutorial/kross2tutorial.tar.gz kross2tutorial.tar.gz] and contains all files needed to build a simple example that demonstrates how Kross could be used. Download and extract the tarball. Compile, install and run the kross2tutorialapp application and its kross2tutorial KPart plugin now with;
<pre>
cd src && mkdir _build && cd _build
cmake -DCMAKE_INSTALL_PREFIX=`kde4-config --prefix` ..
make
sudo make install
./kross2tutorialapp
</pre>

For additional examples where Kross is used you may also like to look at;
* [[Development/Tutorials/KWord Scripting|KWord Scripting]]
* [[Development/Tutorials/KSpread Scripting|KSpread Scripting]]
* [[Development/Tutorials/Krita Scripting|Krita Scripting]]

<!-- ################################################################################ //-->

==The application==

This section deals with the question how to integrate Kross into a KPart-application to
be able to extend your application with scripting.

For testing purposes we first create a simple KPart application. If you already have an application
you may like to skip this section and continue with the KPart Plugin.

Relevant files within the
[http://kross.dipe.org/kross2tutorial/kross2tutorial.tar.gz kross2tutorial.tar.gz] are;
<ul>
    <li>[http://kross.dipe.org/kross2tutorial/src/ src] directory
        <ul>
            <li>[http://kross.dipe.org/kross2tutorial/src/CMakeLists.txt CMakeLists.txt] for the cmake build system</li>
            <li>[http://kross.dipe.org/kross2tutorial/src/main.cpp main.cpp] create the KApplication and show the MainWindow</li>
            <li>[http://kross.dipe.org/kross2tutorial/src/mainwindow.h mainwindow.h]
                and [http://kross.dipe.org/kross2tutorial/src/mainwindow.cpp mainwindow.cpp]
                contains the top-level KParts::MainWindow implementation.</li>
            <li>[http://kross.dipe.org/kross2tutorial/src/plugin/ plugin] directory
                <ul>
                    <li>[http://kross.dipe.org/kross2tutorial/src/plugin/CMakeLists.txt CMakeLists.txt] for the cmake build system</li>
                    <li>[http://kross.dipe.org/kross2tutorial/src/plugin/CMakeLists.txt module.h]
                        and [http://kross.dipe.org/kross2tutorial/src/plugin/CMakeLists.txt module.cpp] implements the "KrossModuleTutorial" module</li>
                    <li>[http://kross.dipe.org/kross2tutorial/src/plugin/part.h part.h]
                        and [http://kross.dipe.org/kross2tutorial/src/plugin/part.cpp part.cpp] implements a KParts::ReadWritePart</li>
                </ul>
            </li>
        </ul>
    </li>
</ul>

===The CMake build system===

The [http://kross.dipe.org/kross2tutorial/src/CMakeLists.txt src/CMakeLists.txt] file;
<pre>
project(kross2tutorial)

find_package(KDE4 REQUIRED)
include(KDE4Defaults)
find_package(Perl REQUIRED)
add_definitions(${QT_DEFINITIONS}
  ${KDE4_DEFINITIONS} -DHAVE_CONFIG_H=1)
link_directories(${KDE4_LIB_DIR})
set(CMAKE_REQUIRED_DEFINITIONS
  ${_KDE4_PLATFORM_DEFINITIONS})
include_directories(${CMAKE_SOURCE_DIR}
  ${KDE4_KDECORE_INCLUDES} ${KDE4_INCLUDES}
  ${KDE4_KDEUI_INCLUDES}
  ${KDE4_KPARTS_INCLUDES})

add_subdirectory( plugin )

set(kross2tutorialapp_SRCS
  mainwindow.cpp main.cpp)
kde4_add_executable(kross2tutorialapp
  ${kross2tutorialapp_SRCS})
target_link_libraries(kross2tutorialapp
  ${KDE4_KDECORE_LIBS} ${KDE4_KDEUI_LIBS}
  kparts krosscore )
</pre>

The [http://kross.dipe.org/kross2tutorial/src/plugin/CMakeLists.txt src/plugin/CMakeLists.txt] file;
<pre>
include_directories(${CMAKE_SOURCE_DIR}
  ${KROSS_INCLUDES})
set(krossmoduletutorial_PART_SRCS
  module.cpp part.cpp)
kde4_add_plugin(krossmoduletutorial
  ${krossmoduletutorial_PART_SRCS})
target_link_libraries(krossmoduletutorial
  ${KDE4_KDECORE_LIBS} ${KDE4_KROSSCORE_LIBS}
  kparts )
install(TARGETS krossmoduletutorial
  DESTINATION ${PLUGIN_INSTALL_DIR})
install(FILES krossmoduletutorial.desktop
  DESTINATION ${SERVICES_INSTALL_DIR})
</pre>

===The KApplication===
The main function ([http://kross.dipe.org/kross2tutorial/src/main.cpp main.cpp]) creates the KApplication and shows the MainWindow.
<code cppqt>
int main(int argc, char **argv) {
  KAboutData about();
  KCmdLineArgs::init(argc,argv,&about);
  KApplication app();
  MainWindow *mainWin = new MainWindow();
  mainWin->show();
  return app.exec();
}
</code>

===The KPart main window===
The MainWindow class ([http://kross.dipe.org/kross2tutorial/src/main.cpp mainwindow.h]
[http://kross.dipe.org/kross2tutorial/src/main.cpp mainwindow.cpp]) contains the
top-level KParts::MainWindow implementation.
<code cppqt>
class MainWindow
    : public KParts::MainWindow
{
  public:
    MainWindow()
      : KParts::MainWindow()
    {
      KLibFactory* factory =
        KLibLoader::self()->factory(
          "krossmoduletutorial");
      KParts::ReadWritePart* part =
        dynamic_cast<KParts::ReadWritePart*>
          ( factory->create(this) );
      part->openUrl(
        KUrl("file:///path/myscript.py"));
    }
    virtual ~MainWindow() {}
};
</code>

<!-- ################################################################################ //-->

==The plugin==

===The KPart plugin===
The Part class ([http://kross.dipe.org/kross2tutorial/src/main.cpp part.h]
[http://kross.dipe.org/kross2tutorial/src/plugin/part.cpp part.cpp]) implements
a KParts::ReadWritePart.
<code cppqt>
class Part
  : public KParts::ReadWritePart
{
  public:
    Part(QWidget*, QObject* parent,
      const QStringList&)
      : KParts::ReadWritePart(parent)
      , m_guiclient(
          new Kross::GUIClient(this,this))
      , m_action(0) {}
    virtual ~Part() { delete m_action; }
    virtual bool openFile() {
      delete m_action;
      m_action = new Kross::Action(m_file);
      m_action->trigger();
    }
    virtual bool saveFile() {return false;}
  private:
    Kross::GUIClient* m_guiclient;
    Kross::Action* m_action;
};
</code>

===The Module===
The Module class ([http://kross.dipe.org/kross2tutorial/src/plugin/module.h module.h]
[http://kross.dipe.org/kross2tutorial/src/plugin/module.cpp module.cpp]) implements
the "KrossModuleTutorial" module.
<code cppqt>
class Module : public QObject {
  Q_OBJECT
  public:
    Module(Part* part=0)
      : QObject(part), m_widget(0) {}
    virtual ~Module() {}
  public slots:
    QWidget* widget() {
      if(m_widget) return m_widget;
      Part* part = 
        dynamic_cast<Part*>(parent());
      m_widget = new QWidget(
        part ? part->widget() : 0 );
      m_widget->setLayout(
        new QVBoxLayout(m_widget) );
      QWidget* w = 
        part ? part->widget() : 0;
      if(w && w->layout())
        w->layout()->addWidget(m_widget);
      m_widget->show();
      return m_widget;
    }
  private:
    QWidget* m_widget;
};
</code>

<!-- ################################################################################ //-->

==Samples==
Following sample scripts are also included in the
[http://kross.dipe.org/kross2tutorial/kross2tutorial.tar.gz kross2tutorial.tar.gz]
and should be executed using the "kross2tutorialapp" application.

===Python forms script===
The [http://kross.dipe.org/kross2tutorial/src/sample_forms.py sample_forms.py]
Python script demonstrates usage of into an application embedded Kross forms.
<code python>
#!/usr/bin/env kross
import Kross
import KrossModuleTutorial
forms = Kross.module("forms")
w = KrossModuleTutorial.widget()
l = forms.createWidget(w,"QLabel")
l.wordWrap = True
l.text = "The labels text."
b = forms.createWidget(w,"QPushButton")
def buttonClicked():
  global forms
  forms.showMessageBox("Information",
    "Caption", "the message text")
b.connect("clicked()", buttonClicked)
b.text = "Show messagebox"
</code>

===Python Tkinter script===
The [http://kross.dipe.org/kross2tutorial/src/sample_tkinter.py sample_tkinter.py]
Python script uses the Tkinter to show a modal dialog.
<code python>
#!/usr/bin/env kross
class TkTest:
  def __init__(self):
    import Tkinter
    self.root = Tkinter.Tk()
    self.root.title("TkTest")
    self.root.deiconify()
    self.mainframe =
      Tkinter.Frame(self.root)
    self.mainframe.pack()
    self.button1 = Tkinter.Button(
      self.mainframe,
      text="Button1",
      command=self.callback1)
    self.button1.pack(side=Tkinter.LEFT)
    self.root.mainloop()
  def callback1(self):
    import tkMessageBox
    tkMessageBox.showinfo(
      "Callback1", "Callback1 called.")
TkTest()
</code>

===Ruby forms script===
The [http://kross.dipe.org/kross2tutorial/src/sample_forms.rb sample_forms.rb]
Ruby script uses the Kross forms module to create and embedded a QLabel instance.
<code ruby>
#!/usr/bin/env kross
require 'Kross'
require 'KrossModuleTutorial'
forms = Kross.module("forms")
w = KrossModuleTutorial.widget()
l = forms.createWidget(w,"QLabel")
l.wordWrap = true
l.text = "Some labels text"
</code>

===JavaScript with KjsEmbed script===
The [http://kross.dipe.org/kross2tutorial/src/sample_forms.rb sample_kjsembed.js]
JavaScript script creates and embeddes a QFrame using KjsEmbed.
<code javascript>
#!/usr/bin/env kross
w = KrossModuleTutorial.widget()
var f = new Widget("QFrame", w);
f.frameShape = f.StyledPanel;
f.frameShadow = f.Sunken;
f.lineWidth = 4;
f.show();
</code>