# Kst Extensions

&kst; extensions are a powerful way to add functionality to &kst;. They can, for example, add elements to the &kst; user interface. They are usually designed to accomplish specific tasks which aren't of general use to the &kst; community.

To load or unload extensions in &kst;, select the Extensions... item from the Settings menu. A dialog will be presented which allows you to load or unload installed plugins.

Extensions Dialog

## The ELOG Extension

The ELOG extension allows event monitors to create logbook entries on a server running the Electronic Logbook (ELOG) application. The created logbook entries can be used, for example, to remotely monitor &kst; events or to produce periodic data reports. For information on configuring and maintaining an ELOG server, please see the official ELOG Homepage. To enable the ELOG extension in &kst;, select Extensions... from the Settings menu and ensure that ELOG Extension is checked.

### Server and Logging Settings

Server and logging settings should be configured if ELOG functionality is enabled for an event monitor object. To configure logging settings, click the Configure... button in the ELOG section of the Event Monitor dialog. The ELOG Event Entry dialog should be displayed:

Event Monitor Logging Settings
Event Monitor Logging Settings

Use the three checkboxes at the bottom to select the type of information to be logged. Include Kst capture specifies that a screen capture of the currently active window should be included in the entry. Include Kst configuration file specifies that `*.kst` save file should be attached to the entry. Finally, if Include Kst debugging information is checked, a copy of the debug log will be attached to the entry as well.

Additional fields will appear in this dialog once ELOG server settings are configured. To customize ELOG server settings, click the Configuration... button. The following dialog should be displayed:

Event Monitor Server Settings
Event Monitor Server Settings

Descriptions of the settings in this dialog follow.

Configuration, Save, and Load

  The Configuration drop down list contains a list of saved ELOG server configurations. To load a set of configuration settings, select an item from the list and click the Load button. To save the current configuration settings in this dialog into a slot, select the desired slot and click the Save button.

  Saving settings into a slot overwrites any existing settings in that slot.

IP address and Port number

  Enter the IP address of the machine running the ELOG server application. The port number that the ELOG server listens on is configurable through the server, but by default it is 8080, so if you are unsure, enter 8080 as the port number.

Logbook

  Each ELOG server can contain one or more logbooks, so the name of the logbook to write entries to must be specified. Ensure that the spelling of the logbook is correct.

User name, User password, and Write password

  Depending on the how the ELOG server application is configured, these settings may or may not be necessary. If they are, enter the correct login credentials in the appropriate textboxes.

Capture size

  Use this list box to select the size, in pixels, of the &kst; screen capture to attach (if specified).

Submit as HTML text

  If this checkbox is selected, HTML tags may be used in the logbook entry.

Suppress e-mail notification

  If the logbook is configured to send e-mail notifications of new entries, selecting this checkbox will disable the notifications. Note that this option is not related to &kst;'s own e-mail notification setting for event monitors.

Click the Apply button to apply the entered settings. Click Update to update the ELOG Event Entry dialog (the previous dialog). Additional fields should appear in the ELOG Event Entry dialog. These fields are unique to the selected logbook. Once you are satisfied with the settings, the Test button can be used to send a test logbook entry. Click Close to exit the dialog.

## KstScript

KstScript is a JavaScript binding for &kst;. It aims to offer full control over all aspects of &kst;. To enable KstScript, select Extensions... from the Settings menu and ensure that JavaScript Extension is checked.

### Running a KstScript

There are three ways to to run a KstScript.

- from the command line when starting &kst;:

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

- using kstcmd. kstcmd is a JavaScript interpreter which connects to your &kst; session. It can be run from an external terminal, or from within &kst; itself by selecting Show JavaScript Console from the Tools menu.

      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.

### KstScript Examples

KstScript gives &kst; a powerful programming interface. Chiefly, it can be used to construct 'smart' macro functions for common tasks. We will first look at a basic example illustrating how to control &kst; through KstScript, and then we will look at an example of a macro function.

#### A simple KstScript

Here we have the 'hello world' of KstScripts: plot a curve of random numbers.

    // simple.js: A simple KstScript demo.
    // Generates a new plot with a curve of random numbers.

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

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

    // create new (editable) vectors.
    // these could also be loaded from files.
    var xv = new Vector(); var yv = new Vector();

    xv.tagName = "time"; yv.tagName = "signal";

    // make their length 100.
    xv.resize(100); yv.resize(100);

    // fill in their values.
    for (var i = 0; i < 100; i++) {
            xv[i] = i; //index
            yv[i] = Math.random(); //uniformly distributed between 0 and 1.
    }

    // create a curve from x and y
    var c = new Curve(xv,yv);
    c.tagName = "signalvstime";

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

    // label the x-axis of our plot
    p.xAxis.label = "Time (s)"

This script can be run using any of the methods from . Here is a screenshot of &kst; after entering the commands using the embedded console method.

Simple Output

In the &kst; UI, objects are not labelled by the variable names which we use in our KstScript, but are are referred to by their Tag Name (or "Unique Name"). If you do not manually set the tagName attribute of new objects, then when you look things up in the data manager you will find cryptic names like "anonymous vector 1", or, "". This is the reason why we received several 'undefined' messages in the screenshot above. If you ever plan to use the UI to work with objects you have created with a KstScript, you will want to set their tagName property. You can also use tag names within KstScript itself. For example, after setting the tagName of our new curve we could have called

    p.curves.append("signalvstime");

#### Writing, Including, and Calling Functions

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

    function takeSpectraOfTimePlots() {
    //takes all of the plots in the first window which have an x-axis of "Time (s)"
     and generates power spectra for their curves, which it dumps into a single new
     plot.
            var w = Kst.windows[0];
            var p = new Plot(w);
            p.xAxis.label = "Frequency (Hz)"

            for (var ip = 0; ip < w.plots.length; ip++ ) {
                    cp = w.plots[ip]; //current plot
                    if (cp.xAxis.label == "Time (s)") {
                            for (ic = 0; ip < cp.curves.length; ic++) {
                                    plotSpectrum(p,cp.curves[ic].yVector)
                            }
                    }
            }
    }

    function plotSpectrum(p,v) {
    //creates a power spectrum for the vector v and displays it in plot p. assumes
    the vector is data sampled at 1Hz.
            ps = new PowerSpectrum(v, 1);
            ps.tagName = v.tagName + "-PS";
            c = new Curve(ps.xVector,ps.yVector);
            c.tagName = ps.tagName + "-C";
            p.curves.append(c);
    }

This example contains two functions: `takeSpectraOfTimePlots()` and `plotSpectrum(p,v)`. takeSpectraOfTimePlots() is a macro function which will generate spectra for all of the plots in the first window which have "Time (s)" as their x-axis. In this example, we can see the power of KstScript for such tasks.

The following script loads these routines from the `subroutines.js`. It uses the `simple.js` of the previous section to generate a noise plot with a time axis, and then calles takeSpectraOfTimePlots() to find its spectrum. 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');
    loadScript('simple.js');

    takeSpectraOfTimePlots();

A screenshot of &kst; after executing these commands is shown below.

CallSubs Output

### More KstScript Documentation

KstScript is still under development, and not all bindings have been implemented, but most of the basic functionality is present. KstScript development is need driven, and if you would like to see something specific included then a good place to ask is the &kst; development mailing list (see http://kst.kde.org). Documentation of the current KstScript bindings can be found in the `js` folder of the source distribution.