Seed Runtime Documentation

Seed Runtime
v.3.2.0
imports

An imports object is defined globally in every Seed context. This provides access to GObject Introspection namespaces, C extension modules, and other JavaScript files, as explained in the next three sections.

The default path to search for native modules and JavaScript files to be imported can be set as an array of strings on imports.searchPath:

    imports.searchPath.push("/opt/javascript");

This will add /opt/javascript as the last location to search when looking for native Seed modules and JavaScript files. The default search path includes the current directory and the directory into which Seed's default native modules are installed.

imports.gi

Provides access to all installed gobject-introspection namespaces. imports.gi.namespace will import functions and constructors from the given namespace and return an object providing them.

Importing is done once per process, and any subsequent accesses to the same namespace return the same object, and are very cheap as a result.

    Gtk = imports.gi.Gtk;
    Gtk.init(null, null);

A particular version of a namespace can be loaded by setting before it is first requested, by setting the imports.gi.versions.namespace object to a string representing the version number to load:

    imports.gi.versions.Clutter = "0.8";
    Clutter = imports.gi.Clutter; // The returned object represents clutter-0.8

Importing modules and JavaScript files

Native C modules and JavaScript files can be imported in a similar fashion, by accessing imports.file. Notice that the suffix (most likely .so or .js, respectively) is not included in the file name when requesting it, and keep this in mind when naming files.

First, if the file name is actually a directory, an object is returned that represents the contents of that directory, which behaves exactly as imports does in regards to importing native modules and JavaScript files. For example, say you have the directory js, which contains score.js:

    score = imports.js.score;

This will import score.js, just as described below.

If the file is not a directory, but happens to have your system's shared library suffix, the native module is loaded, and the module object is returned, similar to GObject Introspection namespace imports:

    readline = imports.readline;
    readline.readline(">");

Otherwise, Seed assumes that the file is a JavaScript file. If the file is found in the current path, it is evaluated (in a separate Seed context, so any state in the file it is imported from is not accessible), and the global object is returned. Keep in mind that it is possible to accidentally import a non-JavaScript file, as the extension is not taken into account.

Imagine we have the file test_file.js:

    test_string = "Hello, world!";

And another file, which we evaluate with seed:

    test_file = imports.test_file;
    print(test_file.test_string);

This will print "Hello, world!", as expected. Notice how, unlike in versions of Seed prior to 0.5, the file is not actually evaluated in the context of the importing file, so its toplevel objects are not globally available.

print(value)

Prints, to standard output, a representation of value. Number types are printed as floating-point values (with 6 decimal places); strings are printed as-is; objects are printed as `[object type]`.

    print(5);
    print("This is a test!".replace(" is ", " was "));

    var win = new Gtk.Window();
    print(win);

printf(format, ...)
Seed.sprintf(format, ...)

`printf` prints, to standard output, a string formatted as specified by format. Following format should be values to substitute, as in C's `printf`. Most standard printf format strings should work.

`sprintf` returns the string, instead of printing it.

    printf("A number: %d\n", 5);
    printf("One third is approximately %.3f\n", 1/3);
    printf("%d %s %d\n", 2, " is not ", 5);

    var my_string = Seed.sprintf("%d + %d = %d", 2, 3, 2+3);
    var my_name = printf("[%s] is %d characters long!\n",
                              my_string, my_string.length);

Seed.check_syntax(code)

Examines a segment of Javascript, looking for syntax errors. If errors are found, an exception is thrown, which can be caught with a try/catch block. You can examine the location of the syntax error with the line property of the returned exception.

    try{
        Seed.check_syntax("234[asdf");
    }
    catch(e){
        print("Something horrible happened on line " + e.line);
    }

Seed.stringify(object)

Returns a string representing the entire contents of object in a pretty-printed fashion, like that of JSON.

    proto = Seed.prototype(Gtk.Window);
    method = Seed.introspect(proto.translate_coordinates);
    print(Seed.stringify(method));

Seed.argv

An array representing the arguments passed to the `seed` interpreter.

Seed.quit(exitcode)

Terminates the execution of the Seed interpreter, returning exitcode as the exit value of the program.

object.signal.signame.connect(function, user_data)
object.connect(signame, function, user_data)

Connects function to the signal, signame, on object. Any GObject signal will work. If present, user_data is passed as the last argument to the callback.

    function button_clicked(){
        print("You pushed me!!");
    }

    var button = new Gtk.Button();
    button.signal.clicked.connect(button_clicked);

