The mapping of enum types to JavaScript is straightforward.
In this example,
Toplevel library functions are mapped exactly as you would expect, with
Clutter .COGL_FIXED_0_5 Clutter .Alt_L
Objects are given a constructor on the namespace.
Object constructors, accept as their only argument, a JavaScript object pairing GObject properties, with values. As an example,
w = newAll other properties are left to their default values. Note,Gtk .Window ({title: "Hello"}); c = newClutter .Texture ({width: 300, height:300});
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. Gdk EventKey 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.