Changes between Version 48 and Version 49 of WebKitIDL


Ignore:
Timestamp:
Feb 19, 2012, 11:47:59 PM (13 years ago)
Author:
haraken@chromium.org
Comment:

--

Legend:

Unmodified
Added
Removed
Modified

  • WebKitIDL

    v48 v49  
    77[#Basics Basics of IDL]
    88
    9 [#BindingsCode Where is the bindings code?]
    10 
    11 [#NamingRules Basic naming rules of IDL attribute]
     9[#BindingsCode Where is the bindings code generated?]
     10
     11[#NamingRules Basic naming rules of IDL attributes]
    1212
    1313[#IDLAttributes IDL attributes]
    … …  
    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. 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.
     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 and CPP interfaces is automatically generated.
     115
     116This document describes practical information about how the IDL bindings work 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
    … …  
    123123    interface [
    124124        JSCustomHeader,
    125         CustomToObject
     125        CustomToJSObject
    126126    ] Node {
    127127        const unsigned short ELEMENT_NODE = 1;
    … …  
    136136Let us introduce some terminologies:
    137137
    138  * This is the IDL file of the Node ''''interface''''.
     138 * The above IDL file describes the Node ''''interface''''.
    139139 * ELEMENT_NODE is a ''''constant'''' of the Node interface.
    140140 * parentNode and nodeName are ''''attribute''''s of the Node interface.
    141141 * appendChild(...) and addEventListener(...) are ''''method''''s of the Node interface.
    142142 * type, listener and useCapture are ''''parameter''''s of the Node interface.
    143  * [JSCustomHeader], [CustomToObject], [TreatReturnedNullStringAs=Null], [Custom], [CustomReturn] and [Optional] are ''''IDL attribute''''s.
     143 * [JSCustomHeader], [CustomToJSObject], [TreatReturnedNullStringAs=Null], [Custom], [CustomReturn] and [Optional] are ''''IDL attribute''''s.
    144144
    145145Note: These terminologies are not aligned with the Web IDL spec.
    146 A 'method' is called an 'operation' in the Web IDL spec.
     146In the Web IDL spec, a 'method' is called an 'operation'.
    147147There is no distinction between an 'attribute' and a 'parameter' (a 'parameter' is treated as an 'attribute').
    148148
    … …  
    150150
    151151 * An IDL file controls how the bindings code between JavaScript engine (or ObjC, GObject, CPP) and the WebKit implementation is generated.
    152  * IDL attributes enable us to control the bindings code more in detail.
    153  * There are 90~ IDL attributes and their roles are explained in the subsequent section.
     152 * IDL attributes enable you to control the bindings code more in detail.
     153 * There are 90~ IDL attributes and their roles are explained in the subsequent sections.
    154154 * IDL attributes can be specified on interfaces, methods, attributes and parameters.
    155155Where each IDL attribute can be specified on is defined per each IDL attribute.
    156 This is also explained in the subsequent section.
    157 
    158 The template of an IDL file is as follows:
     156This is also explained in the subsequent sections.
     157
     158A template of an IDL file is as follows:
    159159{{{
    160160module MODULE_NAME {
    … …  
    182182}}}
    183183
    184 = Where is the bindings code? = #BindingsCode
     184= Where is the bindings code generated? = #BindingsCode
    185185
    186186By reading this document you can learn how IDL attributes work.
    187 However, the best practice to understand IDL attributes is to use some IDL attributes and watch the bindings code actually generated.
     187However, the best practice to understand IDL attributes is to try to use some IDL attributes and watch what kind of bindings code is generated.
    188188
    189189If you touch any IDL file, all IDL files are rebuilt.
    190 The code generation is done at the very early phase of the ./webkit-build command,
    191 and you can find the generated code in 1 minute.
    192 
    193 In case of XXX.idl, the bindings code is generated in the following files in the Release build ("Release" becomes "Debug" in the Debug build).
    194 
    195  * JavaScriptCore: WebKitBuild/Release/DerivedSources/WebCore/JSXXX.h, WebKitBuild/Release/DerivedSources/WebCore/JSXXX.cpp
    196  * V8: out/Release/obj/gen/webkit/bindings/V8XXX.h, out/Release/obj/gen/webcore/bindings/V8XXX.cpp
    197  * ObjC: WebKitBuild/Release/DerivedSources/WebCore/DOMXXX.h, WebKitBuild/Release/DerivedSources/WebCore/DOMXXX.mm
    198  * GObject: WebKitBuild/Release/DerivedSources/webkit/WebKitDOMXXX.h, WebKitBuild/Release/DerivedSources/webkit/WebKitDOMXXX.cpp
    199  * CPP: WebKitBuild/Release/DerivedSources/WebCore/WebDOMXXX.h, WebKitBuild/Release/DerivedSources/WebCore/WebDOMXXX.cpp
    200 
    201 = Basic naming rules of IDL attribute = #NamingRules
    202 
    203 There are a few rules of IDL attribute naming:
     190The code generation is done at the very early step of the ./webkit-build command,
     191so you can obtain the generated code in 1 minute.
     192
     193In case of XXX.idl in the Release build, the bindings code is generated in the following files ("Release" becomes "Debug" in the Debug build).
     194
     195 * JavaScriptCore:
     196
     197{{{
     198    WebKitBuild/Release/DerivedSources/WebCore/JSXXX.h
     199    WebKitBuild/Release/DerivedSources/WebCore/JSXXX.cpp
     200}}}
     201 * V8:
     202
     203{{{
     204    out/Release/obj/gen/webkit/bindings/V8XXX.h
     205    out/Release/obj/gen/webcore/bindings/V8XXX.cpp
     206}}}
     207 * ObjC:
     208
     209{{{
     210    WebKitBuild/Release/DerivedSources/WebCore/DOMXXX.h
     211    WebKitBuild/Release/DerivedSources/WebCore/DOMXXX.mm
     212}}}
     213 * GObject:
     214
     215{{{
     216    WebKitBuild/Release/DerivedSources/webkit/WebKitDOMXXX.h
     217    WebKitBuild/Release/DerivedSources/webkit/WebKitDOMXXX.cpp
     218}}}
     219 * CPP:
     220
     221{{{
     222    WebKitBuild/Release/DerivedSources/WebCore/WebDOMXXX.h
     223    WebKitBuild/Release/DerivedSources/WebCore/WebDOMXXX.cpp
     224}}}
     225
     226= Basic naming rules of IDL attributes = #NamingRules
     227
     228There are a few rules in naming IDL attributes:
    204229
    205230 * A name should be aligned with the Web IDL spec as much as possible.
    206  * JavaScriptCore specific IDL attributes are prefixed by "JS".
    207  * V8 specific IDL attributes are prefixed by "V8".
    208  * ObjC specific IDL attributes are prefixed by "ObjC".
    209  * GObject specific IDL attributes are prefixed by "GObject".
    210  * CPP specific IDL attributes are prefixed by "CPP".
     231 * JavaScriptCore-specific IDL attributes are prefixed by "JS".
     232 * V8-specific IDL attributes are prefixed by "V8".
     233 * ObjC-specific IDL attributes are prefixed by "ObjC".
     234 * GObject-specific IDL attributes are prefixed by "GObject".
     235 * CPP-specific IDL attributes are prefixed by "CPP".
    211236 * IDL attributes for custom bindings are prefixed by "Custom".
    212237
    … …  
    215240= IDL attributes = #IDLAttributes
    216241
    217 In the following explanations, (i), (m), (a) and (p) means that the IDL attribute can be specified on interfaces, methods, attributes and parameters, respectively. For example, (a,p) means that the IDL attribute can be specified on attributes and parameters.
     242In the following explanations, (i), (m), (a) or (p) means that a given IDL attribute can be specified on interfaces, methods, attributes and parameters, respectively. For example, (a,p) means that the IDL attribute can be specified on attributes and parameters.
    218243
    219244==  [TreatNullAs](a,p), [TreatUndefinedAs](a,p) == #TreatNullAs
    220245
    221  * [http://dev.w3.org/2006/webapi/WebIDL/#TreatNullAs The spec of TreatNullAs] (Note: The WebKit IDL explained below behaves differently from the spec)
    222  * [http://dev.w3.org/2006/webapi/WebIDL/#TreatUndefinedAs The spec of TreatUndefinedAs] (Note: The WebKit IDL explained below behaves differently from the spec)
    223 
    224 Summary: They control the behavior when a JavaScript null or undefined is passed to DOMString attributes/parameters.
     246 * [http://dev.w3.org/2006/webapi/WebIDL/#TreatNullAs The spec of TreatNullAs] (Note: The WebKit behavior explained below is different from the spec)
     247 * [http://dev.w3.org/2006/webapi/WebIDL/#TreatUndefinedAs The spec of TreatUndefinedAs] (Note: The WebKit behavior explained below is different from the spec)
     248
     249Summary: They control the behavior when a JavaScript null or undefined is passed to a DOMString attribute or parameter.
    225250
    226251Usage: The possible usage is [TreatNullAs=NullString] or [TreatUndefinedAs=NullString].
    … …  
    231256}}}
    232257
    233 [TreatNullAs=NullString] indicates that if a JavaScript null is passed to the attribute/parameter,
    234 then it is converted to a WebKit null string, for which String::IsEmpty() and String::IsNull() will return true.
     258[TreatNullAs=NullString] indicates that if a JavaScript null is passed to the attribute or parameter,
     259then it is converted to a WebKit null string, for which both String::IsEmpty() and String::IsNull() will return true.
    235260Without [TreatNullAs=NullString], a JavaScript null is converted to a WebKit string "null".
    236261
    237 [TreatNullAs=NullString] corresponds to [TreatNullAs=EmptyString] in the Web IDL spec.
    238 Unless the spec does not specify [TreatNullAs=EmptyString], you should not specify [TreatNullAs=NullString] in WebKit.
    239 
    240 [TreatUndefinedAs=NullString] indicates that if a JavaScript undefined is passed to the attribute/parameter,
    241 then it is converted to a WebKit null string, for which IsEmpty() and IsNull() will return true.
     262[TreatNullAs=NullString] in WebKit corresponds to [TreatNullAs=EmptyString] in the Web IDL spec.
     263Unless the spec specifies [TreatNullAs=EmptyString], you should not specify [TreatNullAs=NullString] in WebKit.
     264
     265[TreatUndefinedAs=NullString] indicates that if a JavaScript undefined is passed to the attribute or parameter,
     266then it is converted to a WebKit null string, for which both String::IsEmpty() and String::IsNull() will return true.
    242267Without [TreatUndefinedAs=NullString], a JavaScript undefined is converted to a WebKit string "undefined".
    243268
    244 [TreatUndefinedAs=NullString] corresponds to [TreatUndefinedAs=EmptyString] in the Web IDL spec.
    245 Unless the spec does not specify [TreatUndefinedAs=EmptyString], you should not specify [TreatUndefinedAs=NullString] in WebKit.
    246 
    247 Note: For now the sole usage of [TreatUndefinedAs=NullString] is not allowed in WebKit.
     269[TreatUndefinedAs=NullString] in WebKit corresponds to [TreatUndefinedAs=EmptyString] in the Web IDL spec.
     270Unless the spec specifies [TreatUndefinedAs=EmptyString], you should not specify [TreatUndefinedAs=NullString] in WebKit.
     271
     272Note: For now the sole usage of [TreatUndefinedAs=NullString] is not allowed.
    248273[TreatUndefinedAs=NullString] must be used with [TreatNullAs=NullString], i.e. [TreatNullAs=NullString, TreatUndefinedAs=NullString].
    249274
    250275==  [TreatReturnedNullStringAs](m,a) == #TreatReturnedNullStringAs
    251276
    252 Summary: It controls the behavior when a WebKit null string is returned.
     277Summary: [TreatReturnedNullStringAs] controls the behavior when a WebKit null string is returned from the WebCore implementation.
    253278
    254279Usage: The possible usage is [TreatReturnedNullStringAs=Null], [TreatReturnedNullStringAs=Undefined] or [TreatReturnedNullStringAs=False].
    … …  
    259284}}}
    260285
    261 [TreatReturnedNullStringAs=Null] indicates that if the returned string is a WebKit null string, the returned value is converted to a JavaScript null.
    262 
    263 [TreatReturnedNullStringAs=Undefined] indicates that if the returned string is a WebKit null string, the returned value is converted to a JavaScript undefined.
    264 
    265 [TreatReturnedNullStringAs=False] indicates that if the returned string is a WebKit null string, the returned value is converted to a JavaScript false.
    266 
    267 Without [TreatReturnedNullStringAs=...], if the returned string is a WebKit null string, the returned value becomes a JavaScript empty string ''. Note that what should be specified depends on the spec of each attribute or method.
     286 * [TreatReturnedNullStringAs=Null] indicates that if the returned DOMString is a WebKit null string, the returned value is treated as a JavaScript null.
     287 * [TreatReturnedNullStringAs=Undefined] indicates that if the returned DOMString is a WebKit null string, the returned value is treated as a JavaScript undefined.
     288 * [TreatReturnedNullStringAs=False] indicates that if the returned DOMString is a WebKit null string, the returned value is treated as a JavaScript false.
     289
     290Without [TreatReturnedNullStringAs=...], if the returned DOMString is a WebKit null string, then the returned value is treated as a JavaScript empty string ''.
     291
     292Note that what should be specified on [TreatReturnedNullStringAs=...] depends on the spec of each attribute or method.
    268293
    269294==  [Optional](p) == #Optional
    … …  
    872897==  [CustomConstructor](i), [JSCustomConstructor](i), [V8CustomConstructor](i), [ConstructorParameters](i) == #CustomConstructor
    873898
    874 Summary: They allow us to write custom bindings for constructors.
     899Summary: They allow you to write custom bindings for constructors.
    875900
    876901Usage: They can specified on interfaces.
    … …  
    10031028==  [CustomToJSObject](i), [JSCustomToJSObject](i), [V8CustomToJSObject](i) == #CustomToJSObject
    10041029
    1005 Summary: They allow us to write custom toJS() or toV8().
     1030Summary: They allow you to write custom toJS() or toV8().
    10061031
    10071032Usage: They can be specified on interfaces:
    … …  
    10721097==  [IndexedGetter](i) == #IndexedGetter
    10731098
    1074  * [http://dev.w3.org/2006/webapi/WebIDL/#idl-indexed-properties The spec of indexed properties] (Note: The WebKit IDL explained below behaves differently from the spec)
     1099 * [http://dev.w3.org/2006/webapi/WebIDL/#idl-indexed-properties The spec of indexed properties] (Note: The WebKit behavior explained below is different from the spec)
    10751100
    10761101Summary: [IndexedGetter] means that a given interface should have a getter of indexed properties.
    … …  
    10891114==  [CustomIndexedSetter](i) == #CustomIndexedSetter
    10901115
    1091  * [http://dev.w3.org/2006/webapi/WebIDL/#idl-indexed-properties The spec of indexed properties] (Note: The WebKit IDL explained below behaves differently from the spec)
    1092 
    1093 Summary: [CustomIndexedSetter] allows us to write custom bindings for a setter of indexed properties.
     1116 * [http://dev.w3.org/2006/webapi/WebIDL/#idl-indexed-properties The spec of indexed properties] (Note: The WebKit behavior explained below is different from the spec)
     1117
     1118Summary: [CustomIndexedSetter] allows you to write custom bindings for a setter of indexed properties.
    10941119
    10951120Usage: [CustomIndexedSetter] can be specified on interfaces:
    … …  
    11021127
    11031128Indexed setters define the behavior when "XXX[i] = ..." is evaluated.
    1104 [CustomIndexedSetter] allows us to write the custom bindings.
     1129[CustomIndexedSetter] allows you to write the custom bindings.
    11051130
    11061131 * JavaScriptCore: You can write JSXXX::indexSetter(...) in WebCore/bindings/js/JSXXXCustom.cpp:
    … …  
    11231148==  [NamedGetter](i) == #NamedGetter
    11241149
    1125  * [http://dev.w3.org/2006/webapi/WebIDL/#idl-named-properties The spec of named properties] (Note: The WebKit IDL explained below behaves differently from the spec)
     1150 * [http://dev.w3.org/2006/webapi/WebIDL/#idl-named-properties The spec of named properties] (Note: The WebKit behavior explained below is different from the spec)
    11261151
    11271152Summary: [NamedGetter] means that a given interface should have a getter of named properties.
    … …  
    11401165== [CustomNamedGetter](i), [CustomNamedSetter](i) == #CustomNamedGetter
    11411166
    1142  * [http://dev.w3.org/2006/webapi/WebIDL/#idl-named-properties The spec of named properties] (Note: The WebKit IDL explained below behaves differently from the spec)
    1143 
    1144 Summary: [CustomNamedGetter]/[CustomNamedSetter] allows us to write custom bindings for a getter/setter of named properties.
     1167 * [http://dev.w3.org/2006/webapi/WebIDL/#idl-named-properties The spec of named properties] (Note: The WebKit behavior explained below is different from the spec)
     1168
     1169Summary: [CustomNamedGetter]/[CustomNamedSetter] allows you to write custom bindings for a getter/setter of named properties.
    11451170
    11461171Usage: They can be specified on interfaces:
    … …  
    11551180Named getters define the behavior when XXX.foooooooo is evaluated, where foooooooo is not an attribute of a given interface.
    11561181Named setters define the behavior when "XXX.foooooooo = ..." is evaluated.
    1157 [CustomNamedGetter] and [CustomNamedSetter] allow us to write the custom bindings.
     1182[CustomNamedGetter] and [CustomNamedSetter] allow you to write the custom bindings.
    11581183
    11591184 * [CustomNamedGetter] in JavaScriptCore: You can write JSXXX::canGetItemsForName(...) and JSXXX::nameGetter(...) in WebCore/bindings/js/JSXXXCustom.cpp:
    … …  
    12661291==  [CustomEnumerateProperty](i), [CustomDeleteProperty](i) == #CustomEnumerateProperty
    12671292
    1268 Summary: [CustomEnumerateProperty] allows us to write custom bindings for the case where properties of a given interface are enumerated.
    1269 [CustomDeleteProperty] allows us to write custom bindings for the case where a property of a given interface is deleted.
     1293Summary: [CustomEnumerateProperty] allows you to write custom bindings for the case where properties of a given interface are enumerated.
     1294[CustomDeleteProperty] allows you to write custom bindings for the case where a property of a given interface is deleted.
    12701295
    12711296Usage: They can be specified on interfaces:
    … …  
    13301355==  [CustomCall](i) == #CustomCall
    13311356
    1332 Summary: [CustomCall] allows us to write custom bindings for call(...) of a given interface.
     1357Summary: [CustomCall] allows you to write custom bindings for call(...) of a given interface.
    13331358
    13341359Usage: [CustomCall] can be specified on interfaces:
    … …  
    13611386==  [JSCustomToNativeObject](i), [JSCustomFinalize](i), [JSCustomIsReachable](i), [JSCustomMarkFunction](i), [JSCustomNamedGetterOnPrototype](i), [JSCustomPushEventHandlerScope](i), [JSCustomDefineOwnProperty](i), [JSCustomDefineOwnPropertyOnPrototype](i), [JSCustomGetOwnPropertySlotAndDescriptor](i) == #JSCustomToNativeObject
    13621387
    1363 Summary: They allow us to write custom code for the JavaScriptCore code which would be generated automatically by default.
     1388Summary: They allow you to write custom code for the JavaScriptCore code which would be generated automatically by default.
    13641389
    13651390Usage: They can be specified on interfaces:
    … …  
    14801505==  [JSCustomHeader](i) == #JSCustomHeader
    14811506
    1482 Summary: It allows us to write a custom header for a given interface.
     1507Summary: It allows you to write a custom header for a given interface.
    14831508
    14841509Usage: [JSCustomHeader] can be specified on interfaces:
    … …  
    14921517By default, JSXXX.h and JSXXX.cpp are generated automatically, and if you need,
    14931518you can write custom bindings in WebCore/bindings/js/JSXXXCustom.cpp.
    1494 On the other hand, [JSCustomHeader] allows us to write WebCore/bindings/js/JSXXXCustom.h, which is included by JSXXX.h.
     1519On the other hand, [JSCustomHeader] allows you to write WebCore/bindings/js/JSXXXCustom.h, which is included by JSXXX.h.
    14951520
    14961521