The second form is useful if you want to connect to detailed signals; for example, notify:: signals on an object's properties:

    function handle_opacity_change(obj, gobject, user_data){
        print("Window " + obj + "'s opacity was changed!");
    }

    win = new Gtk.Window();
    win.signal.connect("notify::opacity", handle_opacity_change);

Exceptions

Seed throws Javascript exceptions for errors in the GObject layer; our custom exception types are as follows:

- InvalidPropertyValue - a property was set to a value out of range
- PropertyError - a warning occurred in GLib while trying to set a property
- ArgumentError - a function was called with the wrong number of arguments
- ConversionError - one of the type conversion functions threw an exception
- TypeError - a required argument was of the wrong type
- SyntaxError - a syntax error was thrown from JavaScriptCore
- ParseError - a parsing error was thrown from JavaScriptCore (make sure you close all of your brackets!)

Exceptions are caught with the `try/catch` construct:

    try{
        var window = new Gtk.Window();
        window.opacity = "hello!";
    }
    catch(e){
        print("An exception occurred!");
    }

`e` is the name we've given the Exception object in this examle. The Exception object has a handful of properties which provide more information about the exception:

- name - the exception type
- message - the detailed message describing the exception
- line - the line on which the exception took place
- sourceURL - the source file, if any, in which the exception took place

Just as in Javascript, you can throw an exception manually with the throw function, passing it an object - either a new object, with the properties listed above (for consistency), or an arbitrary object:

    try{
        if(!http.connect("http://google.com"))
            throw { name: "HTTPConnectionError", message: "404 File Not Found" }
    }
    catch(e){
        // e.message = "404 File Not Found"
    }

Inheritance

JavaScript, being a prototypal language, rather than a class based language, has no strict inheritance model. A plethora of documentation can be found on the internet for implementing various inheritance models inside your program. However, a clear and common use case is to subclass GObjects, and Seed provides an interface to define and implement new GTypes.

Type Objects

To implement a new GType, an object describing the type is required.

    NewType = {
        parent: ParentTypeConstructor,
        name: "NewTypeName",
        class_init: function(klass, prototype){
        },
        instance_init: function(){
        }
    }

Indicates that the new type derives from ParentType, i.e. Gtk.Window, with name "NewTypeName". The class_init function is called when the class comes in to existence, and allows you to add to the prototype of objects constructed by the type. The instance_init function is called on the creation of each instance, with the "this" variable set to the new instance. An example type:

    HelloLabel = new GType({
        parent: Gtk.Label,
        name: "HelloLabel",
        class_init: function(klass, prototype){
            prototype.say_goodbye =
                                 function(){
                                     this.label = "Goodbye";
                                 }
        },
        instance_init: function(){
            this.label = "Hello"; // Hello Labels Always Say Hello.
        }
    });

Now to create an instance of the object:

    label = new HelloLabel();
    box.pack_start(label);
    label.show();
    label.say_goodbye();

The label inherits all the methods, signals, and properties of the Gtk.Label class and its parents, and internally has its own GType.

signal.emit(...)

emit provides the ability to arbitrarily emit any GObject signal, thus calling all of the functions which are connected to it. Any arguments passed to emit are passed on to the callback function.

    win = new Gtk.Window();
    win.signal.close.connect(Gtk.main_quit);
    win.signal.close.emit();

class.install_signal(signal_descriptor)

When creating a new GObject type within Seed, install_signal provides the ability to install new signals, which you can later emit with emit and can be connected to in any of the usual ways.

signal_descriptor is a Javascript object describing the signal. Important properties of signal_descriptor are:

- name — the name of the signal
- parameters — the types of any arguments the signal takes, as a Javascript array (optional)
- return_type — the expected return type of the signal handler (optional)

For example:

    HelloWindow = new GType({
        parent: Gtk.Window.type,
        name: "HelloWindow",
        signals: [{name: "hello",
                   parameters: [GObject.TYPE_INT,
                                GObject.TYPE_STRING],
                   return_type: Gtk.Window.type}];
    });

    w = new HelloWindow();

    w.signal.hello.connect(function(object, number, string){
                               print(number + " " + string);
                               return new Gtk.Window()
                           });

    print(w.signal.hello.emit(2, "Test"));