Changes between Version 26 and Version 27 of WebKitIDL

Timestamp:

Feb 13, 2012 10:30:12 PM (12 years ago)

Author:

haraken@chromium.org

Comment:

--

WebKitIDL

@@ -124 +124 @@
 === * [Custom](m,a), [JSCustom](m,a), [V8Custom](m,a), [CustomGetter](a), [JSCustomGetter](a), [V8CustomGetter](a), [CustomSetter](a), [JSCustomSetter](a), [V8CustomSetter](a) ===
 
+Summary: If your bindings require special (i.e. "custom") handling, you can write the bindings code as you like.
+
+Usage: [Custom], [JSCustom] and [V8Custom] can be specified on methods or attributes. [CustomGetter], [JSCustomGetter], [V8CustomGetter], [CustomSetter], [JSCustomSetter], [V8CustomSetter] can be specified on attributes, like this:
+{{{
+    [Custom] void func();
+    attribute [CustomGetter, JSCustomSetter] DOMString str;
+}}}
+
+Before explaining the details, let us clarify the relationship of these IDLs.
+
+ * [JSCustom] on a method indicates that you want to write JavaScriptCore custom bindings for the method.
+ * [V8Custom] on a method indicates that you want to write V8 custom bindings for the method.
+ * [Custom] on a method is equivalent to [JSCustom, V8Custom].
+ * [JSCustomGetter] or [JSCustomSetter] on an attribute indicates that you want to write JavaScriptCore custom bindings for the attribute getter or setter.
+ * [V8CustomGetter] or [V8CustomSetter] on an attribute indicates that you want to write V8 custom bindings for the attribute getter or setter.
+ * [JSCustom] on an attribute is equivalent to [JSCustomGetter, JSCustomSetter].
+ * [V8Custom] on an attribute is equivalent to [V8CustomGetter, V8CustomSetter].
+ * [Custom] on an attribute is equivalent to [JSCustom, V8Custom], i.e. [JSCustomGetter, JSCustomSetter, V8CustomGetter, V8CustomSetter].
+
+For example, if you want to write custom bindings only for an attribute getter of JavaScriptCore and V8 and an attribute setter of JavaScriptCore, you can specify [CustomGetter, JSCustomSetter].
+
+How to write custom bindings are different between JavaScriptCore and V8 or between a method and an attribute getter/setter.
+
+ * JavaScriptCore method
+Consider the following example:
+{{{
+    interface XXX {
+        [JSCustom] void func(in int a, in int b);
+    }
+}}}
+You need to prepare WebCore/bindings/js/JSXXXCustom.cpp and write custom bindings, like this:
+{{{
+    EncodedJSValue JSC_HOST_CALL jsXXXPrototypeFunctionCustomMethod(ExecState* exec)
+    {
+        ...;
+    }
+}}}
+Please refer to WebCore/bindings/js/JSXXXCustom.cpp for more details.
+
+ * JavaScriptCore attribute getter
+Consider the following example:
+{{{
+    interface XXX {
+        attribute [JSCustomGetter] DOMString str;
+    }
+}}}
+You need to prepare WebCore/bindings/js/JSXXXCustom.cpp and write custom bindings, like this:
+{{{
+    JSValue jsXXXCustomAttr(ExecState* exec, JSValue slotBase, const Identifier&)
+    {
+        ...;
+    }
+}}}
+Please refer to WebCore/bindings/js/JSXXXCustom.cpp for more details.
+
+ * JavaScriptCore attribute setter
+Consider the following example:
+{{{
+    interface XXX {
+        attribute [JSCustomSetter] DOMString str;
+    }
+}}}
+You need to prepare WebCore/bindings/js/JSXXXCustom.cpp and write custom bindings, like this:
+{{{
+    void setJSXXXCustomAttr(ExecState* exec, JSObject* thisObject, JSValue value)
+    {
+        ...;
+    }
+}}}
+Please refer to WebCore/bindings/js/JSXXXCustom.cpp for more details.
+
+ * V8 method
+Consider the following example:
+{{{
+    interface XXX {
+        [V8Custom] void func(in int a, in int b);
+    }
+}}}
+You need to prepare WebCore/bindings/v8/custom/V8XXXCustom.cpp and write custom bindings in the following signature:
+{{{
+    v8::Handle<v8::Value> V8XXX::funcCallback(const v8::Arguments& args)
+    {
+        ...;
+    }
+}}}
+Please refer to WebCore/bindings/v8/custom/V8XXXCustom.cpp for more details.
+
+ * V8 attribute getter
+Consider the following example:
+{{{
+    interface XXX {
+        attribute [V8CustomGetter] DOMString str;
+    }
+}}}
+You need to prepare WebCore/bindings/v8/custom/V8XXXCustom.cpp and write custom bindings in the following signature:
+{{{
+    
+    {
+        ...;
+    }
+}}}
+Please refer to WebCore/bindings/v8/custom/V8XXXCustom.cpp for more details.
+
+ * V8 attribute setter
+Consider the following example:
+{{{
+    interface XXX {
+        [V8Custom] void func(in int a, in int b);
+    }
+}}}
+You need to prepare WebCore/bindings/v8/custom/V8XXXCustom.cpp and write custom bindings in the following signature:
+{{{
+    v8::Handle<v8::Value> V8XXX::funcCallback(const v8::Arguments& args)
+    {
+        ...;
+    }
+}}}
+Please refer to WebCore/bindings/v8/custom/V8XXXCustom.cpp for more details.
+
+We should minimize the number of custom bindings as less as possible. Before using [Custom], you should doubly consider if you really need custom bindings.
+
+Note: ObjC, GObject and CPP bindings do not support custom bindings.
+
 === * [CallWith](m,a) ===
 
-Summary: With [CallWith], a WebCore method is called with additional information.
+Summary: It calls a WebCore method with additional information.
 
 Usage: The possible usage is [CallWith=X1|X2|X3|...], where X1, X2, X3, ... is "ScriptExecutionContext", "ScriptState", "ScriptArguments" or "CallStack".
@@ -284 +407 @@
 On the other hand, [V8OnProto] indicates that the attribute getter/setter or the method should be defined on a chain.
 
-Note: As explained above, the current implementation of JSC and V8 is wrong to the Web IDL spec,
+Note: As explained above, the current implementation of JSC and V8 is wrong with the Web IDL spec,
 and [V8Unforgeable] and [V8OnProto] are used for hack.
 You should not use them unless you have a strong reason to use them.