1 files changed, 167 insertions, 0 deletions
diff --git a/doc/mapping/mapping.html.in b/doc/mapping/mapping.html.in
new file mode 100644
index 0000000..2a7c998
--- /dev/null
+++ b/doc/mapping/mapping.html.in
@@ -0,0 +1,167 @@
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN"
+    "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
+<html xmlns="http://www.w3.org/1999/xhtml" lang="en" xml:lang="en">
+<head>
+    <title>Seed C Mapping Conventions</title>
+    <meta http-equiv="Content-Type" content="text/html;charset=utf-8" />
+    <link rel="stylesheet" href="../style.css" type="text/css" charset="utf-8" />
+    <script type="text/javascript" src="../sh.js"></script>
+    <script type="text/javascript" src="../sh_js.js"></script>
+    <link type="text/css" rel="stylesheet" href="../sh.css" />
+    <style type="text/css">
+    div.section
+    {
+        font-weight: bold;
+    }
+    </style>
+
+</head>
+<body onload="sh_highlightDocument();">
+<div id="header">Seed C Mapping Conventions</div>
+<div id="subheader">v.@VERSION@</div>
+<div class="section">Enums and Flags</div>
+<p>
+The mapping of enum types to JavaScript is straightforward.
+</p>
+<div style="text-align: center;">
+<img src="./enum-mapping.png">
+</div>
+<p>
+In this example, <namespace>Gtk</namespace> is the namespace, <type>WindowType</type> is the enum class, and <member>NORMAL</member> 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.
+</p>
+
+<div class="section">Toplevel Functions</div>
+<p>
+Toplevel library functions are mapped exactly as you would expect, with <namespace>gtk</namespace>_<member>main</member> mapping to <namespace>Gtk</namespace>.<member>main</member>.
+</p>
+<div class="section">Constants</div>
+Constants are placed directly on the namespace, with the same casing as present in the C library.
+<pre style="javascript">
+<namespace>Clutter</namespace>.<member>COGL_FIXED_0_5</member>
+<namespace>Clutter</namespace>.<member>Alt_L</member>
+</pre>
+<div class="section">Objects</div>
+<p>
+Objects are given a constructor on the namespace. <namespace>Clutter</namespace><member>Texture</member> having a constructor at <namespace>Clutter</namespace>.<member>Texture</member>
+</p>
+<div class="subsection">Constructors</div>
+<p>
+Object constructors, accept as their only argument, a JavaScript object pairing GObject properties, with values.
+
+As an example,
+<pre class="javascript">
+w = new <namespace>Gtk</namespace>.<type>Window</type>({title: "Hello"});
+c = new <namespace>Clutter</namespace>.<type>Texture</type>({width: 300, height:300});
+</pre>
+All other properties are left to their default values. Note, <code><namespace>Gtk</namespace>.<type>Window</type>.<member>prototype</member></code> is the prototype of all <code><namespace>Gtk</namespace>.<type>Window</type></code> instances. It is also possible for objects to have "named" constructors which take specific arguments, i.e. for <code><namespace>clutter</namespace>_<type>texture</type>_new_<member>from_file</member</code> we have
+<pre class="javascript">t = new <namespace>Clutter</namespace>.<type>Texture</type>.<member>from_file</member>("/tmp/cat.png");</pre>
+
+In addition <code><namespace>gtk</namespace>_<type>window</type>_<member>new</member></code> maps to <code><namespace>Gtk</namespace>.<type>Window</type>.<member>c_new</member></code> (because <code>new</code> is a JavaScript keyword). This however is rarely used.
+</p>
+<div class="subsection">Methods & Static Methods </div>
+<p>
+Non static methods (or "instance" methods) are accessible from the object, as you would expect.
+<pre class="javascript">
+w = new <namespace>Gtk</namespace>.<type>Window</type>();
+w.<member>resize</member>(300, 300);
+</pre>
+
+Static methods are accessible from the constructor, so for <namespace>clutter</namespace>_<type>stage</type>_<member>get_default</member>.
+<pre class="javascript">
+c = <namespace>Clutter</namespace>.<type>Stage</type>.<member>get_default</member>();
+</pre>
+
+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.
+<pre class="javascript">
+w = new <namespace>Gtk</namespace>.<type>Window</type>();
+w.add (new <namespace>Gtk</namespace>.<type>VBox</type>());
+w.foreach(function (widget) {
+              print(widget);
+         });
+
+children = w.<member>get_children</member>();
+for (i in children) {
+    print(children[i]);
+}
+
+</pre>
+</p>
+<div class="subsection">Properties</div>
+<p>
+When attempting to set a property on an object, the following things happen in order.
+<ul>
+<li>If the property name corresponds to a GObject property name, then the JavaScript value is converted to a GValue and set as the property. </li>
+<li>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. </li>
+<li>The property name is set on the JavaScript object. </li>
+</ul>
+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 <code>null</code>, instead of throwing an exception.
+
+So, accessing for example <code>actor.wi<u>td</u>h</code> will return <code>null</code> and it is up to you to catch your typo.
+</p>
+<div class="subsection">Signals</div>
+<p>
+Interaction with an objects signals, takes place through the <code>object.signals</code> property. For example
+<pre class="javascript">
+w.signal.map.connect(function(window) {print ("Hello world");});
+foo.signal.bar.emit(3, 7, "Baz");
+</pre>
+In addition you can use <code>user_data</code>, similar to C
+<pre class="javascript">
+w.signal.map.connect(function(window, user_data) {print(user_data)},  "Hello world");
+</pre>
+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 <code>notify::x</code> however as this is not a valid JavaScript identifier, you have to use the array syntax for accessing properties, 
+<pre class="javascript">
+w.signal["notify::x"].connect(function(){print("x changed")});
+</pre>
+
+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 <code>--seed-debug=signal</code> or <code>--seed-debug=all</code>, Seed will give warnings when connections of improper arity are made (however clearly this is only sometimes a bug).
+
+</p>
+<div class="section">Structs and Unions</div>
+<p>
+Structs and Union's are given a constructor on the namespace. <namespace>Gdk</namespace><member>EventKey</member> simply having a constructor at <namespace>Gdk</namespace>.<member>EventKey</member>.
+</p>
+<div class="subsection">Constructors</div>
+<p>
+Struct and Union constructors, accept as their only argument, a pair of initialization parameters, in a similar fashion to object constructors.
+
+As an example,
+
+ <pre class="javascript">c = new <namespace>Clutter</namespace>.<type>Color</type>({red: 0xff, alpha: 0xff});</pre>
+
+All other fields are "zeroed" in the C sense that the memory is allocated with g_slice_alloc0.
+
+Like objects <code><namespace>Clutter</namespace>.<type>Color</type>.<member>prototype</member></code> is the prototype of all ClutterColor instances.
+
+Again like objects, structs can have "named" constructors which take specific arguments, i.e. for <code><namespace>soup</namespace>_<type>date</type>_new_<member>from_now</member></code>
+<pre class="javascript">d = new <namespace>Soup</namespace>.<type>Date</type>.<member>from_now</member>(0)</pre>
+
+Once again <code><namespace>soup</namespace>_<type>date</type>_<member>new</member></code> would map to <code><namespace>Soup</namespace>.<type>Date</type>.<member>c_new</member></code>.
+</p>
+<div class="subsection">Methods & Static Methods</div>
+<p>
+Non static methods are directly accessible from the object, i.e.
+<pre class="javascript">
+c = new <namespace>Clutter</namespace>.<type>Color</type>({red: 0xff, alpha: 0xff});
+c.<member>from_string</member>("purple");
+</pre>
+</p>
+<b>TODO: Static methods</b>
+<div class="subsection">Implicit creation</div>
+<p>
+Anywhere where a struct is expected, (property assignment, or a method call), a JavaScript object describing the struct can be used.
+<pre style="javascript">
+stage.<member>color</member> = {red: 0xff, blue: 0xcc, alpha: 0xff};
+</pre>
+The semantics are identical to constructors, in that uninitialized fields will be zeroed.
+</p>
+</body>
+</html>