Changes between Version 132 and Version 133 of WebKitIDL

Timestamp:

Aug 7, 2015, 5:01:49 AM (9 years ago)

Author:

calvaris@igalia.com

Comment:

--

WebKitIDL

@@ -13 +13 @@
  - [#Clamp Clamp(a,p)][[br]]
  - [#Custom Custom(m,a), CustomGetter(a), CustomSetter(a)][[br]]
+ - [#CustomBinding CustomBinding][[br]]
  - [#CallWith CallWith(m,a)][[br]]
  - [#StrictTypeChecking StrictTypeChecking(m,a,p)][[br]]
@@ -402 +403 @@
 Note: ObjC, GObject and CPP bindings do not support custom bindings.
 
+== `[CustomBinding]` == #CustomBinding
+
+Summary: They allow you to write bindings code even more manually than `[Custom]`.
+
+Usage: `[CustomBinding]` can be specified only on methods:
+{{{
+    [CustomBinding] void myMethod();
+}}}
+
+We should minimize the number of custom bindings as much as possible, since they are likely to be buggy.
+Before using `[CustomBinding]`, you should doubly consider if you really need custom bindings.
+You are recommended to modify code generators to avoid using `[CustomBinding]`.
+
+Before explaining the details, let us clarify the relationship of these IDL attributes.
+
+ * `[CustomBinding]` on a method indicates that you can write JavaScriptCore custom bindings for the method at a higher level than `[Custom]`.
+
+You can write custom bindings with JavaScriptCore for a method as follows:
+
+{{{
+    interface XXX {
+        [CustomBinding] void myMethod(int a, int b);
+    };
+}}}
+You can write custom bindings in WebCore/bindings/js/JSXXXCustom.cpp:
+{{{
+    EncodedJSValue JSC_HOST_CALL jsXXXPrototypeFunctionMyMethod(ExecState*)
+    {
+        // Read parameters manually if any.
+        // Get the called object from the ExecState if needed and wanted.
+        // Call the object and implementation if needed and wanted.
+        // Return a value.
+        return JSValue::encode(...);
+    }
+}}}
+Refer to WebCore/bindings/js/JSXXXCustom.cpp for more details.
+
+The main difference between `[Custom]` and `[CustomBinding]` is that `[Custom]` generates a `jsXXXPrototypeFunctionMyMethod` where it performs the parameters management, casting to the object and calls the `JSXXX::myMethod` with the parameters and the instance. With `[CustomBinding]`, the implementation of `jsXXXPrototypeFunctionMyMethod` is not done automatically and it is up to the developer to do all the parameter, casting and call operations.
+
+Note: ObjC, GObject and CPP bindings do not support `[CustomBinding]` bindings.
+
 == `[CallWith]`(m,a) == #CallWith