pas2js: docs: interfaces JS

git-svn-id: trunk@38711 -

utils/pas2js/docs/translation.html

@@ -1600,7 +1600,39 @@ function(){
 
     <div class="section">
     <h2 id="classinterfaces">Translating class interfaces</h2>
-    JavaScript has nothing like it, so they are emulated.
+    JavaScript has nothing like it, so they are emulated.<br>
+    An interfacetype is a JS-object with some hidden properties, containing
+    the GUID ($guid) and an array with the method names ($names). Here is how
+    IUnknown looks like in JS:<br>
+<pre>
+{
+  $module: [object Object],
+  $name: "IUnknown",
+  $fullname: "System.IUnknown",
+  $guid: "{00000000-0000-0000-C000-000000000046}",
+  $names: ["QueryInterface","_AddRef","_Release"],
+  $rtti: [object Object],
+  $kind: "com",
+}
+</pre>
+    A class implementing interfaces has a variable <i>$intfmaps</i>, which has
+    for each implemented GUID a map or delegator function. A map
+    is a JS instance of the interfacetype plus a for each method name a
+    function to call the class method. Here is an example map of <i>IUknown</i> of
+    <i>TInterfacedObject</i>:<br>
+<pre>
+ {
+  QueryInterface: function (){ return fn.apply(this.$o,arguments); },
+  _AddRef: function (){ return fn.apply(this.$o,arguments); },
+  _Release: function (){ return fn.apply(this.$o,arguments); },
+  ...
+}
+</pre>
+    When an interface is created for an object (here: a Pascal class instance),
+    for example by using the <i>as</i>-operator "<i>ObjVar as IUnknown</i>", a JS object is created, which
+    is an instance of the map object with its <i>$o</i> set to the <i>ObjVar</i>.<br>
+    <br>
+    Supported:
     <ul>
     <li>methods, properties, default property</li>
     <li><i>{$interfaces com|corba|default}</i><br>
@@ -1612,7 +1644,7 @@ function(){
       </ul>
       </li>
     <li>inheriting</li>
-    <li>GUIDs are simple string literals, TGUID = string.</li>
+    <li>Contrary to Delphi/FPC the GUIDs are simple string literals, TGUID = string.</li>
     <li>An interface without a GUID gets one autogenerated from its name and method names.</li>
     <li>a class implementing an interface must not be external</li>
     <li>a ClassType "supports" an interface, if it itself or one of its
@@ -1642,17 +1674,19 @@ function(){
           objfpc: can be unrelated, nil if not found,
           COM: if ObjVar has delegate uses _AddRef</li>
         <li>TJSObject(intfvar)</li>
+        <li>jsvalue(intfvar)</li>
       </ul>
     <li>Assign operator:</li>
       <ul>
-        <li>IntfVar:=nil</li>
-        <li>IntfVar:=IntfVar2 - IntfVar2 must be same type or a descendant</li>
-        <li>IntfVar:=ObjVar - nil if unsupported</li>
-        <li>jsvalue:=IntfVar</li>
+        <li>IntfVar:=nil;</li>
+        <li>IntfVar:=IntfVar2; - IntfVar2 must be same type or a descendant</li>
+        <li>IntfVar:=ObjVar; - nil if unsupported</li>
+        <li>jsvalue:=IntfVar;</li>
       </ul>
     <li>Assigned(IntfVar)</li>
     <li>RTTI</li>
     </ul>
+    Not yet supported: array of intferfacetype, interface as record member.
     </div>
 
     <div class="section">
@@ -1755,6 +1789,7 @@ function(){
     byte, ..., longword, enums, custom ranges are translated to a for loop.</li>
     <li>set types are translated to a for loop, while const sets and set variables are enumerated via a for(...in...) loop.</li>
     <li>string and array variables are enumerated via for loops.</li>
+    <li>for aString in ArrayOfString do ...</li>
     </ul>
     The class GetEnumerator function is translated like this:
     <table class="sample">
@@ -2754,7 +2789,6 @@ End.
     <li>Futures</li>
     <li>Helpers for types, classes, records</li>
     <li>Inline</li>
-    <li>Interfaces</li>
     <li>Library</li>
     <li>Nested classes</li>
     <li>Objects</li>