Changes between Version 43 and Version 44 of WebKitIDL


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

--

Legend:

Unmodified
Added
Removed
Modified

  • WebKitIDL

    v43 v44  
    44
    55[#Overview Overview]
     6
    67[#Basics Basics of IDL]
     8
    79[#BindingsCode Where is the bindings code?]
     10
    811[#NamingRules Basic naming rules of IDL attribute]
     12
    913[#IDLAttributes IDL attributes]
    10 - [#TreatNullAs TreatNullAs]
     14
     15 - [#TreatNullAs TreatNullAs(a,p), TreatUndefinedAs(a,p)]
     16
     17 - [#TreatReturnedNullStringAs TreatReturnedNullStringAs(m,a)]
     18
     19 - [#Optional Optional(p)]
     20
     21 - [#Callback Callback(i,p) FIXME]
     22
     23 - [#Custom Custom(m,a), JSCustom(m,a), V8Custom(m,a), CustomGetter(a), JSCustomGetter(a), V8CustomGetter(a), CustomSetter(a), JSCustomSetter(a), V8CustomSetter(a)]
     24
     25 - [#CallWith CallWith(i,m,a)]
     26
     27 - [#CheckSecurityForNode CheckSecurityForNode(m,a)]
     28
     29 - [#StrictTypeChecking StrictTypeChecking(m,a) FIXME]
     30
     31 - [#ReturnNewObject ReturnNewObject(m,a)]
     32
     33 - [#ImplementedAs ImplementedAs(m)]
     34
     35 - [#Reflect Reflect(a) FIXME]
     36
     37 - [#Replaceable Replaceable(a)]
     38
     39 - [#Deletable Deletable(a), NotEnumerable(a), V8ReadOnly(a)]
     40
     41 - [#CachedAttribute CachedAttribute(a)]
     42
     43 - [#V8Unforgeable V8Unforgeable(m,a), V8OnProto(m,a)]
     44
     45 - [#URL URL(a)]
     46
     47 - [#JSWindowEventListener JSWindowEventListener(a) FIXME]
     48
     49 - [#Supplemental Supplemental(i)]
     50
     51 - [#Constructor Constructor(i), CallWith(i,m,a), ConstructorRaisesException(i)]
     52
     53 - [#ConstructorTemplate ConstructorTemplate(i), InitializedByEventConstructor(a)]
     54
     55 - [#NamedConstructor NamedConstructor(i)]
     56
     57 - [#CustomConstructor CustomConstructor(i), JSCustomConstructor(i), V8CustomConstructor(i), ConstructorParameters(i)]
     58
     59 - [#Conditional Conditional(i,m,a)]
     60
     61 - [#V8EnabledAtRuntime V8EnabledAtRuntime(i,m,a)]
     62
     63 - [#CustomToJSObject CustomToJSObject(i), JSCustomToJSObject(i), V8CustomToJSObject(i)]
     64
     65 - [#CheckSecurity CheckSecurity(i), DoNotCheckSecurity(m,a), DoNotCheckSecurityOnGetter(a), DoNotCheckSecurityOnSetter(a)]
     66
     67 - [#IndexedGetter IndexedGetter(i)]
     68
     69 - [#CustomIndexedSetter CustomIndexedSetter(i)]
     70
     71 - [#NamedGetter NamedGetter(i)]
     72
     73 - [#CustomNamedGetter CustomNamedGetter(i), CustomNamedSetter(i)]
     74
     75 - [#EventTarget EventTarget(i) FIXME]
     76
     77 - [#DoNotCheckConstants DoNotCheckConstants(i)]
     78
     79 - [#ActiveDOMObject ActiveDOMObject(i)]
     80
     81 - [#V8DependentLifeTime V8DependentLifeTime(i) FIXME]
     82
     83 - [#CustomEnumerateProperty CustomEnumerateProperty(i), CustomDeleteProperty(i)]
     84
     85 - [#IsWorkerContext IsWorkerContext(i)]
     86
     87 - [#CustomCall CustomCall(i)]
     88
     89 - [#JSCustomToNativeObject JSCustomToNativeObject(i), JSCustomFinalize(i), JSCustomIsReachable(i), JSCustomMarkFunction(i), JSCustomNamedGetterOnPrototype(i), JSCustomPushEventHandlerScope(i), JSCustomDefineOwnProperty(i), JSCustomDefineOwnPropertyOnPrototype(i), JSCustomGetOwnPropertySlotAndDescriptor(i)]
     90
     91 - [#JSGenerateToJSObject JSGenerateToJSObject(i), JSGenerateIsReachable(i), JSGenerateToNativeObject(i)]
     92
     93 - [#JSCustomHeader JSCustomHeader(i)]
     94
     95 - [#JSLegacyParent JSLegacyParent(i)]
     96
     97 - [#JSInlineGetOwnPropertySlot JSInlineGetOwnPropertySlot(i)]
     98
     99 - [#JSNoStaticTables JSNoStaticTables(i) FIXME]
     100
     101 - [#ObjCProtocol ObjCProtocol(i), ObjCPolymorphic(i), ObjCLegacyUnnamedParameters(m), ObjCUseDefaultView(m), ObjCImplementedAsUnsignedLongLong(a)]
     102
     103 - [#CPPPureInterface CPPPureInterface(i)]
     104
     105 - [#CustomReturn CustomReturn(p)]
     106
     107 - [#OmitConstructor OmitConstructor, Immutable, MasqueradesAsUndefined]
     108
     109 - [#CustomGetOwnPropertySlot CustomGetOwnPropertySlot, ReplaceableConstructor, ExtendsDOMGlobalObject, IsIndex, V8DoNotCheckSignature, NumericIndexedGetter]
     110
    11111
    12112= Overview = #Overview
    … …  
    117217In 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.
    118218
    119 ==  [TreatNullAs](a,p), [TreatUndefinedAs](a,p) == #TreatNullAs
     219==  [TreatNullAs](a,p), [TreatUndefinedAs](a,p) == #TreatNullAs #TreatNullAs
    120220
    121221 * [http://dev.w3.org/2006/webapi/WebIDL/#TreatNullAs The spec of TreatNullAs] (Note: The WebKit IDL explained below behaves differently from the spec)
    … …  
    148248[TreatUndefinedAs=NullString] must be used with [TreatNullAs=NullString], i.e. [TreatNullAs=NullString, TreatUndefinedAs=NullString].
    149249
    150 ==  [TreatReturnedNullStringAs](m,a) ==
     250==  [TreatReturnedNullStringAs](m,a) == #TreatReturnedNullStringAs
    151251
    152252Summary: It controls the behavior when a WebKit null string is returned.
    … …  
    167267Without [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.
    168268
    169 ==  [Optional](p) ==
     269==  [Optional](p) == #Optional
    170270
    171271Summary: It allows method overloading for methods whose argument count are different with each other.
    … …  
    197297While in [Optional=DefalutIsUndefined] the "supplemented" JavaScript undefined is converted to a WebKit string "undefined", in [Optional=DefaultIsNullString] the "supplemented" JavaScript undefined is converted to a WebKit null string. Specifically, if JavaScript calls func3(100, 200), then HTMLFoo::func3(int a, int b, String c, String d) is called in WebCore. Here 100 is passed to a, 200 is passed to b, a WebKit string "undefined" is passed to c, and a WebKit null string is passed to d.
    198298
    199 ==  [Callback](i,p) FIXME ==
     299==  [Callback](i,p) FIXME == #Callback
    200300
    201301Summary: ADD SUMMARY
    … …  
    212312ADD EXPLANATIONS
    213313
    214 ==  [Custom](m,a), [JSCustom](m,a), [V8Custom](m,a), [CustomGetter](a), [JSCustomGetter](a), [V8CustomGetter](a), [CustomSetter](a), [JSCustomSetter](a), [V8CustomSetter](a) ==
     314==  [Custom](m,a), [JSCustom](m,a), [V8Custom](m,a), [CustomGetter](a), [JSCustomGetter](a), [V8CustomGetter](a), [CustomSetter](a), [JSCustomSetter](a), [V8CustomSetter](a) == #Custom
    215315
    216316Summary: If your bindings require special (i.e. "custom") handling, you can write the bindings code as you like.
    … …  
    339439Note: ObjC, GObject and CPP bindings do not support custom bindings.
    340440
    341 ==  [CallWith](i,m,a) ==
     441==  [CallWith](i,m,a) == #CallWith
    342442
    343443Summary: It calls a WebCore method with additional information.
    … …  
    369469HTMLFoo::func3(ScriptArguments* arguments, ScriptCallStack* callstack, int a, int b) is called.
    370470
    371 ==  [CheckSecurityForNode](m,a) ==
     471==  [CheckSecurityForNode](m,a) == #CheckSecurityForNode
    372472
    373473Summary: It checks if a given Node access is allowed in terms of security.
    … …  
    383483This is really important for security.
    384484
    385 ==  [StrictTypeChecking](m,a) FIXME ==
     485==  [StrictTypeChecking](m,a) FIXME == #StrictTypeChecking
    386486
    387487Summary: ADD SUMMARY
    … …  
    395495ADD EXPLANATIONS
    396496
    397 ==  [ReturnNewObject](m,a) ==
     497==  [ReturnNewObject](m,a) == #ReturnNewObject
    398498
    399499Summary: It controls whether WebCore can return a cached wrapper object or not.
    … …  
    420520
    421521
    422 ==  [ImplementedAs](m) ==
     522==  [ImplementedAs](m) == #ImplementedAs
    423523
    424524Summary: It specifies a method name in WebCore implementation, if the IDL method name and the WebCore method name are different.
    … …  
    434534You should avoid using [ImplementedAs] as much as possible though.
    435535
    436 ==  [Reflect](a) FIXME ==
     536==  [Reflect](a) FIXME == #Reflect
    437537
    438538Summary: ADD SUMMARY
    … …  
    445545ADD EXPLANATIONS
    446546
    447 ==  [Replaceable](a) ==
     547==  [Replaceable](a) == #Replaceable
    448548
    449549 * [http://dev.w3.org/2006/webapi/WebIDL/#Replaceable The spec of replaceable]
    … …  
    482582
    483583
    484 ==  [Deletable](a), [NotEnumerable](a), [V8ReadOnly](a) ==
     584==  [Deletable](a), [NotEnumerable](a), [V8ReadOnly](a) == #Deletable
    485585
    486586 * [http://www.ecma-international.org/publications/files/ECMA-ST/Ecma-262.pdf The spec of Writable, Enumerable and Configurable (8.6.1)]
    … …  
    499599[Deletable] indicates that the attribute is deletable. [NotEnumerable] indicates that the attribute is not enumerable. [V8ReadOnly] indicates that the attribute is readonly in V8 even if the attribute is not prefixed by "readonly".
    500600
    501 ==  [CachedAttribute](a) ==
     601==  [CachedAttribute](a) == #CachedAttribute
    502602
    503603Summary: For performance optimization, it indicates to cache a wrapped object in a DOM object.
    … …  
    550650but also it increases the overhead of "cache-miss"ed getters and setters (Setters always need to invalidate the caches).
    551651
    552 ==  [V8Unforgeable](m,a), [V8OnProto](m,a) ==
     652==  [V8Unforgeable](m,a), [V8OnProto](m,a) == #V8Unforgeable
    553653
    554654 * [http://dev.w3.org/2006/webapi/WebIDL/#Unforgeable The spec of Unforgeable]
    … …  
    574674You should not use them unless you have a strong reason to use them.
    575675
    576 ==  [URL](a) ==
     676==  [URL](a) == #URL
    577677
    578678Summary: It indicates that a given DOMString is a URL.
    … …  
    587687If you forgot to specify [URL], then the attribute getter might cause a bug.
    588688
    589 ==  [JSWindowEventListener](a) FIXME ==
     689==  [JSWindowEventListener](a) FIXME == #JSWindowEventListener
    590690
    591691Summary: ADD SUMMARY
    … …  
    598698ADD EXPLANATIONS
    599699
    600 ==  [Supplemental](i) ==
     700==  [Supplemental](i) == #Supplemental
    601701
    602702 * [http://dev.w3.org/2006/webapi/WebIDL/#dfn-supplemental-interface The spec of Supplemental]
    … …  
    645745If 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].
    646746
    647 ==  [Constructor](i), [CallWith](i,m,a), [ConstructorRaisesException](i) ==
     747==  [Constructor](i), [CallWith](i,m,a), [ConstructorRaisesException](i) == #Constructor
    648748
    649749 * [http://dev.w3.org/2006/webapi/WebIDL/#Constructor The spec of Constructor]
    … …  
    708808Whether you should allow an interface to have constructor depends on the spec of the interface.
    709809
    710 ==  [ConstructorTemplate](i), [InitializedByEventConstructor](a) ==
     810==  [ConstructorTemplate](i), [InitializedByEventConstructor](a) == #ConstructorTemplate
    711811
    712812Summary: They are used for Event constructors.
    … …  
    749849In other words, in case of Event, you should specify [InitializedByEventConstructor] on bubbles and cancelable.
    750850
    751 ==  [NamedConstructor](i) ==
     851==  [NamedConstructor](i) == #NamedConstructor
    752852
    753853 * [http://dev.w3.org/2006/webapi/WebIDL/#NamedConstructor The spec of NamedConstructor]
    … …  
    768868Whether you should allow an interface to have a named constructor depends on the spec of the interface.
    769869
    770 ==  [CustomConstructor](i), [JSCustomConstructor](i), [V8CustomConstructor](i), [ConstructorParameters](i) ==
     870==  [CustomConstructor](i), [JSCustomConstructor](i), [V8CustomConstructor](i), [ConstructorParameters](i) == #CustomConstructor
    771871
    772872Summary: They allow us to write custom bindings for constructors.
    … …  
    837937You do not need to specify [ConstructorParameters] if the interface does not have any of [JSCustomConstructor], [V8CustomConstructor] or [CustomConstructor].
    838938
    839 ==  [Conditional](i,m,a) ==
     939==  [Conditional](i,m,a) == #Conditional
    840940
    841941Summary: It inserts "#if ENABLE(SOME_FLAG) ... #endif" into the generated code.
    … …  
    861961If [Conditional] is specified on an interface, it means that [Conditional] is specified on all attributes and methods on the interface.
    862962
    863 ==  [V8EnabledAtRuntime](i,m,a) ==
     963==  [V8EnabledAtRuntime](i,m,a) == #V8EnabledAtRuntime
    864964
    865965Summary: In Chromium/V8, we can enable/disable a flag at runtime.
    … …  
    899999and WebKit/chromium/src/WebRuntimeFeatures.cpp for more details.
    9001000
    901 ==  [CustomToJSObject](i), [JSCustomToJSObject](i), [V8CustomToJSObject](i) ==
     1001==  [CustomToJSObject](i), [JSCustomToJSObject](i), [V8CustomToJSObject](i) == #CustomToJSObject
    9021002
    9031003Summary: They allow us to write custom toJS() or toV8().
    … …  
    9311031}}}
    9321032
    933 ==  [CheckSecurity](i), [DoNotCheckSecurity](m,a), [DoNotCheckSecurityOnGetter](a), [DoNotCheckSecurityOnSetter](a) ==
     1033==  [CheckSecurity](i), [DoNotCheckSecurity](m,a), [DoNotCheckSecurityOnGetter](a), [DoNotCheckSecurityOnSetter](a) == #CheckSecurity
    9341034
    9351035Summary: It checks if a given Frame access is allowed or not, in terms of security.
    … …  
    9681068 * [DoNotCheckSecurity] on an attribute is equivalent to [DoNotCheckSecurityOnGetter, DoNotCheckSecurityOnSetter].
    9691069
    970 ==  [IndexedGetter](i) ==
     1070==  [IndexedGetter](i) == #IndexedGetter
    9711071
    9721072 * [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)
    … …  
    9851085The bindings code is generated automatically so that XXX[i] behaves equivalent to XXX.item(i).
    9861086
    987 ==  [CustomIndexedSetter](i) ==
     1087==  [CustomIndexedSetter](i) == #CustomIndexedSetter
    9881088
    9891089 * [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)
    … …  
    10171117}}}
    10181118
    1019 ==  [NamedGetter](i) ==
     1119==  [NamedGetter](i) == #NamedGetter
    10201120
    10211121 * [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)
    … …  
    10341134The bindings code is generated automatically so that XXX.foooooooo behaves equivalent to XXX.namedItem(i).
    10351135
    1036 == [CustomNamedGetter](i), [CustomNamedSetter](i) ==
     1136== [CustomNamedGetter](i), [CustomNamedSetter](i) == #CustomNamedGetter
    10371137
    10381138 * [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)
    … …  
    10871187}}}
    10881188
    1089 ==  [EventTarget](i) FIXME ==
     1189==  [EventTarget](i) FIXME == #EventTarget
    10901190
    10911191Summary: ADD SUMMARY
    … …  
    11011201ADD EXPLANATIONS
    11021202
    1103 ==  [DoNotCheckConstants](i) ==
     1203==  [DoNotCheckConstants](i) == #DoNotCheckConstants
    11041204
    11051205Summary: [DoNotCheckConstants] stops inserting compile-time assertions for constants of a given interface.
    … …  
    11241224you can specify [DoNotCheckConstants] on the interface to skip the compile-time assertions.
    11251225
    1126 ==  [ActiveDOMObject](i) ==
     1226==  [ActiveDOMObject](i) == #ActiveDOMObject
    11271227
    11281228Summary: [ActiveDOMObject] indicates that a DOM object should be kept alive when the DOM object has pending activities.
    … …  
    11421242then the interface Y should also have [ActiveDOMObject].
    11431243
    1144 ==  [V8DependentLifeTime](i) FIXME ==
     1244==  [V8DependentLifeTime](i) FIXME == #V8DependentLifeTime
    11451245
    11461246Summary: ADD SUMMARY
    … …  
    11561256ADD EXPLANATIONS
    11571257
    1158 ==  [CustomEnumerateProperty](i), [CustomDeleteProperty](i) ==
     1258==  [CustomEnumerateProperty](i), [CustomDeleteProperty](i) == #CustomEnumerateProperty
    11591259
    11601260Summary: [CustomEnumerateProperty] allows us to write custom bindings for the case where properties of a given interface are enumerated.
    … …  
    12071307}}}
    12081308
    1209 ==  [IsWorkerContext](i) ==
     1309==  [IsWorkerContext](i) == #IsWorkerContext
    12101310
    12111311Summary: It indicates that the interface is a WorkerContext-related interface.
    … …  
    12201320}}}
    12211321
    1222 ==  [CustomCall](i) ==
     1322==  [CustomCall](i) == #CustomCall
    12231323
    12241324Summary: [CustomCall] allows us to write custom bindings for call(...) of a given interface.
    … …  
    12491349}}}
    12501350
    1251 ==  [JSCustomToNativeObject](i), [JSCustomFinalize](i), [JSCustomIsReachable](i), [JSCustomMarkFunction](i), [JSCustomNamedGetterOnPrototype](i), [JSCustomPushEventHandlerScope](i), [JSCustomDefineOwnProperty](i), [JSCustomDefineOwnPropertyOnPrototype](i), [JSCustomGetOwnPropertySlotAndDescriptor](i) ==
     1351==  [JSCustomToNativeObject](i), [JSCustomFinalize](i), [JSCustomIsReachable](i), [JSCustomMarkFunction](i), [JSCustomNamedGetterOnPrototype](i), [JSCustomPushEventHandlerScope](i), [JSCustomDefineOwnProperty](i), [JSCustomDefineOwnPropertyOnPrototype](i), [JSCustomGetOwnPropertySlotAndDescriptor](i) == #JSCustomToNativeObject
    12521352
    12531353Summary: They allow us to write custom code for the JavaScriptCore code which would be generated automatically by default.
    … …  
    13411441}}}
    13421442
    1343 ==  [JSGenerateToJSObject](i), [JSGenerateIsReachable](i), [JSGenerateToNativeObject](i) ==
     1443==  [JSGenerateToJSObject](i), [JSGenerateIsReachable](i), [JSGenerateToNativeObject](i) == #JSGenerateToJSObject
    13441444
    13451445Summary: They force JavaScriptCore bindings to generate JavaScriptCore specific methods even if a given interface has a parent interface.
    … …  
    13591459[JSGenerateToJSObject], [JSGenerateIsReachable] or [JSGenerateToNativeObject], respectively.
    13601460
    1361 ==  [JSCustomHeader](i) ==
     1461==  [JSCustomHeader](i) == #JSCustomHeader
    13621462
    13631463Summary: It allows us to write a custom header for a given interface.
    … …  
    13761476
    13771477
    1378 ==  [JSLegacyParent](i) ==
     1478==  [JSLegacyParent](i) == #JSLegacyParent
    13791479
    13801480Summary: It explicitly controls the parent interface of a given interface.
    … …  
    13901490Even if a given interface does not have a parent interface, you can specify a parent interface using [JSLegacyParent].
    13911491
    1392 ==  [JSInlineGetOwnPropertySlot](i) ==
     1492==  [JSInlineGetOwnPropertySlot](i) == #JSInlineGetOwnPropertySlot
    13931493
    13941494Summary: It makes getOwnPropertySlot(...) and getOwnPropertyDescriptor(...) an inline method for performance.
    … …  
    14021502}}}
    14031503
    1404 ==  [JSNoStaticTables](i) FIXME ==
     1504==  [JSNoStaticTables](i) FIXME == #JSNoStaticTables
    14051505
    14061506Summary: ADD SUMMARY
    … …  
    14161516ADD EXPLANATIONS
    14171517
    1418 ==  [ObjCProtocol](i), [ObjCPolymorphic](i), [ObjCLegacyUnnamedParameters](m), [ObjCUseDefaultView](m), [ObjCImplementedAsUnsignedLongLong](a) ==
     1518==  [ObjCProtocol](i), [ObjCPolymorphic](i), [ObjCLegacyUnnamedParameters](m), [ObjCUseDefaultView](m), [ObjCImplementedAsUnsignedLongLong](a) == #ObjCProtocol
    14191519
    14201520Used by ObjC bindings only.
    14211521
    1422 ==  [CPPPureInterface](i) ==
     1522==  [CPPPureInterface](i) == #CPPPureInterface
    14231523
    14241524Used by CPP bindings only.
    14251525
    1426 ==  [CustomReturn](p) ==
     1526==  [CustomReturn](p) == #CustomReturn
    14271527
    14281528Used by ObjC, GObject and CPP bindings only.
    14291529
    1430 ==  [OmitConstructor], [Immutable], [MasqueradesAsUndefined] ==
     1530==  [OmitConstructor], [Immutable], [MasqueradesAsUndefined] == #OmitConstructor
    14311531
    14321532Might be deprecated. Discussion is on-going.
    14331533
    1434 ==  [CustomGetOwnPropertySlot], [ReplaceableConstructor], [ExtendsDOMGlobalObject], [IsIndex], [V8DoNotCheckSignature], [NumericIndexedGetter] ==
     1534==  [CustomGetOwnPropertySlot], [ReplaceableConstructor], [ExtendsDOMGlobalObject], [IsIndex], [V8DoNotCheckSignature], [NumericIndexedGetter] == #CustomGetOwnPropertySlot
    14351535
    14361536Will be deprecated. Discussion is on-going.