Changes between Version 26 and Version 27 of WebKitIDL


Ignore:
Timestamp:
Feb 13, 2012 10:30:12 PM (10 years ago)
Author:
haraken@chromium.org
Comment:

--

Legend:

Unmodified
Added
Removed
Modified
  • WebKitIDL

    v26 v27  
    124124=== * [Custom](m,a), [JSCustom](m,a), [V8Custom](m,a), [CustomGetter](a), [JSCustomGetter](a), [V8CustomGetter](a), [CustomSetter](a), [JSCustomSetter](a), [V8CustomSetter](a) ===
    125125
     126Summary: If your bindings require special (i.e. "custom") handling, you can write the bindings code as you like.
     127
     128Usage: [Custom], [JSCustom] and [V8Custom] can be specified on methods or attributes. [CustomGetter], [JSCustomGetter], [V8CustomGetter], [CustomSetter], [JSCustomSetter], [V8CustomSetter] can be specified on attributes, like this:
     129{{{
     130    [Custom] void func();
     131    attribute [CustomGetter, JSCustomSetter] DOMString str;
     132}}}
     133
     134Before explaining the details, let us clarify the relationship of these IDLs.
     135
     136 * [JSCustom] on a method indicates that you want to write JavaScriptCore custom bindings for the method.
     137 * [V8Custom] on a method indicates that you want to write V8 custom bindings for the method.
     138 * [Custom] on a method is equivalent to [JSCustom, V8Custom].
     139 * [JSCustomGetter] or [JSCustomSetter] on an attribute indicates that you want to write JavaScriptCore custom bindings for the attribute getter or setter.
     140 * [V8CustomGetter] or [V8CustomSetter] on an attribute indicates that you want to write V8 custom bindings for the attribute getter or setter.
     141 * [JSCustom] on an attribute is equivalent to [JSCustomGetter, JSCustomSetter].
     142 * [V8Custom] on an attribute is equivalent to [V8CustomGetter, V8CustomSetter].
     143 * [Custom] on an attribute is equivalent to [JSCustom, V8Custom], i.e. [JSCustomGetter, JSCustomSetter, V8CustomGetter, V8CustomSetter].
     144
     145For 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].
     146
     147How to write custom bindings are different between JavaScriptCore and V8 or between a method and an attribute getter/setter.
     148
     149 * JavaScriptCore method
     150Consider the following example:
     151{{{
     152    interface XXX {
     153        [JSCustom] void func(in int a, in int b);
     154    }
     155}}}
     156You need to prepare WebCore/bindings/js/JSXXXCustom.cpp and write custom bindings, like this:
     157{{{
     158    EncodedJSValue JSC_HOST_CALL jsXXXPrototypeFunctionCustomMethod(ExecState* exec)
     159    {
     160        ...;
     161    }
     162}}}
     163Please refer to WebCore/bindings/js/JSXXXCustom.cpp for more details.
     164
     165 * JavaScriptCore attribute getter
     166Consider the following example:
     167{{{
     168    interface XXX {
     169        attribute [JSCustomGetter] DOMString str;
     170    }
     171}}}
     172You need to prepare WebCore/bindings/js/JSXXXCustom.cpp and write custom bindings, like this:
     173{{{
     174    JSValue jsXXXCustomAttr(ExecState* exec, JSValue slotBase, const Identifier&)
     175    {
     176        ...;
     177    }
     178}}}
     179Please refer to WebCore/bindings/js/JSXXXCustom.cpp for more details.
     180
     181 * JavaScriptCore attribute setter
     182Consider the following example:
     183{{{
     184    interface XXX {
     185        attribute [JSCustomSetter] DOMString str;
     186    }
     187}}}
     188You need to prepare WebCore/bindings/js/JSXXXCustom.cpp and write custom bindings, like this:
     189{{{
     190    void setJSXXXCustomAttr(ExecState* exec, JSObject* thisObject, JSValue value)
     191    {
     192        ...;
     193    }
     194}}}
     195Please refer to WebCore/bindings/js/JSXXXCustom.cpp for more details.
     196
     197 * V8 method
     198Consider the following example:
     199{{{
     200    interface XXX {
     201        [V8Custom] void func(in int a, in int b);
     202    }
     203}}}
     204You need to prepare WebCore/bindings/v8/custom/V8XXXCustom.cpp and write custom bindings in the following signature:
     205{{{
     206    v8::Handle<v8::Value> V8XXX::funcCallback(const v8::Arguments& args)
     207    {
     208        ...;
     209    }
     210}}}
     211Please refer to WebCore/bindings/v8/custom/V8XXXCustom.cpp for more details.
     212
     213 * V8 attribute getter
     214Consider the following example:
     215{{{
     216    interface XXX {
     217        attribute [V8CustomGetter] DOMString str;
     218    }
     219}}}
     220You need to prepare WebCore/bindings/v8/custom/V8XXXCustom.cpp and write custom bindings in the following signature:
     221{{{
     222   
     223    {
     224        ...;
     225    }
     226}}}
     227Please refer to WebCore/bindings/v8/custom/V8XXXCustom.cpp for more details.
     228
     229 * V8 attribute setter
     230Consider the following example:
     231{{{
     232    interface XXX {
     233        [V8Custom] void func(in int a, in int b);
     234    }
     235}}}
     236You need to prepare WebCore/bindings/v8/custom/V8XXXCustom.cpp and write custom bindings in the following signature:
     237{{{
     238    v8::Handle<v8::Value> V8XXX::funcCallback(const v8::Arguments& args)
     239    {
     240        ...;
     241    }
     242}}}
     243Please refer to WebCore/bindings/v8/custom/V8XXXCustom.cpp for more details.
     244
     245We should minimize the number of custom bindings as less as possible. Before using [Custom], you should doubly consider if you really need custom bindings.
     246
     247Note: ObjC, GObject and CPP bindings do not support custom bindings.
     248
    126249=== * [CallWith](m,a) ===
    127250
    128 Summary: With [CallWith], a WebCore method is called with additional information.
     251Summary: It calls a WebCore method with additional information.
    129252
    130253Usage: The possible usage is [CallWith=X1|X2|X3|...], where X1, X2, X3, ... is "ScriptExecutionContext", "ScriptState", "ScriptArguments" or "CallStack".
     
    284407On the other hand, [V8OnProto] indicates that the attribute getter/setter or the method should be defined on a chain.
    285408
    286 Note: As explained above, the current implementation of JSC and V8 is wrong to the Web IDL spec,
     409Note: As explained above, the current implementation of JSC and V8 is wrong with the Web IDL spec,
    287410and [V8Unforgeable] and [V8OnProto] are used for hack.
    288411You should not use them unless you have a strong reason to use them.