Developer Resources

Overview of the Scripting API

The scripting API in Kirix Strata™ utilizes classes to define a rich API for creating GUI elements, such as forms with a native look&feel, accessing and manipulating databases, interfacing with the web, and more.

The class categories divide roughly into classes used for basic language operations, classes for creating interfaces, classes for accessing and manipulating information, and classes for interacting with the system and host application.

Of course, the classes used for the basic language operations are the standard core JavaScript classes. In addition to this, the classes used for creating interfaces are the classes in the Application, Dialog, Form, Control, Layout, and Graphics categories. The classes used for accessing and manipulating information are the classes in the Input/Output, XML, DOM, Network, Database and Encryption categories. And finally, the classes used for interacting with the system and the host application are the classes in the System and Host Application categories.

Following is an overview of the major class categories as well as some of the important classes in each category:

Core

The Core class category contains the foundational classes and functions that are used to manipulate strings, numbers, dates, boolean values, arrays, and basic objects.

For example, with the String class, you can concatenate strings, split them up, extract substrings, or match and replace portions of strings. Or, with the Array class, you can store collections of Strings or Numbers, add or remove elements from these collections, sort these elements, or iterate through them, performing operations on each element.

Application

The Application category contains classes essential for creating and interacting with script-defined interfaces, and it contains both the Application class as well as the Event classes.

The Application class is responsible for starting and stopping the script event loop, which drives the user interface aspects of the program and coordinates the connection between the program code and the user's actions.

In practice, the Application class only needs to be called if the script needs to process events, and in this case, it should appear after the main form is created and shown, near the top of the script:

var a = new Form;
a.show();
Application.run();

While the Application class is responsible for the event loop, the Event class serves as the base class for the events that are actually processed, such as mouse events. The Event class contains functions for dispatching events as well as functions for connecting to the event so that when the event is dispatched, appropriate event handlers can be notified that the event has occurred, as well as receive information about the event.

Dialog

The dialog category of classes contains classes for creating stock dialogs. For example, using these classes, you can create dialogs for opening or saving files, entering text or passwords, or selecting colors.

While interfaces usually require the Application event to start the event loop, dialogs don't need the Application event loop to run.

So, to create a new file open dialog for selecting images, you might create a script like this:

// create a new file dialog object
var dlg = new FileDialog;

// show these file types in the file dialogs filter
dlg.setFilter("Bitmap Files|*.bmp|JPEG Images|*.jpg;*.jpeg");

// show the dialog, and accept the results only if the
// user presses Ok

if (dlg.showDialog() == DialogResult.Ok)
{
    var files = dlg.getPaths();

    for (var f in files)
        alert(files[f]);
}

Form

The Form category contains classes for creating top-level forms that contain other controls, as well as for creating and manipulating menu bars, toolbars, and status bars.

Control

The Control category contains classes for controls that are added to forms. With the classes in this category, you can add buttons, text controls, web controls, tree controls, list controls, and other important interface elements to your forms. In addition, by extending the FormControl class, you can create your own controls.

Here's an example that adds a button to a form and closes the form when the button is clicked:

// create an instance of our derived MyForm class
var f = new MyForm;
f.show();
Application.run();

// create our own class derived from Form
class MyForm extends Form
{
    function MyForm()
    {
        // call the constructor on the base class Form
        super("Button Example", 100, 100, 200, 100);
        
        // create a button and add the button to our form
        var button = new Button("Exit", 60, 20, 80, 24);
        this.add(button);
        
        // when the button is clicked, call the onButtonClicked
        // event handler on this class
        button.click.connect(this, onButtonClicked);
    }
    
    function onButtonClicked()
    {
        // when the button is clicked, exit the application
        Application.exit();
    }
}

Layout

The Layout category contains classes for laying our controls on a form.

Graphics

The Graphics category contains classes for drawing to the device context of a form.

Input/Output

The Input/Output category contains classes for reading and writing to text and binary files.

XML

The XML category contains a class for accessing information in XML.

Document Object Model (DOM)

The Document Object Model category contains classes for accessing and manipulating the document object model.

Network

The Network category contains classes for issuing HttpRequests as well as transferring data via FTP and SFTP.

Database

The database category of classes contains information for connecting to databases, such as Oracle, MySQL, or Strata's database, and interacting with the data inside the database. With classes in this category, you can connect to databases, create tables, and perform queries on the data, such as queries to select data from tables, insert new records into tables, delete records, as well as other standard database operations.

The main classes in the Database category are DbConnection and DbResult: DbConnection is used to connect to databases and execute SQL commands on the connected database. DbResult is used to iterate through whatever results are returned when the SQL is executed.

Here's an example that shows how to connect to Strata's database, and create a new table and select data from it:

// connect to local project database;
// HostApp.getDatabase() returns a DbConnection object
var db = HostApp.getDatabase();

