Changes between Version 47 and Version 48 of WebKitIDL
- Timestamp:
- Feb 19, 2012 10:41:05 PM (11 years ago)
Legend:
- Unmodified
- Added
- Removed
- Modified
-
WebKitIDL
v47 v48 112 112 = Overview = #Overview 113 113 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. Weneed 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 wecan 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.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. 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 116 This 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. 117 117 118 118 = Basics of IDL = #Basics … … 342 342 343 343 * Method in JavaScriptCore: Consider the following example: 344 344 345 {{{ 345 346 interface XXX { … … 357 358 358 359 * Attribute getter in JavaScriptCore: Consider the following example: 360 359 361 {{{ 360 362 interface XXX { … … 372 374 373 375 * Attribute setter in JavaScriptCore: Consider the following example: 376 374 377 {{{ 375 378 interface XXX { … … 387 390 388 391 * Method in V8: Consider the following example: 392 389 393 {{{ 390 394 interface XXX { … … 402 406 403 407 * Attribute getter in V8: Consider the following example: 408 404 409 {{{ 405 410 interface XXX { … … 417 422 418 423 * Attribute setter in V8: Consider the following example: 424 419 425 {{{ 420 426 interface XXX { … … 502 508 For example, consider the case where node.firstChild is accessed: 503 509 504 *Node::firstChild() is called505 *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 node507 *If cached, the cached wrapper object is returned508 *Otherwise, toJS() or toV8() creates the wrapper object of the result509 *The created wrapper object is cached on the node510 *The wrapper object is returned510 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 511 517 512 518 On the other hand, if you do not want to cache the wrapper object and want to create the wrapper object every time, … … 709 715 where XXX implements YYY. [Supplemental] can be specified on interfaces. 710 716 711 Here is an example. Without [Supplemental], if wewant to add XXX's attributes or methods to DOMWindow,712 713 * weneed to modify WebCore/page/DOMWindow.idl to add the XXX's attributes or methods714 715 * weneed 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], wejust need to modify the code under WebCore/Modules/XXX/:717 Here 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 723 On the other hand, in the modularized world with [Supplemental], you just need to modify the code under WebCore/Modules/XXX/: 718 724 719 725 * WebCore/Modules/XXX/DOMWindowXXX.idl 726 720 727 {{{ 721 728 interface [ … … 729 736 730 737 * WebCore/Modules/XXX/DOMWindowXXX.h 738 731 739 {{{ 732 740 DOMWindowXXX::foo(...) { ... } // The C++ implementation of the foo attribute getter. … … 735 743 }}} 736 744 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, wecan implement the attributes and methods without modifying code of DOMWindow.{h,cpp,idl}.745 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, you can implement the attributes and methods without modifying code of DOMWindow.{h,cpp,idl}. 738 746 739 747 If 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]. … … 891 899 How to write custom bindings are different between JavaScriptCore and V8. 892 900 893 * JavaScriptCore 894 Consider the following example: 901 * JavaScriptCore: Consider the following example: 902 895 903 {{{ 896 904 interface [ … … 909 917 Refer to WebCore/bindings/js/JSXXXCustom.cpp for more details. 910 918 911 * V8 912 Consider the following example: 919 * V8: Consider the following example: 920 913 921 {{{ 914 922 interface [ … … 957 965 == [V8EnabledAtRuntime](i,m,a) == #V8EnabledAtRuntime 958 966 959 Summary: In Chromium/V8, wecan enable/disable a flag at runtime.967 Summary: In Chromium/V8, you can enable/disable a flag at runtime. 960 968 961 969 Usage: The possible usage is [V8EnabledAtRuntime] or [V8EnabledAtRuntime=X], … … 977 985 }}} 978 986 979 In Chromium/V8, wecan enable/disable flags in the about:flags page.987 In Chromium/V8, you can enable/disable flags in the about:flags page. 980 988 To make interfaces/methods/attributes controllable through about:flags, you can specify [V8EnabledAtRuntime]. 981 989 … … 1096 1104 [CustomIndexedSetter] allows us to write the custom bindings. 1097 1105 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 1099 1108 {{{ 1100 1109 void JSXXX::indexSetter(JSC::ExecState* exec, unsigned index, JSC::JSValue value) … … 1103 1112 } 1104 1113 }}} 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 1106 1116 {{{ 1107 1117 v8::Handle<v8::Value> V8XXX::indexedPropertyGetter(uint32_t index, const v8::AccessorInfo& info) … … 1147 1157 [CustomNamedGetter] and [CustomNamedSetter] allow us to write the custom bindings. 1148 1158 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 1150 1161 {{{ 1151 1162 bool JSXXX::canGetItemsForName(ExecState*, XXX* impl, const Identifier& propertyName) … … 1159 1170 } 1160 1171 }}} 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 1162 1174 {{{ 1163 1175 v8::Handle<v8::Value> V8XXX::namedPropertyGetter(v8::Local<v8::String>, v8::Local<v8::Value>, const v8::AccessorInfo&) … … 1166 1178 } 1167 1179 }}} 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 1169 1182 {{{ 1170 1183 bool JSXXX::putDelegate(ExecState* exec, const Identifier& propertyName, JSValue value, PutPropertySlot&) … … 1173 1186 } 1174 1187 }}} 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 1176 1190 {{{ 1177 1191 v8::Handle<v8::Value> V8XXX::namedPropertySetter(v8::Local<v8::String>, v8::Local<v8::Value>, const v8::AccessorInfo&) … … 1328 1342 If you want to write custom bindings for XXX.call(...), you can use [CustomCall]. 1329 1343 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 1331 1346 {{{ 1332 1347 JSC::CallType JSXXX::getCallData(JSC::JSCell* cell, JSC::CallData& callData) … … 1335 1350 } 1336 1351 }}} 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 1338 1354 {{{ 1339 1355 v8::Handle<v8::Value> V8XXX::callAsFunctionCallback(const v8::Arguments& args) … … 1366 1382 Refer to use cases in WebCore/bindings/js/JSXXXCustom.cpp for more details. 1367 1383 1368 * With [JSCustomToNativeObject], you can write custom toXXX(...): 1384 * [JSCustomToNativeObject]: you can write custom toXXX(...): 1385 1369 1386 {{{ 1370 1387 PassRefPtr<XXX> toXXX(JSGlobalData& globalData, JSValue value) … … 1373 1390 } 1374 1391 }}} 1375 * With [JSCustomFinalize], you can write custom JSXXXOwner::finalize(...): 1392 * [JSCustomFinalize]: You can write custom JSXXXOwner::finalize(...): 1393 1376 1394 {{{ 1377 1395 void JSXXXOwner::finalize(JSC::Handle<JSC::Unknown> handle, void* context) … … 1380 1398 } 1381 1399 }}} 1382 * With [JSCustomIsReachable], you can write custom JSXXXOwner::isReachableFromOpaqueRoots(...): 1400 * [JSCustomIsReachable]: You can write custom JSXXXOwner::isReachableFromOpaqueRoots(...): 1401 1383 1402 {{{ 1384 1403 bool JSXXXOwner::isReachableFromOpaqueRoots(JSC::Handle<JSC::Unknown> handle, void* context, SlotVisitor& visitor) … … 1387 1406 } 1388 1407 }}} 1389 * With [JSCustomMarkFunction], you can write custom JSXXX::visitChildren(...): 1408 * [JSCustomMarkFunction]: You can write custom JSXXX::visitChildren(...): 1409 1390 1410 {{{ 1391 1411 void JSXXX::visitChildren(JSCell* cell, SlotVisitor& visitor) … … 1394 1414 } 1395 1415 }}} 1396 * With [JSCustomNamedGetterOnPrototype], you can write custom JSXXX::putDelegate(...): 1416 * [JSCustomNamedGetterOnPrototype]: You can write custom JSXXX::putDelegate(...): 1417 1397 1418 {{{ 1398 1419 bool JSXXX::putDelegate(ExecState* exec, const Identifier& propertyName, JSValue value, PutPropertySlot& slot) … … 1401 1422 } 1402 1423 }}} 1403 * With [JSCustomPushEventHandlerScope], you can write custom JSXXX::pushEventHandlerScope(...): 1424 * [JSCustomPushEventHandlerScope]: You can write custom JSXXX::pushEventHandlerScope(...): 1425 1404 1426 {{{ 1405 1427 ScopeChainNode* JSXXX::pushEventHandlerScope(ExecState* exec, ScopeChainNode* node) const … … 1408 1430 } 1409 1431 }}} 1410 * With [JSCustomDefineOwnProperty], you can write custom JSXXX::defineOwnProperty(...): 1432 * [JSCustomDefineOwnProperty]: You can write custom JSXXX::defineOwnProperty(...): 1433 1411 1434 {{{ 1412 1435 bool JSXXX::defineOwnProperty(JSObject* object, ExecState* exec, const Identifier& propertyName, PropertyDescriptor& descriptor, bool throwException) … … 1415 1438 } 1416 1439 }}} 1417 * With [JSCustomDefineOwnPropertyOnPrototype], you can write custom JSXXXPrototype::defineOwnProperty(...): 1440 * [JSCustomDefineOwnPropertyOnPrototype]: You can write custom JSXXXPrototype::defineOwnProperty(...): 1441 1418 1442 {{{ 1419 1443 bool JSXXXPrototype::defineOwnProperty(JSObject* object, ExecState* exec, const Identifier& propertyName, PropertyDescriptor& descriptor, bool throwException) … … 1422 1446 } 1423 1447 }}} 1424 * With [JSCustomGetOwnPropertySlotAndDescriptor], you can write custom JSXXX::getOwnPropertySlotDelegate(...) and JSXXX::getOwnPropertyDescriptorDelegate(...): 1448 * [JSCustomGetOwnPropertySlotAndDescriptor]: You can write custom JSXXX::getOwnPropertySlotDelegate(...) and JSXXX::getOwnPropertyDescriptorDelegate(...): 1449 1425 1450 {{{ 1426 1451 bool JSXXX::getOwnPropertySlotDelegate(ExecState* exec, const Identifier& propertyName, PropertySlot& slot)