# The &kjs; Tutorial

Barth Netterfield

    kst@kde.org

2006 Barth Netterfield
2006-03-19
1.2.0

&kjs; is a JavaScript binding for &kst;. It offers full control over all aspects of &kst;

KDE kdeextragear Kst plotting plot JavaScript

## Running a KstScript

&kjs; is a JavaScript binding to &kst;. There are three ways to to run a &kjs;

- from the command line when starting &kst;:

      kst -E js:"loadScript('myscript.js')"

- using kstcmd

      kstcmd

      Attached to Kst session kst-17704
      kst> loadScript(myscript.js)

- from the menu once &kst; is loaded: File->LoadJavaScript

Note that with the first two methods, any KstScript command, or collection of KstScript commands can be substituted for the loadscript command.

## A simple KstScript

Here we have the 'hello world' of KstScripts: plot a curve from a file.

    // simple.js: A very simple KstScript demo: plot column 1 of a file vs line number

    // open the file "demodata.dat"
    file = new DataSource("demodata.dat");

    // grab the window
    var w = Kst.windows[0];

    // add a plot to the window
    var p = new Plot(w);

    // create the X vector which is the line number of the file
    var x = new DataVector(file,"INDEX");

    // create the Y vector, which is column 1
    var y = new DataVector(file,"1");

    // create a curve from x and y
    var c = new Curve(x,y);

    // put the curve in the plot
    p.curves.append(c);

This script plots column 1 of the file 'demodata.dat' vs line number. It can be run by any of the three methods from . For example,

    kst -E js:"loadScript('simple.js')"

Simple Output

## Tagnames and Variable names

In the simple script from , we refered to all of the objects we created by their KstScript names. This, however, is not how they are refered to from the Kst UI. In the UI, objects are refered to by their Tag Name (or "Unique Name"). The script above did not define the tag names of any of the objects we created (plots, vectors and curves), so if you try to look things up in the data manager, you will get cryptic names like "anonymous vector 1", or, for the curve, "". If you ever plan to use the UI to work with objects you have created with a KstScript, you will want to set their tag name:

    x.tagName = "xv"

Once you have set the tagName, you can use it to refer to the object as a parameter in the built in KstScript function calls. The following script does the same thing as the script in , except that it sets and refers to objects by their tagName.

    // very simple KstScript demo: plot a vector collumn from a file
    file = new DataSource("demodata.dat")

    var w = new Window;
    var p = new Plot(w);

    var x = new DataVector(file,"INDEX");
    x.tagName = "xv"

    var y = new DataVector(file,"1");
    y.tagName = "yv"

    var c = new Curve("xv","yv");
    c.tagName = "c"

    p.curves.append("c");

## Writing, Including, and Calling Subroutines

As with any JavaScript environment, you can write and call functions with KstScript. Additionally, KstScript posseses a means for a KstScript to load functions from disk. Consider the following example:

    // subroutines.js
    // plot a field from a datasource in a previously created plot
    function addField(plot, field, f0, n, datasource) {
      var x1 = new DataVector(datasource, "INDEX", f0, n);
      x1.tagName = "INDEX"
      var y1 = new DataVector(datasource, field, f0, n);
      y1.tagName=field
      var c1 = new Curve(x1, y1);
      c1.tagName = field
      plot.curves.append(c1)
      plot.topLabel =  plot.topLabel + field + " "
    }

    // create a plot and add a field curve to it.
    function plotField(field, f0, n, datasource) {
      var p1 = new Plot(Kst.windows[0]);
      p1.topLabel = "File: " + datasource.fileName + "   Fields: "
      addField(p1,field, f0, n, datasource);
      p1.xAxis.label = "Index"
      return p1
    }

This example contains two functions: `addField()` reads data from a datasource, makes a curve from it, and plots the curve in an exisiting plot. Additionally, it appends the field name to the top label. `plotField()` creates a new plot, plots a curve in it, and sets the X axis label, and top label.

The following script loads `subroutines.js`, and then uses `plotField()` and `addField()` to plot 3 columns of data from `demodata.dat`. Notice that `subroutines.js` is loaded using `loadScript()`, the same call that we used from the command line in .

    // callsubs.js
    // demonstrate calling subroutines

    loadScript('subroutines.js');

    file = new DataSource("demodata.dat");

    var p = plotField("1", 0, -1, file);
    addField(p, "2", 0, -1, file);
    addField(p, "3", 0, -1, file);

CallSubs Output