Seed C Mapping Conventions
v.3.2.0
Enums and Flags

The mapping of enum types to JavaScript is straightforward.

In this example, Gtk is the namespace, WindowType is the enum class, and NORMAL is the enum member. Note that the enum member is always UPPERCASE, and the enum class is CasedLikeTypes. It is worth noting that this is the same convention as Vala. When passing enums in to functions, the enum will be checked (to ensure it is in fact a value of the required enum class). This is not true for fields.

Toplevel Functions

Toplevel library functions are mapped exactly as you would expect, with gtk_main mapping to Gtk.main.

Constants
Constants are placed directly on the namespace, with the same casing as present in the C library.

    Clutter.COGL_FIXED_0_5
    Clutter.Alt_L

Objects

Objects are given a constructor on the namespace. Clutter Texture having a constructor at Clutter.Texture

Constructors

Object constructors, accept as their only argument, a JavaScript object pairing GObject properties, with values. As an example,

    w = new Gtk.Window({title: "Hello"});
    c = new Clutter.Texture({width: 300, height:300});

All other properties are left to their default values. Note, `Gtk.Window.prototype` is the prototype of all `Gtk.Window` instances. It is also possible for objects to have "named" constructors which take specific arguments, i.e. for `clutter_texture_new_from_file we have

    t = new Clutter.Texture.from_file("/tmp/cat.png");

In addition `gtk_window_new` maps to `Gtk.Window.c_new` (because `new` is a JavaScript keyword). This however is rarely used.
Methods & Static Methods

Non static methods (or "instance" methods) are accessible from the object, as you would expect.

    w = new Gtk.Window();
    w.resize(300, 300);

Static methods are accessible from the constructor, so for clutter_stage_get_default.

    c = Clutter.Stage.get_default();

The type conversion, is fairly sophisticated, so where C methods expect non-basic types, like function pointers, GLists, or C arrays, you are able to just pass in JavaScript functions and arrays.

    w = new Gtk.Window();
    w.add (new Gtk.VBox());
    w.foreach(function (widget) {
                  print(widget);
             });

    children = w.get_children();
    for (i in children) {
        print(children[i]);
    }

Properties

When attempting to set a property on an object, the following things happen in order.

- If the property name corresponds to a GObject property name, then the JavaScript value is converted to a GValue and set as the property.
- If the property name corresponds to a member of the objects struct (i.e. the GtkWindow struct), the JavaScript value is set inside the struct.
- The property name is set on the JavaScript object.

and vice versa for reading properties. One thing which may be surprising to developers used to other scripting languages (say, python) is that an attempt to access an unset property will just return `null`, instead of throwing an exception. So, accessing for example `actor.witdh` will return `null` and it is up to you to catch your typo.
Signals

Interaction with an objects signals, takes place through the `object.signals` property. For example

    w.signal.map.connect(function(window) {print ("Hello world");});
    foo.signal.bar.emit(3, 7, "Baz");

In addition you can use `user_data`, similar to C

    w.signal.map.connect(function(window, user_data) {print(user_data)},  "Hello world");

In many cases this is made useless by JavaScript's support for closures. Note, in many cases, it is useful to access signals with details, for example `notify::x` however as this is not a valid JavaScript identifier, you have to use the array syntax for accessing properties,

    w.signal["notify::x"].connect(function(){print("x changed")});

Sometimes, it may be desirable to check that the functions you are connecting to signals, have the correct arity (accept the proper number of argmuents), and if you compile Seed with debugging enabled, and pass `--seed-debug=signal` or `--seed-debug=all`, Seed will give warnings when connections of improper arity are made (however clearly this is only sometimes a bug).
Structs and Unions

Structs and Union's are given a constructor on the namespace. GdkEventKey simply having a constructor at Gdk.EventKey.

Constructors

Struct and Union constructors, accept as their only argument, a pair of initialization parameters, in a similar fashion to object constructors. As an example,

    c = new Clutter.Color({red: 0xff, alpha: 0xff});

All other fields are "zeroed" in the C sense that the memory is allocated with g_slice_alloc0. Like objects `Clutter.Color.prototype` is the prototype of all ClutterColor instances. Again like objects, structs can have "named" constructors which take specific arguments, i.e. for `soup_date_new_from_now`

    d = new Soup.Date.from_now(0)

Once again `soup_date_new` would map to `Soup.Date.c_new`.
Methods & Static Methods

Non static methods are directly accessible from the object, i.e.

    c = new Clutter.Color({red: 0xff, alpha: 0xff});
    c.from_string("purple");

TODO: Static methods
Implicit creation

Anywhere where a struct is expected, (property assignment, or a method call), a JavaScript object describing the struct can be used.

    stage.color = {red: 0xff, blue: 0xcc, alpha: 0xff};

The semantics are identical to constructors, in that uninitialized fields will be zeroed.`