User:Dipesh/Kross-Tutorial: Difference between revisions

From KDE TechBase
(Removed the "Introduction to Kross" part.)
(properly highlight the cpp, python, ruby, and js snippets using <code>)
Line 108: Line 108:
===The KApplication===
===The KApplication===
The main function ([http://kross.dipe.org/kross2tutorial/src/main.cpp main.cpp]) creates the KApplication and shows the MainWindow.
The main function ([http://kross.dipe.org/kross2tutorial/src/main.cpp main.cpp]) creates the KApplication and shows the MainWindow.
<pre>
<code cppqt>
int main(int argc, char **argv) {
int main(int argc, char **argv) {
   KAboutData about();
   KAboutData about();
Line 117: Line 117:
   return app.exec();
   return app.exec();
}
}
</pre>
</code>


===The KPart main window===
===The KPart main window===
Line 123: Line 123:
[http://kross.dipe.org/kross2tutorial/src/main.cpp mainwindow.cpp]) contains the
[http://kross.dipe.org/kross2tutorial/src/main.cpp mainwindow.cpp]) contains the
top-level KParts::MainWindow implementation.
top-level KParts::MainWindow implementation.
<pre>
<code cppqt>
class MainWindow
class MainWindow
     : public KParts::MainWindow
     : public KParts::MainWindow
Line 142: Line 142:
     virtual ~MainWindow() {}
     virtual ~MainWindow() {}
};
};
</pre>
</code>


<!-- ################################################################################ //-->
<!-- ################################################################################ //-->
Line 152: Line 152:
[http://kross.dipe.org/kross2tutorial/src/plugin/part.cpp part.cpp]) implements
[http://kross.dipe.org/kross2tutorial/src/plugin/part.cpp part.cpp]) implements
a KParts::ReadWritePart.
a KParts::ReadWritePart.
<pre>
<code cppqt>
class Part
class Part
   : public KParts::ReadWritePart
   : public KParts::ReadWritePart
Line 174: Line 174:
     Kross::Action* m_action;
     Kross::Action* m_action;
};
};
</pre>
</code>


===The Module===
===The Module===
Line 180: Line 180:
[http://kross.dipe.org/kross2tutorial/src/plugin/module.cpp module.cpp]) implements
[http://kross.dipe.org/kross2tutorial/src/plugin/module.cpp module.cpp]) implements
the "KrossModuleTutorial" module.
the "KrossModuleTutorial" module.
<pre>
<code cppqt>
class Module : public QObject {
class Module : public QObject {
   Q_OBJECT
   Q_OBJECT
Line 206: Line 206:
     QWidget* m_widget;
     QWidget* m_widget;
};
};
</pre>
</code>


<!-- ################################################################################ //-->
<!-- ################################################################################ //-->
Line 218: Line 218:
The [http://kross.dipe.org/kross2tutorial/src/sample_forms.py sample_forms.py]
The [http://kross.dipe.org/kross2tutorial/src/sample_forms.py sample_forms.py]
Python script demonstrates usage of into an application embedded Kross forms.
Python script demonstrates usage of into an application embedded Kross forms.
<pre>
<code python>
#!/usr/bin/env kross
#!/usr/bin/env kross
import Kross
import Kross
Line 234: Line 234:
b.connect("clicked()", buttonClicked)
b.connect("clicked()", buttonClicked)
b.text = "Show messagebox"
b.text = "Show messagebox"
</pre>
</code>


===Python Tkinter script===
===Python Tkinter script===
The [http://kross.dipe.org/kross2tutorial/src/sample_tkinter.py sample_tkinter.py]
The [http://kross.dipe.org/kross2tutorial/src/sample_tkinter.py sample_tkinter.py]
Python script uses the Tkinter to show a modal dialog.
Python script uses the Tkinter to show a modal dialog.
<pre>
<code python>
#!/usr/bin/env kross
#!/usr/bin/env kross
class TkTest:
class TkTest:
Line 261: Line 261:
       "Callback1", "Callback1 called.")
       "Callback1", "Callback1 called.")
TkTest()
TkTest()
</pre>
</code>


===Ruby forms script===
===Ruby forms script===
The [http://kross.dipe.org/kross2tutorial/src/sample_forms.rb sample_forms.rb]
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.
Ruby script uses the Kross forms module to create and embedded a QLabel instance.
<pre>
<code ruby>
#!/usr/bin/env kross
#!/usr/bin/env kross
require 'Kross'
require 'Kross'
Line 275: Line 275:
l.wordWrap = true
l.wordWrap = true
l.text = "Some labels text"
l.text = "Some labels text"
</pre>
</code>


===JavaScript with KjsEmbed script===
===JavaScript with KjsEmbed script===
The [http://kross.dipe.org/kross2tutorial/src/sample_forms.rb sample_kjsembed.js]
The [http://kross.dipe.org/kross2tutorial/src/sample_forms.rb sample_kjsembed.js]
JavaScript script creates and embeddes a QFrame using KjsEmbed.
JavaScript script creates and embeddes a QFrame using KjsEmbed.
<pre>
<code javascript>
#!/usr/bin/env kross
#!/usr/bin/env kross
w = KrossModuleTutorial.widget()
w = KrossModuleTutorial.widget()
Line 288: Line 288:
f.lineWidth = 4;
f.lineWidth = 4;
f.show();
f.show();
</pre>
</code>

Revision as of 11:12, 28 May 2007

Warning
This section needs improvements: Please help us to

cleanup confusing sections and fix sections which contain a todo


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 the KOffice2 libraries to install the Ruby and Python support (will be moved to kdebindings soon).

The whole sourcecode we will produce within this tutorial could also be downloaded as 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;

cd src && mkdir _build && cd _build
cmake -DCMAKE_INSTALL_PREFIX=`kde4-config --prefix` ..
make
sudo make install
./kross2tutorialapp

For additional examples where Kross is used you may also like to look at;


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 kross2tutorial.tar.gz are;

The CMake build system

The src/CMakeLists.txt file;

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_automoc(${kross2tutorialapp_SRCS})
kde4_add_executable(kross2tutorialapp
  ${kross2tutorialapp_SRCS})
target_link_libraries(kross2tutorialapp
  ${KDE4_KDECORE_LIBS} ${KDE4_KDEUI_LIBS}
  kparts krosscore )

The src/plugin/CMakeLists.txt file;

include_directories(${CMAKE_SOURCE_DIR}
  ${KROSS_INCLUDES})
set(krossmoduletutorial_PART_SRCS
  module.cpp part.cpp)
kde4_automoc(${krossmoduletutorial_PART_SRCS})
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})

The KApplication

The main function (main.cpp) creates the KApplication and shows the MainWindow. int main(int argc, char **argv) {

 KAboutData about();
 KCmdLineArgs::init(argc,argv,&about);
 KApplication app();
 MainWindow *mainWin = new MainWindow();
 mainWin->show();
 return app.exec();

}

The KPart main window

The MainWindow class (mainwindow.h mainwindow.cpp) contains the top-level KParts::MainWindow implementation. 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() {}

};


The plugin

The KPart plugin

The Part class (part.h part.cpp) implements a KParts::ReadWritePart. 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;

};

The Module

The Module class (module.h module.cpp) implements the "KrossModuleTutorial" module. 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;

};


Samples

Following sample scripts are also included in the kross2tutorial.tar.gz and should be executed using the "kross2tutorialapp" application.

Python forms script

The sample_forms.py Python script demonstrates usage of into an application embedded Kross forms.

  1. !/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"

Python Tkinter script

The sample_tkinter.py Python script uses the Tkinter to show a modal dialog.

  1. !/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()

Ruby forms script

The sample_forms.rb Ruby script uses the Kross forms module to create and embedded a QLabel instance.

  1. !/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"

JavaScript with KjsEmbed script

The sample_kjsembed.js JavaScript script creates and embeddes a QFrame using KjsEmbed.

  1. !/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();