// create a table
var result = db.execute("CREATE TABLE mytable (field1 VARCHAR(80));");

// add some rows
db.execute("
        INSERT INTO mytable (field1) VALUES ('111');
        INSERT INTO mytable (field1) VALUES ('222');
        INSERT INTO mytable (field1) VALUES ('333');
        ");

// update application's project tree (we do this
// so that the newly created table displays in the
// application project tree)
HostApp.refresh();

// select the rows and display the values
var result = db.execute("SELECT * FROM mytable");

while (result.next())
{
    alert(result.field1);
}

Encryption

The encryption category contains classes for encrypting strings. For example, you can perform use the Hash class to perform an MD5 hash as follows:

var text = "The hash of this text is: ";
alert(text + Hash.md5(text));

System

The System category contains classes for interacting with the computer on which the script is running. With classes in this category, you can find out information about system settings, such as system metrics, fonts, and colors. In addition, you can use it to load and access shared libraries, such as DLLs, SOs, and DYLIBs.

For example, here's how to show information about default system directories:

var output;

output += "Document Path: \t";
output += Environment.getDocumentsPath();
output += "\n";

output += "System Path: \t";
output += Environment.getSystemPath();
output += "\n";

output += "Temporary Path: \t";
output += Environment.getTempPath();
output += "\n\n";

alert(output);

Host Application

The Host Application category contains classes for interacting with the application in which the script is running. For example, if a Script is running inside Strata, the host application is Strata and using the Host Application category of classes, you are able to add items to menus, add forms to dockable panes, manipulate documents, and more.

For example, if you want to find out all the open documents, you might do the following:

// get all the host application's open documents, which 
// are returned by HostApp.getDocuments() as an array of 
// HostDocument objects
var g_all_documents;
g_all_documents = HostApp.getDocuments();

var g_all_locations = "The documents currently open are: \n\n";
for (var doc in g_all_documents)
{
    // for each open document, find the location
    var location;
    location = g_all_documents[doc].getLocation();
    g_all_locations += location + "\n";
}

// show the open locations
alert(g_all_locations);

Extensions

Strata extensions are stored and distributed as ".kxt" files. These are simply .zip files with a .kxt file extension. To put together a new .kxt file, start by creating an empty .zip file and add your script files, info.xml and any other resources into it. Finally, change the file extension from ".zip" to ".kxt".

In order for an extension to work, your .kxt file must contain at least two items:

info.xml - An XML file with the metadata for the extension. See an example of this type of file below.
main.js - A JavaScript file that contains the code you want to run when the extension loads.

In addition to the two required files listed above, .kxt files may also contain additional files:

As many Javascript source files as you'd like to include which may be referenced in your Javascript code. (Optional)
As many Extension resource files as you'd like to include which may be referenced in your Javascript code. To see how to reference Extension resource files in your Javascript code, see "Can I add bitmaps and text resources to an extension?". (Optional)
A bitmap file that will be shown in the Extension Manager in Kirix Strata. This bitmap file must be referenced in the <bitmap> tag in the "info.xml" file. (Optional)

The fields in this "info.xml" file are as follows:

<guid> Unique ID for the extension (generate using the extension wizard)
<name> Name shown in the Extensions panel in Kirix Strata.
<author> Author of the extension.
<bitmap> Bitmap shown in the Extensions panel in Kirix Strata.
<startup> Initial script file to be called when the extension is run.
<copyright> Copyright information for the extension.
<description> Description shown in the Extensions panel in Kirix Strata.
<major_version> Major version shown in the Extensions panel in Kirix Strata.
<minor_version> Minor version shown in the Extensions panel in Kirix Strata.
<subminor_version> Subminor version shown in the Extensions panel in Kirix Strata.

Here's what an example "info.xml" file would look like:

<?xml version="1.0">
<extension_info>
    <guid>{9642c44c-f790-4f16-9d46-fb54fc97d1a7}</guid>
    <name>Example Extension</name>
    <author>Example Industries, Inc.</author>
    <bitmap>icon.png</bitmap>
    <startup>main.js</startup>
    <copyright>(c) 2008 Example Industries, Inc.</copyright>
    <description>Example extension description goes here.</description>
    <major_version>1</major_version>
    <minor_version>0</minor_version>
    <subminor_version>0</subminor_version>
</extension_info>

After you've put together a .kxt file, you can add it to Strata by selecting Extensions from the Tools menu. An Extension Manager will appear; click the Add Extensions button to add your extension to the list. Going forward, every time Strata loads, it will automatically launch your extension and run the code you have in "main.js".

Developer's Guide

Check out our Developer's Guide to learn how to develop a new extension or edit an existing one.

About Us·Solutions·Terms of Use·Privacy Policy·Contact Us