Changes between Version 52 and Version 53 of WebKitIDL


Ignore:
Timestamp:
Feb 20, 2012 6:02:44 AM (12 years ago)
Author:
haraken@chromium.org
Comment:

--

Legend:

Unmodified
Added
Removed
Modified
  • WebKitIDL

    v52 v53  
    105105 - [#CustomReturn CustomReturn(p)]
    106106
    107  - [#OmitConstructor OmitConstructor, Immutable, MasqueradesAsUndefined]
    108 
    109  - [#CustomGetOwnPropertySlot CustomGetOwnPropertySlot, ReplaceableConstructor, ExtendsDOMGlobalObject, IsIndex, V8DoNotCheckSignature, NumericIndexedGetter]
     107 - [#OmitConstructor OmitConstructor, Immutable, MasqueradesAsUndefined, CustomGetOwnPropertySlot, ReplaceableConstructor, ExtendsDOMGlobalObject, IsIndex, V8DoNotCheckSignature, NumericIndexedGetter]
    110108
    111109
     
    242240In 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.
    243241
    244 ==  [TreatNullAs](a,p), [TreatUndefinedAs](a,p) == #TreatNullAs
     242== [TreatNullAs](a,p), [TreatUndefinedAs](a,p) == #TreatNullAs
    245243
    246244 * [http://dev.w3.org/2006/webapi/WebIDL/#TreatNullAs The spec of TreatNullAs] (Note: The WebKit behavior explained below is different from the spec)
     
    273271[TreatUndefinedAs=NullString] must be used with [TreatNullAs=NullString], i.e. [TreatNullAs=NullString, TreatUndefinedAs=NullString].
    274272
    275 ==  [TreatReturnedNullStringAs](m,a) == #TreatReturnedNullStringAs
     273== [TreatReturnedNullStringAs](m,a) == #TreatReturnedNullStringAs
    276274
    277275Summary: [TreatReturnedNullStringAs] controls the behavior when a WebKit null string is returned from the WebCore implementation.
     
    292290Note that what should be specified on [TreatReturnedNullStringAs=...] depends on the spec of each attribute or method.
    293291
    294 ==  [Optional](p) == #Optional
     292== [Optional](p) == #Optional
    295293
    296294Summary: [Optional] allows method overloading for methods whose argument counts are different with each other.
     
    329327d.IsEmpty() and d.IsNull() return true.
    330328
    331 ==  [Callback](i,p) FIXME == #Callback
     329== [Callback](i,p) FIXME == #Callback
    332330
    333331Summary: ADD SUMMARY
     
    344342ADD EXPLANATIONS
    345343
    346 ==  [Custom](m,a), [JSCustom](m,a), [V8Custom](m,a), [CustomGetter](a), [JSCustomGetter](a), [V8CustomGetter](a), [CustomSetter](a), [JSCustomSetter](a), [V8CustomSetter](a) == #Custom
     344== [Custom](m,a), [JSCustom](m,a), [V8Custom](m,a), [CustomGetter](a), [JSCustomGetter](a), [V8CustomGetter](a), [CustomSetter](a), [JSCustomSetter](a), [V8CustomSetter](a) == #Custom
    347345
    348346Summary: They allow you to write bindings code manually as you like.
     
    471469Note: ObjC, GObject and CPP bindings do not support custom bindings.
    472470
    473 ==  [CallWith](i,m,a) == #CallWith
     471== [CallWith](i,m,a) == #CallWith
    474472
    475473Summary: [CallWith] indicates that the bindings code calls a WebCore method with additional information.
     
    503501For example, in case of func4(...), HTMLFoo::func3(ScriptArguments* arguments, ScriptCallStack* callstack, int a, int b) is called in WebCore.
    504502
    505 ==  [StrictTypeChecking](m,a) FIXME == #StrictTypeChecking
     503== [StrictTypeChecking](m,a) FIXME == #StrictTypeChecking
    506504
    507505Summary: ADD SUMMARY
     
    515513ADD EXPLANATIONS
    516514
    517 ==  [ReturnNewObject](m,a) == #ReturnNewObject
     515== [ReturnNewObject](m,a) == #ReturnNewObject
    518516
    519517Summary: [ReturnNewObject] controls whether WebCore can return a cached wrapped object or WebCore needs to return a newly created wrapped object every time.
     
    539537you can specify [ReturnNewObject].
    540538
    541 ==  [ImplementedAs](m) == #ImplementedAs
     539== [ImplementedAs](m) == #ImplementedAs
    542540
    543541Summary: [ImplementedAs] specifies a method name in WebCore, if the method name in an IDL file and the method name in WebCore are different.
     
    554552You should avoid using [ImplementedAs] as much as possible though.
    555553
    556 ==  [Reflect](a) FIXME == #Reflect
     554== [Reflect](a) FIXME == #Reflect
    557555
    558556Summary: ADD SUMMARY
     
    601599Whether [Replaceable] should be specified or not depends on the spec of each attribute.
    602600
    603 ==  [Deletable](a), [NotEnumerable](a), [V8ReadOnly](a) == #Deletable
     601== [Deletable](a), [NotEnumerable](a), [V8ReadOnly](a) == #Deletable
    604602
    605603 * [http://www.ecma-international.org/publications/files/ECMA-ST/Ecma-262.pdf The spec of Writable, Enumerable and Configurable (Section 8.6.1)]
     
    672670In addition, setters always need to invalidate the cache.
    673671
    674 ==  [V8Unforgeable](m,a), [V8OnProto](m,a) == #V8Unforgeable
     672== [V8Unforgeable](m,a), [V8OnProto](m,a) == #V8Unforgeable
    675673
    676674 * [http://dev.w3.org/2006/webapi/WebIDL/#Unforgeable The spec of Unforgeable]
     
    721719ADD EXPLANATIONS
    722720
    723 ==  [Supplemental](i) == #Supplemental
     721== [Supplemental](i) == #Supplemental
    724722
    725723 * [http://dev.w3.org/2006/webapi/WebIDL/#dfn-supplemental-interface The spec of Supplemental]
     
    883881In other words, in case of Event, you should specify [InitializedByEventConstructor] on bubbles and cancelable.
    884882
    885 ==  [NamedConstructor](i) == #NamedConstructor
     883== [NamedConstructor](i) == #NamedConstructor
    886884
    887885 * [http://dev.w3.org/2006/webapi/WebIDL/#NamedConstructor The spec of NamedConstructor]
     
    903901Whether you should allow an interface to have a named constructor or not depends on the spec of each interface.
    904902
    905 ==  [CustomConstructor](i), [JSCustomConstructor](i), [V8CustomConstructor](i), [ConstructorParameters](i) == #CustomConstructor
     903== [CustomConstructor](i), [JSCustomConstructor](i), [V8CustomConstructor](i), [ConstructorParameters](i) == #CustomConstructor
    906904
    907905Summary: They allow you to write custom bindings for constructors.
     
    997995If [Conditional] is specified on an interface, it means that [Conditional] is specified on all attributes and methods of the interface.
    998996
    999 ==  [V8EnabledAtRuntime](i,m,a) == #V8EnabledAtRuntime
     997== [V8EnabledAtRuntime](i,m,a) == #V8EnabledAtRuntime
    1000998
    1001999Summary: In Chromium/V8, you can enable or disable a flag at runtime.
     
    10341032it means that [V8EnabledAtRuntime] is specified on all the attributes and methods of the interface,
    10351033
    1036 ==  [CustomToJSObject](i), [JSCustomToJSObject](i), [V8CustomToJSObject](i) == #CustomToJSObject
     1034== [CustomToJSObject](i), [JSCustomToJSObject](i), [V8CustomToJSObject](i) == #CustomToJSObject
    10371035
    10381036Summary: They allow you to write custom toJS() or toV8().
     
    11061104 * [DoNotCheckSecurity] on an attribute is equivalent to [DoNotCheckSecurityOnGetter, DoNotCheckSecurityOnSetter].
    11071105
    1108 ==  [CheckSecurityForNode](m,a) == #CheckSecurityForNode
     1106== [CheckSecurityForNode](m,a) == #CheckSecurityForNode
    11091107
    11101108Summary: [CheckSecurityForNode] checks whether a given access to Node is allowed or not, in terms of the same-origin security policy.
     
    11731171}}}
    11741172
    1175 ==  [NamedGetter](i) == #NamedGetter
     1173== [NamedGetter](i) == #NamedGetter
    11761174
    11771175 * [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)
     
    12471245}}}
    12481246
    1249 ==  [EventTarget](i) FIXME == #EventTarget
     1247== [EventTarget](i) FIXME == #EventTarget
    12501248
    12511249Summary: ADD SUMMARY
     
    12611259ADD EXPLANATIONS
    12621260
    1263 ==  [DoNotCheckConstants](i) == #DoNotCheckConstants
    1264 
    1265 Summary: [DoNotCheckConstants] stops inserting compile-time assertions for constants of a given interface.
     1261== [DoNotCheckConstants](i) == #DoNotCheckConstants
     1262
     1263Summary: [DoNotCheckConstants] indicates that constant values in an IDL file can be different from constant values in WebCore implementation.
    12661264
    12671265Usage: [DoNotCheckConstants] can be specified on interfaces:
     
    12701268        DoNotCheckConstants
    12711269    ] XXX {
    1272         const unsigned short NOT_FOUND_ERR = 123;
    1273         const unsigned short SYNTAX_ERR = 124;
    1274     };
    1275 }}}
    1276 
    1277 Without [DoNotCheckConstants], compile-time assertions are generated to check if the constant values defined in IDL files
    1278 are equal to the constant values in WebKit implementation.
    1279 In the above example, if NOT_FOUND_ERR were 100 in WebKit implementation, the build will fail.
    1280 Basically values of all constants are defined in the spec,
    1281 and thus the values defined in IDL files and the values in WebKit implementations should be equal to the values defined in the spec.
    1282 
    1283 If you want to introduce non-speced constant values and allow different values between IDL files and WebKit implementation,
    1284 you can specify [DoNotCheckConstants] on the interface to skip the compile-time assertions.
    1285 
    1286 ==  [ActiveDOMObject](i) == #ActiveDOMObject
    1287 
    1288 Summary: [ActiveDOMObject] indicates that a DOM object should be kept alive when the DOM object has pending activities.
     1270        const unsigned short NOT_FOUND_ERR = 12345;
     1271        const unsigned short SYNTAX_ERR = 12346;
     1272    };
     1273}}}
     1274
     1275By default (i.e. without [DoNotCheckConstants]), compile-time assertions are inserted to check if the constant values defined in IDL files
     1276are equal to the constant values in WebCore implementation.
     1277In the above example, if NOT_FOUND_ERR were implemented as 100 in WebCore, the build will fail.
     1278
     1279Note that basically all constant values are defined in the spec,
     1280and thus the values in WebCore implementation should be equal to the values defined in the spec.
     1281If you really want to introduce non-speced constant values and allow different values between IDL files and WebCore implementation,
     1282you can specify [DoNotCheckConstants] to skip the compile-time assertions.
     1283
     1284== [ActiveDOMObject](i) == #ActiveDOMObject
     1285
     1286Summary: [ActiveDOMObject] indicates that a given DOM object should be kept alive as long as the DOM object has pending activities.
    12891287
    12901288Usage: [ActiveDOMObject] can be specified on interfaces:
     
    12971295
    12981296If a given DOM object needs to be kept alive as long as the DOM object has pending activities, you need to specify [ActiveDOMObject].
    1299 For example, [ActiveDOMObject] can be used when the DOM object is expecting events to be raised.
     1297For example, [ActiveDOMObject] can be used when the DOM object is expecting events to be raised in the future.
    13001298
    13011299If an interface X has [ActiveDOMObject] and an interface Y inherits the interface X,
    13021300then the interface Y should also have [ActiveDOMObject].
    13031301
    1304 ==  [V8DependentLifeTime](i) FIXME == #V8DependentLifeTime
     1302== [V8DependentLifeTime](i) FIXME == #V8DependentLifeTime
    13051303
    13061304Summary: ADD SUMMARY
     
    13161314ADD EXPLANATIONS
    13171315
    1318 ==  [CustomEnumerateProperty](i), [CustomDeleteProperty](i) == #CustomEnumerateProperty
     1316== [CustomEnumerateProperty](i), [CustomDeleteProperty](i) == #CustomEnumerateProperty
    13191317
    13201318Summary: [CustomEnumerateProperty] allows you to write custom bindings for the case where properties of a given interface are enumerated.
     
    13301328}}}
    13311329
    1332 With [CustomEnumerateProperty], you can write custom bindings when properties of XXX are enumerated.
     1330 * [CustomEnumerateProperty] in JavaScriptCore: You can write custom bindings when properties of XXX are enumerated.
    13331331Specifically, you can write JSXXX::getOwnPropertyNames(...) in WebCore/bindings/js/JSXXXCustom.cpp:
     1332
    13341333{{{
    13351334    void JSXXX::getOwnPropertyNames(JSObject* object, ExecState* exec, PropertyNameArray& propertyNames, EnumerationMode mode)
     
    13381337    }
    13391338}}}
    1340 and V8XXX::namedPropertyQuery(...) and V8XXX::namedPropertyEnumerator(...) in WebCore/bindings/v8/custom/V8XXXCustom.cpp:
     1339
     1340 * [CustomEnumerateProperty] in V8: You can write custom bindings as V8XXX::namedPropertyQuery(...) and V8XXX::namedPropertyEnumerator(...) in WebCore/bindings/v8/custom/V8XXXCustom.cpp:
     1341
    13411342{{{
    13421343    v8::Handle<v8::Integer> V8XXX::namedPropertyQuery(v8::Local<v8::String> name, const v8::AccessorInfo& info)
     
    13511352}}}
    13521353
    1353 With [CustomDeleteProperty], you can write custom bindings for the case where a property of XXX is deleted.
     1354 * [CustomDeleteProperty] in JavaScriptCore: You can write custom bindings for the case where a property of XXX is deleted.
    13541355Specifically, you can write JSXXX::deleteProperty(...) in WebCore/bindings/js/JSXXXCustom.cpp:
     1356
    13551357{{{
    13561358    bool JSXXX::deleteProperty(JSCell* cell, ExecState* exec, const Identifier& propertyName)
     
    13591361    }
    13601362}}}
    1361 and V8XXX::namedPropertyDeleter(...) in WebCore/bindings/v8/custom/V8XXXCustom.cpp:
     1363
     1364 * [CustomDeleteProperty] in V8: You can write custom bindings as V8XXX::namedPropertyDeleter(...) in WebCore/bindings/v8/custom/V8XXXCustom.cpp:
     1365
    13621366{{{
    13631367    v8::Handle<v8::Boolean> V8XXX::namedPropertyDeleter(v8::Local<v8::String> name, const v8::AccessorInfo& info)
     
    13671371}}}
    13681372
    1369 ==  [IsWorkerContext](i) == #IsWorkerContext
    1370 
    1371 Summary: It indicates that the interface is a WorkerContext-related interface.
    1372 
    1373 Usage: [IsWorkerContext] can be specified on WorkerContext-related interfaces:
     1373== [IsWorkerContext](i) == #IsWorkerContext
     1374
     1375Summary: [IsWorkerContext] indicates that a given interface is a WorkerContext-related interface.
     1376
     1377Usage: [IsWorkerContext] can be specified on WorkerContext-related interfaces only:
    13741378{{{
    13751379    interface [
    13761380        IsWorkerContext
    13771381    ] SharedWorkerContext {
    1378         ...;
    1379     };
    1380 }}}
    1381 
    1382 ==  [CustomCall](i) == #CustomCall
     1382    };
     1383}}}
     1384
     1385== [CustomCall](i) == #CustomCall
    13831386
    13841387Summary: [CustomCall] allows you to write custom bindings for call(...) of a given interface.
     
    14111414}}}
    14121415
    1413 ==  [JSCustomToNativeObject](i), [JSCustomFinalize](i), [JSCustomIsReachable](i), [JSCustomMarkFunction](i), [JSCustomNamedGetterOnPrototype](i), [JSCustomPushEventHandlerScope](i), [JSCustomDefineOwnProperty](i), [JSCustomDefineOwnPropertyOnPrototype](i), [JSCustomGetOwnPropertySlotAndDescriptor](i) == #JSCustomToNativeObject
     1416== [JSCustomToNativeObject](i), [JSCustomFinalize](i), [JSCustomIsReachable](i), [JSCustomMarkFunction](i), [JSCustomNamedGetterOnPrototype](i), [JSCustomPushEventHandlerScope](i), [JSCustomDefineOwnProperty](i), [JSCustomDefineOwnPropertyOnPrototype](i), [JSCustomGetOwnPropertySlotAndDescriptor](i) == #JSCustomToNativeObject
    14141417
    14151418Summary: They allow you to write custom code for the JavaScriptCore code that would be generated automatically by default.
     
    15121515}}}
    15131516
    1514 ==  [JSGenerateToJSObject](i), [JSGenerateIsReachable](i), [JSGenerateToNativeObject](i) == #JSGenerateToJSObject
    1515 
    1516 Summary: They force JavaScriptCore bindings to generate JavaScriptCore specific methods even if a given interface has a parent interface.
     1517== [JSGenerateToJSObject](i), [JSGenerateIsReachable](i), [JSGenerateToNativeObject](i) == #JSGenerateToJSObject
     1518
     1519Summary: They force JavaScriptCore bindings to generate JavaScriptCore-specific methods, even if a given interface has a parent interface.
    15171520
    15181521Usage: They can be specified on interfaces that do not have a parent interface:
     
    15261529}}}
    15271530
    1528 toJS(...), isReachableFromOpaqueRoots(...) or toXXX() are not generated if the interface has a parent interface.
    1529 If you want to generate it even if the interface does not have a parent interface, you can specify
     1531toJS(...), isReachableFromOpaqueRoots(...) or toXXX() is not generated if XXX has a parent interface.
     1532If you want to generate it even if XXX does not have a parent interface, you can specify
    15301533[JSGenerateToJSObject], [JSGenerateIsReachable] or [JSGenerateToNativeObject], respectively.
    15311534
    1532 ==  [JSCustomHeader](i) == #JSCustomHeader
    1533 
    1534 Summary: It allows you to write a custom header for a given interface.
     1535== [JSCustomHeader](i) == #JSCustomHeader
     1536
     1537Summary: [JSCustomHeader] allows you to write a custom header for a given interface.
    15351538
    15361539Usage: [JSCustomHeader] can be specified on interfaces:
     
    15421545}}}
    15431546
    1544 By default, JSXXX.h and JSXXX.cpp are generated automatically, and if you need,
    1545 you can write custom bindings in WebCore/bindings/js/JSXXXCustom.cpp.
    1546 On the other hand, [JSCustomHeader] allows you to write WebCore/bindings/js/JSXXXCustom.h, which is included by JSXXX.h.
    1547 
    1548 
    1549 ==  [JSLegacyParent](i) == #JSLegacyParent
    1550 
    1551 Summary: It explicitly controls the parent interface of a given interface.
    1552 
    1553 Usage: [JSLegacyParent] can be specified on interfaces:
     1547By default, JSXXX.h and JSXXX.cpp are generated automatically.
     1548By specifying [Custom*], you can write custom bindings in WebCore/bindings/js/JSXXXCustom.cpp.
     1549In addition, by specifying [JSCustomHeader], you can write custom header in WebCore/bindings/js/JSXXXCustom.h, which will be included by JSXXX.h.
     1550
     1551== [JSLegacyParent](i) == #JSLegacyParent
     1552
     1553Summary: [JSLegacyParent] explicitly controls the parent interface of a given interface.
     1554
     1555Usage: [JSLegacyParent] can be specified on interfaces that do not have a parent interface:
    15541556{{{
    15551557    interface [
     
    15611563Even if a given interface does not have a parent interface, you can specify a parent interface using [JSLegacyParent].
    15621564
    1563 ==  [JSInlineGetOwnPropertySlot](i) == #JSInlineGetOwnPropertySlot
    1564 
    1565 Summary: It makes getOwnPropertySlot(...) and getOwnPropertyDescriptor(...) an inline method for performance.
     1565== [JSInlineGetOwnPropertySlot](i) == #JSInlineGetOwnPropertySlot
     1566
     1567Summary: For performance, [JSInlineGetOwnPropertySlot] makes getOwnPropertySlot(...) and getOwnPropertyDescriptor(...) an inline method.
    15661568
    15671569Usage: [JSInlineGetOwnPropertySlot] can be specified on interfaces:
     
    15731575}}}
    15741576
    1575 ==  [JSNoStaticTables](i) FIXME == #JSNoStaticTables
     1577== [JSNoStaticTables](i) FIXME == #JSNoStaticTables
    15761578
    15771579Summary: ADD SUMMARY
     
    15871589ADD EXPLANATIONS
    15881590
    1589 ==  [ObjCProtocol](i), [ObjCPolymorphic](i), [ObjCLegacyUnnamedParameters](m), [ObjCUseDefaultView](m), [ObjCImplementedAsUnsignedLongLong](a) == #ObjCProtocol
     1591== [ObjCProtocol](i), [ObjCPolymorphic](i), [ObjCLegacyUnnamedParameters](m), [ObjCUseDefaultView](m), [ObjCImplementedAsUnsignedLongLong](a) == #ObjCProtocol
    15901592
    15911593Used by ObjC bindings only.
    15921594
    1593 ==  [CPPPureInterface](i) == #CPPPureInterface
     1595== [CPPPureInterface](i) == #CPPPureInterface
    15941596
    15951597Used by CPP bindings only.
    15961598
    1597 ==  [CustomReturn](p) == #CustomReturn
     1599== [CustomReturn](p) == #CustomReturn
    15981600
    15991601Used by ObjC, GObject and CPP bindings only.
    16001602
    1601 ==  [OmitConstructor], [Immutable], [MasqueradesAsUndefined] == #OmitConstructor
     1603== [OmitConstructor], [Immutable], [MasqueradesAsUndefined], [CustomGetOwnPropertySlot], [ReplaceableConstructor], [ExtendsDOMGlobalObject], [IsIndex], [V8DoNotCheckSignature], [NumericIndexedGetter]== #OmitConstructor
    16021604
    16031605Might be deprecated. Discussion is on-going.
    1604 
    1605 ==  [CustomGetOwnPropertySlot], [ReplaceableConstructor], [ExtendsDOMGlobalObject], [IsIndex], [V8DoNotCheckSignature], [NumericIndexedGetter] == #CustomGetOwnPropertySlot
    1606 
    1607 Will be deprecated. Discussion is on-going.