Changes between Version 47 and Version 48 of WebKitIDL


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

--

Legend:

Unmodified
Added
Removed
Modified

  • WebKitIDL

    v47 v48  
    112112= Overview = #Overview
    113113
    114 The [http://www.w3.org/TR/WebIDL/ Web IDL] is a language that defines how WebCore interfaces are bound to external languages such as JavaScriptCore, V8, ObjC, GObject and CPP. We need to write IDL files (e.g. XMLHttpRequest.idl, Element.idl, etc) to expose WebCore interfaces to those external languages. When WebKit is built, the IDL files are parsed, and the code to bind WebCore implementations and JavaScriptCore/V8/ObjC/GObject/CPP interfaces is automatically generated.
    115 
    116 This page describes practical information about how the IDL binding works and how we can write IDL files in WebKit. The syntax of IDL files is fairly well documented in the [http://www.w3.org/TR/WebIDL/ Web IDL spec], but it is too formal to read:-) and there are several differences between the Web IDL spec and the WebKit IDL due to implementation issues.
     114The [http://www.w3.org/TR/WebIDL/ Web IDL] is a language that defines how WebCore interfaces are bound to external languages such as JavaScriptCore, V8, ObjC, GObject and CPP. You need to write IDL files (e.g. XMLHttpRequest.idl, Element.idl, etc) to expose WebCore interfaces to those external languages. When WebKit is built, the IDL files are parsed, and the code to bind WebCore implementations and JavaScriptCore/V8/ObjC/GObject/CPP interfaces is automatically generated.
     115
     116This page describes practical information about how the IDL binding works and how you can write IDL files in WebKit. The syntax of IDL files is fairly well documented in the [http://www.w3.org/TR/WebIDL/ Web IDL spec], but it is too formal to read:-) and there are several differences between the Web IDL spec and the WebKit IDL due to implementation issues.
    117117
    118118= Basics of IDL = #Basics
    … …  
    342342
    343343 * Method in JavaScriptCore: Consider the following example:
     344
    344345{{{
    345346    interface XXX {
    … …  
    357358
    358359 * Attribute getter in JavaScriptCore: Consider the following example:
     360
    359361{{{
    360362    interface XXX {
    … …  
    372374
    373375 * Attribute setter in JavaScriptCore: Consider the following example:
     376
    374377{{{
    375378    interface XXX {
    … …  
    387390
    388391 * Method in V8: Consider the following example:
     392
    389393{{{
    390394    interface XXX {
    … …  
    402406
    403407 * Attribute getter in V8: Consider the following example:
     408
    404409{{{
    405410    interface XXX {
    … …  
    417422
    418423 * Attribute setter in V8: Consider the following example:
     424
    419425{{{
    420426    interface XXX {
    … …  
    502508For example, consider the case where node.firstChild is accessed:
    503509
    504  * Node::firstChild() is called
    505  * The result is passed to toJS() or toV8()
    506  * toJS() or toV8() checks if a wrapper object of the result is already cached on the node
    507  * If cached, the cached wrapper object is returned
    508  * Otherwise, toJS() or toV8() creates the wrapper object of the result
    509  * The created wrapper object is cached on the node
    510  * The wrapper object is returned
     510 1. Node::firstChild() is called
     511 1. The result is passed to toJS() or toV8()
     512 1. toJS() or toV8() checks if a wrapper object of the result is already cached on the node
     513 1. If cached, the cached wrapper object is returned
     514 1. Otherwise, toJS() or toV8() creates the wrapper object of the result
     515 1. The created wrapper object is cached on the node
     516 1. The wrapper object is returned
    511517
    512518On the other hand, if you do not want to cache the wrapper object and want to create the wrapper object every time,
    … …  
    709715where XXX implements YYY. [Supplemental] can be specified on interfaces.
    710716
    711 Here is an example. Without [Supplemental], if we want to add XXX's attributes or methods to DOMWindow,
    712 
    713  * we need to modify WebCore/page/DOMWindow.idl to add the XXX's attributes or methods
    714 
    715  * we need to modify WebCore/page/DOMWindow.{h,cpp} to add the C++ implementation of the attribute getters and setters or the method callbacks.
    716 
    717 On the other hand, in the modularized world with [Supplemental], we just need to modify the code under WebCore/Modules/XXX/:
     717Here is an example. Without [Supplemental], if you want to add XXX's attributes or methods to DOMWindow,
     718
     719 * you need to modify WebCore/page/DOMWindow.idl to add the XXX's attributes or methods
     720
     721 * you need to modify WebCore/page/DOMWindow.{h,cpp} to add the C++ implementation of the attribute getters and setters or the method callbacks.
     722
     723On the other hand, in the modularized world with [Supplemental], you just need to modify the code under WebCore/Modules/XXX/:
    718724
    719725 * WebCore/Modules/XXX/DOMWindowXXX.idl
     726
    720727{{{
    721728   interface [
    … …  
    729736
    730737 * WebCore/Modules/XXX/DOMWindowXXX.h
     738
    731739{{{
    732740   DOMWindowXXX::foo(...) { ... }   // The C++ implementation of the foo attribute getter.
    … …  
    735743}}}
    736744
    737 As shown above, [Supplemental=DOMWindow] indicates that all the attributes and methods of DOMWindowXXX should be exposed on DOMWindow, but should be implemented in DOMWindowXXX. In this way, we can implement the attributes and methods without modifying code of DOMWindow.{h,cpp,idl}.
     745As shown above, [Supplemental=DOMWindow] indicates that all the attributes and methods of DOMWindowXXX should be exposed on DOMWindow, but should be implemented in DOMWindowXXX. In this way, you can implement the attributes and methods without modifying code of DOMWindow.{h,cpp,idl}.
    738746
    739747If you want to add APIs whose implementations are likely to be independent from WebCore, it is strongly recommended to put the APIs and .h/.cpp files into WebCore/Modules/XXX/ using [Supplemental].
    … …  
    891899How to write custom bindings are different between JavaScriptCore and V8.
    892900
    893  * JavaScriptCore
    894 Consider the following example:
     901 * JavaScriptCore: Consider the following example:
     902
    895903{{{
    896904    interface [
    … …  
    909917Refer to WebCore/bindings/js/JSXXXCustom.cpp for more details.
    910918
    911  * V8
    912 Consider the following example:
     919 * V8: Consider the following example:
     920
    913921{{{
    914922    interface [
    … …  
    957965==  [V8EnabledAtRuntime](i,m,a) == #V8EnabledAtRuntime
    958966
    959 Summary: In Chromium/V8, we can enable/disable a flag at runtime.
     967Summary: In Chromium/V8, you can enable/disable a flag at runtime.
    960968
    961969Usage: The possible usage is [V8EnabledAtRuntime] or [V8EnabledAtRuntime=X],
    … …  
    977985}}}
    978986
    979 In Chromium/V8, we can enable/disable flags in the about:flags page.
     987In Chromium/V8, you can enable/disable flags in the about:flags page.
    980988To make interfaces/methods/attributes controllable through about:flags, you can specify [V8EnabledAtRuntime].
    981989
    … …  
    10961104[CustomIndexedSetter] allows us to write the custom bindings.
    10971105
    1098  * In JavaScriptCore, you can write JSXXX::indexSetter(...) in WebCore/bindings/js/JSXXXCustom.cpp:
     1106 * JavaScriptCore: You can write JSXXX::indexSetter(...) in WebCore/bindings/js/JSXXXCustom.cpp:
     1107
    10991108{{{
    11001109    void JSXXX::indexSetter(JSC::ExecState* exec, unsigned index, JSC::JSValue value)
    … …  
    11031112    }
    11041113}}}
    1105  * In V8, you can write V8XXX::indexedPropertyGetter(...) in WebCore/bindings/v8/custom/V8XXXCustom.cpp:
     1114 * In V8: You can write V8XXX::indexedPropertyGetter(...) in WebCore/bindings/v8/custom/V8XXXCustom.cpp:
     1115
    11061116{{{
    11071117    v8::Handle<v8::Value> V8XXX::indexedPropertyGetter(uint32_t index, const v8::AccessorInfo& info)
    … …  
    11471157[CustomNamedGetter] and [CustomNamedSetter] allow us to write the custom bindings.
    11481158
    1149  * With [CustomNamedGetter] in JavaScriptCore, you can write JSXXX::canGetItemsForName(...) and JSXXX::nameGetter(...) in WebCore/bindings/js/JSXXXCustom.cpp:
     1159 * [CustomNamedGetter] in JavaScriptCore: You can write JSXXX::canGetItemsForName(...) and JSXXX::nameGetter(...) in WebCore/bindings/js/JSXXXCustom.cpp:
     1160
    11501161{{{
    11511162    bool JSXXX::canGetItemsForName(ExecState*, XXX* impl, const Identifier& propertyName)
    … …  
    11591170    }
    11601171}}}
    1161  * With [CustomNamedGetter] in V8, you can write V8XXX::namedPropertyGetter(...) in WebCore/bindings/v8/custom/V8XXXCustom.cpp:
     1172 * [CustomNamedGetter] in V8: You can write V8XXX::namedPropertyGetter(...) in WebCore/bindings/v8/custom/V8XXXCustom.cpp:
     1173
    11621174{{{
    11631175    v8::Handle<v8::Value> V8XXX::namedPropertyGetter(v8::Local<v8::String>, v8::Local<v8::Value>, const v8::AccessorInfo&)
    … …  
    11661178    }
    11671179}}}
    1168  * With [CustomNamedSetter] in JavaScriptCore, you can write JSXXX::putDelegate(...) in WebCore/bindings/js/JSXXXCustom.cpp:
     1180 * [CustomNamedSetter] in JavaScriptCore: You can write JSXXX::putDelegate(...) in WebCore/bindings/js/JSXXXCustom.cpp:
     1181
    11691182{{{
    11701183    bool JSXXX::putDelegate(ExecState* exec, const Identifier& propertyName, JSValue value, PutPropertySlot&)
    … …  
    11731186    }
    11741187}}}
    1175  * With [CustomNamedSetter] in V8, you can write V8XXX::namedPropertySetter(...) in WebCore/bindings/v8/custom/V8XXXCustom.cpp:
     1188 * [CustomNamedSetter] in V8: You can write V8XXX::namedPropertySetter(...) in WebCore/bindings/v8/custom/V8XXXCustom.cpp:
     1189
    11761190{{{
    11771191    v8::Handle<v8::Value> V8XXX::namedPropertySetter(v8::Local<v8::String>, v8::Local<v8::Value>, const v8::AccessorInfo&)
    … …  
    13281342If you want to write custom bindings for XXX.call(...), you can use [CustomCall].
    13291343
    1330  * In JavaScriptCore, you can write JSXXX::getCallData(...) in WebCore/bindings/js/JSXXXCustom.cpp:
     1344 * JavaScriptCore: You can write JSXXX::getCallData(...) in WebCore/bindings/js/JSXXXCustom.cpp:
     1345
    13311346{{{
    13321347    JSC::CallType JSXXX::getCallData(JSC::JSCell* cell, JSC::CallData& callData)
    … …  
    13351350    }
    13361351}}}
    1337  * In V8, you can write V8XXX::callAsFunctionCallback(...) in WebCore/bindings/v8/custom/V8XXXCustom.cpp:
     1352 * V8: You can write V8XXX::callAsFunctionCallback(...) in WebCore/bindings/v8/custom/V8XXXCustom.cpp:
     1353
    13381354{{{
    13391355    v8::Handle<v8::Value> V8XXX::callAsFunctionCallback(const v8::Arguments& args)
    … …  
    13661382Refer to use cases in WebCore/bindings/js/JSXXXCustom.cpp for more details.
    13671383
    1368  * With [JSCustomToNativeObject], you can write custom toXXX(...):
     1384 * [JSCustomToNativeObject]: you can write custom toXXX(...):
     1385
    13691386{{{
    13701387    PassRefPtr<XXX> toXXX(JSGlobalData& globalData, JSValue value)
    … …  
    13731390    }
    13741391}}}
    1375  * With [JSCustomFinalize], you can write custom JSXXXOwner::finalize(...):
     1392 * [JSCustomFinalize]: You can write custom JSXXXOwner::finalize(...):
     1393
    13761394{{{
    13771395    void JSXXXOwner::finalize(JSC::Handle<JSC::Unknown> handle, void* context)
    … …  
    13801398    }
    13811399}}}
    1382  * With [JSCustomIsReachable], you can write custom JSXXXOwner::isReachableFromOpaqueRoots(...):
     1400 * [JSCustomIsReachable]: You can write custom JSXXXOwner::isReachableFromOpaqueRoots(...):
     1401
    13831402{{{
    13841403    bool JSXXXOwner::isReachableFromOpaqueRoots(JSC::Handle<JSC::Unknown> handle, void* context, SlotVisitor& visitor)
    … …  
    13871406    }
    13881407}}}
    1389  * With [JSCustomMarkFunction], you can write custom JSXXX::visitChildren(...):
     1408 * [JSCustomMarkFunction]: You can write custom JSXXX::visitChildren(...):
     1409
    13901410{{{
    13911411    void JSXXX::visitChildren(JSCell* cell, SlotVisitor& visitor)
    … …  
    13941414    }
    13951415}}}
    1396  * With [JSCustomNamedGetterOnPrototype], you can write custom JSXXX::putDelegate(...):
     1416 * [JSCustomNamedGetterOnPrototype]: You can write custom JSXXX::putDelegate(...):
     1417
    13971418{{{
    13981419    bool JSXXX::putDelegate(ExecState* exec, const Identifier& propertyName, JSValue value, PutPropertySlot& slot)
    … …  
    14011422    }
    14021423}}}
    1403  * With [JSCustomPushEventHandlerScope], you can write custom JSXXX::pushEventHandlerScope(...):
     1424 * [JSCustomPushEventHandlerScope]: You can write custom JSXXX::pushEventHandlerScope(...):
     1425
    14041426{{{
    14051427    ScopeChainNode* JSXXX::pushEventHandlerScope(ExecState* exec, ScopeChainNode* node) const
    … …  
    14081430    }
    14091431}}}
    1410  * With [JSCustomDefineOwnProperty], you can write custom JSXXX::defineOwnProperty(...):
     1432 * [JSCustomDefineOwnProperty]: You can write custom JSXXX::defineOwnProperty(...):
     1433
    14111434{{{
    14121435    bool JSXXX::defineOwnProperty(JSObject* object, ExecState* exec, const Identifier& propertyName, PropertyDescriptor& descriptor, bool throwException)
    … …  
    14151438    }
    14161439}}}
    1417  * With [JSCustomDefineOwnPropertyOnPrototype], you can write custom JSXXXPrototype::defineOwnProperty(...):
     1440 * [JSCustomDefineOwnPropertyOnPrototype]: You can write custom JSXXXPrototype::defineOwnProperty(...):
     1441
    14181442{{{
    14191443    bool JSXXXPrototype::defineOwnProperty(JSObject* object, ExecState* exec, const Identifier& propertyName, PropertyDescriptor& descriptor, bool throwException)
    … …  
    14221446    }
    14231447}}}
    1424  * With [JSCustomGetOwnPropertySlotAndDescriptor], you can write custom JSXXX::getOwnPropertySlotDelegate(...) and JSXXX::getOwnPropertyDescriptorDelegate(...):
     1448 * [JSCustomGetOwnPropertySlotAndDescriptor]: You can write custom JSXXX::getOwnPropertySlotDelegate(...) and JSXXX::getOwnPropertyDescriptorDelegate(...):
     1449
    14251450{{{
    14261451    bool JSXXX::getOwnPropertySlotDelegate(ExecState* exec, const Identifier& propertyName, PropertySlot& slot)