---

Framework for embedding the KJS Javascript Interpreter

Introduction

The KJSEmbed library provides a framework that makes it easy for applications to embed KJS, the KDE JavaScript interpreter. The facilities available include a JS console widget, a dialog loader and a binding between JS and the properties and slots of QObjects.

Important Classes

The most important classes to consider are:

KJSEmbed::KJSEmbedPart : Main API for KJSEmbed.

KJSEmbed::JSConsoleWidget : A widget that provides an interactive JS console.

KJSEmbed::JSObjectProxy : A Javascript object that can access the properties of a QObject,

KJSEmbed::SecurityPolicy : Defines a security policy for JSObjectProxy.

Basic Usage

The simplest way to use KJSEmbed is by simply creating a Javascript console widget. The console allows the user to enter and run arbitrary Javascript expressions.

    KJSEmbed::JSConsoleWidget *win = new KJSEmbed::JSConsoleWidget();
    win->show();
 

The embedding application can run scripts in the console using the execute() method.

The best way to use KJSEmbed is keep control of the interpreter yourself using the KJSEmbedPart, this way you can make parts of your application available to scripts. The following example creates its own interpreter then binds it to the console:

    KJSEmbed::KJSEmbedPart *js = new KJSEmbed::KJSEmbedPart();
    KJSEmbed::JSConsoleWidget *console = js->view();
 

Publishing QObjects

KJSEmbed allows applications to make arbitrary QObjects visible to a Javascript interpreter. The binding itself is provided by the JSProxyObject class, but is more easily used via the publish(...) methods of KJSEmbedPart.

The following code shows how easy it is to make an object available for scripting. It creates a QVBox containing two QLabels then makes them visible to KJSEmbed:

    QVBox *toplevel = new QVBox( 0, "box" );
    QLabel *title = new QLabel( "Some Title", toplevel, "title");
    QLabel *main = new QLabel( "Some text, more text.", toplevel, "main" );

    js->publish( title );
    js->publish( main, "text" );
 

Publishing an object makes it possibile for scripts to access both the properties and slots as if it was a normal Javascript object. The code above allows scripts read-write access to the label properties as this script illustrates:

    title.text = "World"
    title.text = "Hello " + title.text
 

The script above would set the text of the label to 'Hello World'.

The slots of a QObject bound to the interpreter are made available to scripts as if they normal methods. In the example above, we could conceal the label 'main' entirely by calling its hide() slot:

    main.hide()
 

Access To the QObject Tree

As well as providing script access to an individual widget, KJSEmbed allows scripts to walk the object tree and access others. If we modified the previous example to publish the QBox widget 'toplevel' as follows:

    js->publish( toplevel, "window" );
 

Then, despite the fact we've only explicitly published a single widget, we've also provided access to both 'main' and 'title'. The ability to navigate the object tree is limited by the SecurityPolicy, the default policy only allows scripts access to children of the published object.

To achieve the same result as before, we could use script like this:

    window.child("main").text = "World"
    window.child("main").text = "Hello " + window.child("main").text
 

The result of this script is identical to the previous example.

---