Changes between Version 37 and Version 38 of WebKitIDL


Ignore:
Timestamp:
Feb 17, 2012 2:22:48 AM (12 years ago)
Author:
haraken@chromium.org
Comment:

--

Legend:

Unmodified
Added
Removed
Modified
  • WebKitIDL

    v37 v38  
    106106In 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.
    107107
    108 === * [TreatNullAs](a,p), [TreatUndefinedAs](a,p) ===
     108==  [TreatNullAs](a,p), [TreatUndefinedAs](a,p) ==
    109109
    110110 * [http://dev.w3.org/2006/webapi/WebIDL/#TreatNullAs The spec of TreatNullAs] (Note: The WebKit IDL explained below behaves differently from the spec)
     
    137137[TreatUndefinedAs=NullString] must be used with [TreatNullAs=NullString], i.e. [TreatNullAs=NullString, TreatUndefinedAs=NullString].
    138138
    139 === * [TreatReturnedNullStringAs](m,a) ===
     139==  [TreatReturnedNullStringAs](m,a) ==
    140140
    141141Summary: It controls the behavior when a WebKit null string is returned.
     
    156156Without [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.
    157157
    158 === * [Optional](p) ===
     158==  [Optional](p) ==
    159159
    160160Summary: It allows method overloading for methods whose argument count are different with each other.
     
    186186While 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.
    187187
    188 === * [Callback](i,p) FIXME ===
     188==  [Callback](i,p) FIXME ==
    189189
    190190Summary: ADD SUMMARY
     
    201201ADD EXPLANATIONS
    202202
    203 === * [Custom](m,a), [JSCustom](m,a), [V8Custom](m,a), [CustomGetter](a), [JSCustomGetter](a), [V8CustomGetter](a), [CustomSetter](a), [JSCustomSetter](a), [V8CustomSetter](a) ===
     203==  [Custom](m,a), [JSCustom](m,a), [V8Custom](m,a), [CustomGetter](a), [JSCustomGetter](a), [V8CustomGetter](a), [CustomSetter](a), [JSCustomSetter](a), [V8CustomSetter](a) ==
    204204
    205205Summary: If your bindings require special (i.e. "custom") handling, you can write the bindings code as you like.
     
    328328Note: ObjC, GObject and CPP bindings do not support custom bindings.
    329329
    330 === * [CallWith](i,m,a) ===
     330==  [CallWith](i,m,a) ==
    331331
    332332Summary: It calls a WebCore method with additional information.
     
    358358HTMLFoo::func3(ScriptArguments* arguments, ScriptCallStack* callstack, int a, int b) is called.
    359359
    360 === * [CheckAccessToNode](m,a) ===
     360==  [CheckAccessToNode](m,a) ==
    361361
    362362Summary: It checks if a given Node access is allowed in terms of security.
     
    372372This is really important for security.
    373373
    374 === * [StrictTypeChecking](m,a) FIXME ===
     374==  [StrictTypeChecking](m,a) FIXME ==
    375375
    376376Summary: ADD SUMMARY
     
    384384ADD EXPLANATIONS
    385385
    386 === * [ReturnNewObject](m,a) ===
     386==  [ReturnNewObject](m,a) ==
    387387
    388388Summary: It controls whether WebCore can return a cached wrapper object or not.
     
    409409
    410410
    411 === * [ImplementedAs](m) ===
     411==  [ImplementedAs](m) ==
    412412
    413413Summary: It specifies a method name in WebCore implementation, if the IDL method name and the WebCore method name are different.
     
    423423You should avoid using [ImplementedAs] as much as possible though.
    424424
    425 === * [Reflect](a) FIXME ===
     425==  [Reflect](a) FIXME ==
    426426
    427427Summary: ADD SUMMARY
     
    434434ADD EXPLANATIONS
    435435
    436 === * [Replaceable](a) ===
     436==  [Replaceable](a) ==
    437437
    438438 * [http://dev.w3.org/2006/webapi/WebIDL/#Replaceable The spec of replaceable]
     
    471471
    472472
    473 === * [Deletable](a), [NotEnumerable](a), [V8ReadOnly](a) ===
     473==  [Deletable](a), [NotEnumerable](a), [V8ReadOnly](a) ==
    474474
    475475 * [http://www.ecma-international.org/publications/files/ECMA-ST/Ecma-262.pdf The spec of Writable, Enumerable and Configurable (8.6.1)]
     
    488488[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".
    489489
    490 === * [CachedAttribute](a) ===
     490==  [CachedAttribute](a) ==
    491491
    492492Summary: For performance optimization, it indicates to cache a wrapped object in a DOM object.
     
    539539but also it increases the overhead of "cache-miss"ed getters and setters (Setters always need to invalidate the caches).
    540540
    541 === * [V8Unforgeable](m,a), [V8OnProto](m,a) ===
     541==  [V8Unforgeable](m,a), [V8OnProto](m,a) ==
    542542
    543543 * [http://dev.w3.org/2006/webapi/WebIDL/#Unforgeable The spec of Unforgeable]
     
    563563You should not use them unless you have a strong reason to use them.
    564564
    565 === * [URL](a) ===
     565==  [URL](a) ==
    566566
    567567Summary: It indicates that a given DOMString is a URL.
     
    576576If you forgot to specify [URL], then the attribute getter might cause a bug.
    577577
    578 === * [JSWindowEventListener](a) FIXME ===
     578==  [JSWindowEventListener](a) FIXME ==
    579579
    580580Summary: ADD SUMMARY
     
    587587ADD EXPLANATIONS
    588588
    589 == IDL attributes around interfaces ==
    590 
    591 === * [Supplemental](i) ===
     589==  [Supplemental](i) ==
    592590
    593591 * [http://dev.w3.org/2006/webapi/WebIDL/#dfn-supplemental-interface The spec of Supplemental]
     
    633631If 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].
    634632
    635 === * [Constructor](i), [CallWith](i,m,a), [ConstructorRaisesException](i) ===
     633==  [Constructor](i), [CallWith](i,m,a), [ConstructorRaisesException](i) ==
    636634
    637635 * [http://dev.w3.org/2006/webapi/WebIDL/#Constructor The spec of Constructor]
     
    696694Whether you should allow an interface to have constructor depends on the spec of the interface.
    697695
    698 === * [ConstructorTemplate](i), [InitializedByEventConstructor](a) ===
     696==  [ConstructorTemplate](i), [InitializedByEventConstructor](a) ==
    699697
    700698Summary: They are used for Event constructors.
     
    737735In other words, in case of Event, you should specify [InitializedByEventConstructor] on bubbles and cancelable.
    738736
    739 === * [NamedConstructor](i) ===
     737==  [NamedConstructor](i) ==
    740738
    741739 * [http://dev.w3.org/2006/webapi/WebIDL/#NamedConstructor The spec of NamedConstructor]
     
    756754Whether you should allow an interface to have a named constructor depends on the spec of the interface.
    757755
    758 === * [CustomConstructor](i), [JSCustomConstructor](i), [V8CustomConstructor](i), [ConstructorParameters](i) ===
     756==  [CustomConstructor](i), [JSCustomConstructor](i), [V8CustomConstructor](i), [ConstructorParameters](i) ==
    759757
    760758Summary: They allow us to write custom bindings for constructors.
     
    825823You do not need to specify [ConstructorParameters] if the interface does not have any of [JSCustomConstructor], [V8CustomConstructor] or [CustomConstructor].
    826824
    827 === * [Conditional](i,m,a) ===
     825==  [Conditional](i,m,a) ==
    828826
    829827Summary: It inserts "#if ENABLE(SOME_FLAG) ... #endif" into the generated code.
     
    849847If [Conditional] is specified on an interface, it means that [Conditional] is specified on all attributes and methods on the interface.
    850848
    851 === * [V8EnabledAtRuntime](i,m,a) ===
     849==  [V8EnabledAtRuntime](i,m,a) ==
    852850
    853851Summary: In Chromium/V8, we can enable/disable a flag at runtime.
     
    887885and WebKit/chromium/src/WebRuntimeFeatures.cpp for more details.
    888886
    889 === * [CustomToJSObject](i), [JSCustomToJSObject](i), [V8CustomToJSObject](i) ===
     887==  [CustomToJSObject](i), [JSCustomToJSObject](i), [V8CustomToJSObject](i) ==
    890888
    891889Summary: They allow us to write custom toJS() or toV8().
     
    919917}}}
    920918
    921 === * [CheckAccessToFrame](i), [DoNotCheckAccessToFrame](m,a), [DoNotCheckAccessToFrameOnGetter](a), [DoNotCheckAccessToFrameOnSetter](a) ===
     919==  [CheckAccessToFrame](i), [DoNotCheckAccessToFrame](m,a), [DoNotCheckAccessToFrameOnGetter](a), [DoNotCheckAccessToFrameOnSetter](a) ==
    922920
    923921Summary: It checks if a given Frame access is allowed or not, in terms of security.
     
    956954 * [DoNotCheckAccessToFrame] on an attribute is equivalent to [DoNotCheckAccessToFrameOnGetter, DoNotCheckAccessToFrameOnSetter].
    957955
    958 === * [IndexedGetter](i) ===
     956==  [IndexedGetter](i) ==
    959957
    960958 * [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)
     
    973971The bindings code is generated automatically so that XXX[i] behaves equivalent to XXX.item(i).
    974972
    975 === * [CustomIndexedSetter](i) ===
     973==  [CustomIndexedSetter](i) ==
    976974
    977975 * [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)
     
    10051003}}}
    10061004
    1007 === * [NamedGetter](i) ===
     1005==  [NamedGetter](i) ==
    10081006
    10091007 * [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)
     
    10221020The bindings code is generated automatically so that XXX.foooooooo behaves equivalent to XXX.namedItem(i).
    10231021
    1024 === [CustomNamedGetter](i), [CustomNamedSetter](i) ===
     1022== [CustomNamedGetter](i), [CustomNamedSetter](i) ==
    10251023
    10261024 * [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)
     
    10751073}}}
    10761074
    1077 === * [EventTarget](i) FIXME ===
     1075==  [EventTarget](i) FIXME ==
    10781076
    10791077Summary: ADD SUMMARY
     
    10891087ADD EXPLANATIONS
    10901088
    1091 === * [DoNotCheckConstants](i) ===
     1089==  [DoNotCheckConstants](i) ==
    10921090
    10931091Summary: [DoNotCheckConstants] stops inserting compile-time assertions for constants of a given interface.
     
    11121110you can specify [DoNotCheckConstants] on the interface to skip the compile-time assertions.
    11131111
    1114 === * [ActiveDOMObject](i) ===
     1112==  [ActiveDOMObject](i) ==
    11151113
    11161114Summary: [ActiveDOMObject] indicates that a DOM object should be kept alive when the DOM object has pending activities.
     
    11301128then the interface Y should also have [ActiveDOMObject].
    11311129
    1132 === * [V8DependentLifeTime](i) FIXME ===
     1130==  [V8DependentLifeTime](i) FIXME ==
    11331131
    11341132Summary: ADD SUMMARY
     
    11441142ADD EXPLANATIONS
    11451143
    1146 === * [CustomEnumerateProperty](i), [CustomDeleteProperty](i) ===
     1144==  [CustomEnumerateProperty](i), [CustomDeleteProperty](i) ==
    11471145
    11481146Summary: [CustomEnumerateProperty] allows us to write custom bindings for the case where properties of a given interface are enumerated.
     
    11951193}}}
    11961194
    1197 === * [IsWorkerContext](i) ===
     1195==  [IsWorkerContext](i) ==
    11981196
    11991197Summary: It indicates that the interface is a WorkerContext-related interface.
     
    12081206}}}
    12091207
    1210 === * [CustomCall](i) ===
     1208==  [CustomCall](i) ==
    12111209
    12121210Summary: [CustomCall] allows us to write custom bindings for call(...) of a given interface.
     
    12371235}}}
    12381236
    1239 === * [JSCustomToNativeObject](i), [JSCustomFinalize](i), [JSCustomIsReachable](i), [JSCustomMarkFunction](i), [JSCustomNamedGetterOnPrototype](i), [JSCustomPushEventHandlerScope](i), [JSCustomDefineOwnProperty](i), [JSCustomDefineOwnPropertyOnPrototype](i), [JSCustomGetOwnPropertySlotAndDescriptor](i) ===
     1237==  [JSCustomToNativeObject](i), [JSCustomFinalize](i), [JSCustomIsReachable](i), [JSCustomMarkFunction](i), [JSCustomNamedGetterOnPrototype](i), [JSCustomPushEventHandlerScope](i), [JSCustomDefineOwnProperty](i), [JSCustomDefineOwnPropertyOnPrototype](i), [JSCustomGetOwnPropertySlotAndDescriptor](i) ==
    12401238
    12411239Summary: They allow us to write custom code for the JavaScriptCore code which would be generated automatically by default.
     
    13291327}}}
    13301328
    1331 === * [JSGenerateToJSObject](i), [JSGenerateIsReachable](i), [JSGenerateToNativeObject](i) ===
     1329==  [JSGenerateToJSObject](i), [JSGenerateIsReachable](i), [JSGenerateToNativeObject](i) ==
    13321330
    13331331Summary: They force JavaScriptCore bindings to generate JavaScriptCore specific methods even if a given interface has a parent interface.
     
    13471345[JSGenerateToJSObject], [JSGenerateIsReachable] or [JSGenerateToNativeObject], respectively.
    13481346
    1349 === * [JSCustomHeader](i) ===
     1347==  [JSCustomHeader](i) ==
    13501348
    13511349Summary: It allows us to write a custom header for a given interface.
     
    13641362
    13651363
    1366 === * [JSLegacyParent](i) ===
     1364==  [JSLegacyParent](i) ==
    13671365
    13681366Summary: It explicitly controls the parent interface of a given interface.
     
    13781376Even if a given interface does not have a parent interface, you can specify a parent interface using [JSLegacyParent].
    13791377
    1380 === * [JSInlineGetOwnPropertySlot](i) ===
     1378==  [JSInlineGetOwnPropertySlot](i) ==
    13811379
    13821380Summary: It makes getOwnPropertySlot(...) and getOwnPropertyDescriptor(...) an inline method for performance.
     
    13901388}}}
    13911389
    1392 === * [JSNoStaticTables](i) FIXME ===
     1390==  [JSNoStaticTables](i) FIXME ==
    13931391
    13941392Summary: ADD SUMMARY
     
    14041402ADD EXPLANATIONS
    14051403
    1406 == IDL attributes used by ObjC, GObject and CPP bindings only ==
    1407 
    1408 === * [ObjCProtocol](i), [ObjCPolymorphic](i), [ObjCLegacyUnnamedParameters](m), [ObjCUseDefaultView](m), [ObjCImplementedAsUnsignedLongLong](a) ===
     1404==  [ObjCProtocol](i), [ObjCPolymorphic](i), [ObjCLegacyUnnamedParameters](m), [ObjCUseDefaultView](m), [ObjCImplementedAsUnsignedLongLong](a) ==
    14091405
    14101406Used by ObjC bindings only.
    14111407
    1412 === * [CPPPureInterface](i) ===
     1408==  [CPPPureInterface](i) ==
    14131409
    14141410Used by CPP bindings only.
    14151411
    1416 === * [CustomReturn](p) ===
     1412==  [CustomReturn](p) ==
    14171413
    14181414Used by ObjC, GObject and CPP bindings only.
    14191415
    1420 == IDL attributes which might be deprecated ==
    1421 
    1422 === * [OmitConstructor], [Immutable], [MasqueradesAsUndefined] ===
     1416==  [OmitConstructor], [Immutable], [MasqueradesAsUndefined] ==
    14231417
    14241418Might be deprecated. Discussion is on-going.
    14251419
    1426 === * [CustomGetOwnPropertySlot], [ReplaceableConstructor], [ExtendsDOMGlobalObject], [IsIndex], [V8DoNotCheckSignature], [NumericIndexedGetter] ===
     1420==  [CustomGetOwnPropertySlot], [ReplaceableConstructor], [ExtendsDOMGlobalObject], [IsIndex], [V8DoNotCheckSignature], [NumericIndexedGetter] ==
    14271421
    14281422Will be deprecated. Discussion is on-going.