Changes between Version 19 and Version 20 of WebKitIDL


Ignore:
Timestamp:
Feb 13, 2012 3:57:33 AM (10 years ago)
Author:
haraken@chromium.org
Comment:

--

Legend:

Unmodified
Added
Removed
Modified
  • WebKitIDL

    v19 v20  
    3434Summary: They control the behavior when a JavaScript null or undefined is passed to DOMString attributes/parameters.
    3535
    36 The possible usage is [TreatNullAs=NullString] or [TreatUndefinedAs=NullString].
     36Usage: The possible usage is [TreatNullAs=NullString] or [TreatUndefinedAs=NullString].
    3737They can be specified on DOMString attributes or DOMString parameters only, like this:
    38 
    3938{{{
    4039    attribute [TreatNullAs=NullString] DOMString str;
     
    6362Summary: It controls the behavior when a WebKit null string is returned.
    6463
    65 The possible usage is [TreatReturnedNullStringAs=Null], [TreatReturnedNullStringAs=Undefined] or [TreatReturnedNullStringAs=False].
     64Usage: The possible usage is [TreatReturnedNullStringAs=Null], [TreatReturnedNullStringAs=Undefined] or [TreatReturnedNullStringAs=False].
    6665They can be specified on DOMString attributes or methods which return a DOMString value, like this:
    67 
    6866{{{
    6967    attribute [TreatReturnedNullStringAs=Null] DOMString str;
     
    8381Summary: It allows method overloading for methods whose argument count are different with each other.
    8482
    85 The possible usage is [Optional], [Optional=DefaultIsUndefined] or [Optional=DefaultIsNullString].
     83Usage: The possible usage is [Optional], [Optional=DefaultIsUndefined] or [Optional=DefaultIsNullString].
    8684[Optional] and [Optional=DefaultIsUndefined] can be specified on parameters.
    8785[Optional=DefaultIsNullString] can be specified on DOMString parameters, like this:
    88 
    8986{{{
    9087    interface HTMLFoo {
     
    110107While 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.
    111108
    112 
    113 === * [Callback](i,p) ===
    114 
    115 Summary: ???
    116 
    117 The possible usage is [Callback]. [Callback] can be specified on interfaces and parameters.
    118 
    119 FIXME: ADD EXPLANATIONS
     109=== * [Callback](i,p) FIXME ===
     110
     111Summary: ADD SUMMARY
     112
     113Usage: [Callback] can be specified on interfaces and parameters, like this:
     114{{{
     115    interface [
     116        Callback
     117    ] HTMLFoo {
     118        void func(in int a, in [Callback] int b);
     119    }
     120}}}
     121
     122ADD EXPLANATIONS
    120123
    121124=== * [Custom](m,a), [JSCustom](m,a), [V8Custom](m,a), [CustomGetter](a), [JSCustomGetter](a), [V8CustomGetter](a), [CustomSetter](a), [JSCustomSetter](a), [V8CustomSetter](a) ===
     
    125128=== * [CheckAccessToNode](m,a) ===
    126129
    127 === * [StrictTypeChecking](m,a) ===
     130=== * [StrictTypeChecking](m,a) FIXME ===
     131
     132Summary: ADD SUMMARY
     133
     134Usage: [StrictTypeChecking] can be specified on methods and attributes, like this:
     135{{{
     136    attribute [StringTypeChecking] float x;
     137    [StrictTypeChecking] DOMString func();
     138}}}
     139
     140ADD EXPLANATIONS
    128141
    129142=== * [ReturnNewObject](m,a) ===
     
    131144=== * [ImplementedAs](m) ===
    132145
    133 === * [Reflect](a) ===
     146Summary: It specifies a method name in WebCore implementation, if the IDL method name and the WebCore method name are different.
     147
     148Usage: The possible usage is [ImplementedAs=XXX], where XXX is a method name of the WebCore implementation. It can be specified on methods, like this:
     149{{{
     150    void [ImplementedAs=deleteFunction] delete();
     151}}}
     152
     153Basically, the WebCore method name should be equal to the IDL method name.
     154That being said, sometimes you cannot use the same method name; e.g. "delete" is a C++ keyword.
     155In such cases, you can explicitly specify the WebCore method name by [ImplementedAs].
     156You should avoid using [ImplementedAs] as much as possible though.
     157
     158=== * [Reflect](a) FIXME ===
     159
     160Summary: ADD SUMMARY
     161
     162Usage: [Reflect] can be specified on attributes.
     163{{{
     164    attribute [Reflect] DOMString str;
     165}}}
     166
     167ADD EXPLANATIONS
    134168
    135169=== * [Replaceable](a) ===
     
    137171=== * [Deletable](a), [NotEnumerable](a), [V8ReadOnly](a) ===
    138172
     173 * [http://www.ecma-international.org/publications/files/ECMA-ST/Ecma-262.pdf The spec of [[Writable]], [[Enumerable]] and [[Configurable]] (8.6.1)]
     174
     175Summary: They control Writability, Enumerability and Configurability of attributes.
     176
     177Usage: They can be specified on attributes, like this:
     178{{{
     179    attribute [NotEnumerable, Deletable] DOMString str;
     180    readonly attribute DOMString readonlyStr;
     181    attribute [V8ReadOnly] DOMString readonlyStrOnV8;
     182}}}
     183
     184By default, non-"readonly" attributes are enumerable, writable and not deletable. "readonly" attributes are enumerable, not writable and not deletable. You can change the default behavior using [Deletable], [NotEnumerable] or [V8ReadOnly].
     185
     186[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".
     187
    139188=== * [CachedAttribute](a) ===
    140189
    141 === * [V8Unforgeable](a), [V8OnInstance](a), [V8OnProto](a) ===
     190Summary: For performance optimization, it indicates to cache a wrapped object in a DOM object.
     191
     192Usage: It can be specified on attributes, like this:
     193{{{
     194    interface HTMLFoo {
     195        attribute [CachedAttribute] DOMString normalValue;
     196        attribute [CachedAttribute] SerializedScriptValue serializedValue;
     197    }
     198}}}
     199
     200Without [CachedAttribute], the normalValue getter works in the following way:
     201
     202 * HTMLFoo::normalValue() is called.
     203 * The result is passed to toJS() or toV8(), and is converted to a wrapper object.
     204 * The wrapper object is returned.
     205
     206In case where HTMLFoo::normalValue() and wrapping the result is weight,
     207you can cache the wrapped object in the DOM object by using [CachedAttribute].
     208With [CachedAttribute], the normalValue getter works in the following way:
     209
     210 * If the wrapper object is cached, the cached wrapper object is returned.
     211 * Otherwise, HTMLFoo::normalValue() is called.
     212 * The result is passed to toJS() or toV8(), and is converted to a wrapped object.
     213 * The wrapped object is cached.
     214 * The wrapped object is returned.
     215
     216In particular, [CachedAttribute] will be helpful for serialized values.
     217Without [CachedAttribute], the serializedValue getter works in the following way:
     218
     219 * HTMLFoo::serializedValue() is called.
     220 * The result is deserialized.
     221 * The deserialized result is passed to toJS() or toV8(), and is converted to a wrapped object.
     222 * The wrapped object is returned.
     223
     224In case where HTMLFoo::serializedValue(), deserializing and wrapping the result is weight,
     225you can cache the wrapped object to the DOM object by specifying [CachedAttribute].
     226With [CachedAttribute], the serializedValue getter works in the following way:
     227
     228 * If the wrapper object is cached, the cached wrapper object is returned.
     229 * Otherwise, HTMLFoo::serializedValue() is called.
     230 * The result is deserialized.
     231 * The deserialized result is passed to toJS() or toV8(), and is converted to a wrapped object.
     232 * The wrapped object is cached.
     233 * The wrapped object is returned.
     234
     235Note that you should cache attributes if and only if it is really important for performance.
     236Not only does caching increase the DOM object size,
     237but also it increases the overhead of "cache-miss"ed getters and setters (Setters always need to invalidate the caches).
     238
     239=== * [V8Unforgeable](m,a), [V8OnProto](m,a) ===
     240
     241 * [http://dev.w3.org/2006/webapi/WebIDL/#Unforgeable The spec of [Unforgeable]]
     242
     243Summary: They control where a given attribute getter/setter is defined.
     244
     245Usage: They can be specified on attributes, like this:
     246{{{
     247    attribute [V8Unforgeable] DOMString str1;
     248    attribute [V8OnProto] DOMString str2;
     249}}}
     250
     251By default in JSC and V8, attribute getters/setters are defined on a DOM object, and methods are defined on a prototype chain
     252(although the Web IDL spec requires that both attribute getters/setters and methods should be defined on a prototype chain).
     253
     254If you want to explicitly control where an attribute getter/setter or a method is defined in V8,
     255you can use [V8Unforgeable] or [V8OnProto].
     256[V8Unforgeable] indicates that the attribute getter/setter or the method should be defined on a DOM object.
     257On the other hand, [V8OnProto] indicates that the attribute getter/setter or the method should be defined on a chain.
     258
     259Note: As explained above, the current implementation of JSC and V8 is wrong to the Web IDL spec,
     260and [V8Unforgeable] and [V8OnProto] are used for hack.
     261You should not use them unless you have a strong reason to use them.
    142262
    143263=== * [URL](a) ===
    144264
     265Summary: It indicates that a given DOMString is a URL.
     266
     267Usage: It can be specified on DOMString attributes, like this:
     268{{{
     269    attribute [Reflect, V8URL] DOMString url;
     270}}}
     271
     272You must specify [URL] if the DOMString represents URL,
     273since URL attribute getters are realized in a special routine in WebKit, i.e. Element::getURLAttribute().
     274If you forgot to specify [URL], then the attribute getter might cause a bug.
     275
    145276=== * [JSWindowEventListener](a) ===
    146277
     
    153284 * [http://old.nabble.com/Things-missing-from-Web-IDL-for-HTML5-td24873773.html Easy explanation of [Supplemental\]]
    154285
    155 The [Supplemental] IDL helps WebKit modularization. The [Supplemental] IDL makes it possible to add XXX's APIs (e.g. XXX=WebAudio, WebSocket, Blob, GamePad, ...etc) without modifying code outside of WebCore/Modules/XXX/. This helps make XXX a "self-contained module".
    156 
    157 Here is an example. Without the [Supplemental] IDL, if we want to add XXX's attributes or methods to DOMWindow,
     286Summary: [Supplemental] helps WebKit modularization. The [Supplemental] IDL makes it possible to add XXX's APIs (e.g. XXX=WebAudio, WebSocket, Blob, GamePad, ...etc) without modifying code outside of WebCore/Modules/XXX/. This helps make XXX a "self-contained module".
     287
     288Usage: The possible usage is
     289{{{
     290    interface [Supplemental=YYY] XXX { ... }
     291}}}
     292where XXX implements YYY. [Supplemental] can be specified on interfaces.
     293
     294Here is an example. Without [Supplemental], if we want to add XXX's attributes or methods to DOMWindow,
    158295
    159296 * we need to modify WebCore/page/DOMWindow.idl to add the IDLs of the XXX's attributes or methods
     
    161298 * we need to modify WebCore/page/DOMWindow.{h,cpp} to add the C++ implementation of the attribute getters and setters or the method callbacks.
    162299
    163 On the other hand, in the modularized world with the [Supplemental] IDL, we just need to modify the code under WebCore/Modules/XXX/, like this:
     300On the other hand, in the modularized world with [Supplemental], we just need to modify the code under WebCore/Modules/XXX/, like this:
    164301
    165302 * WebCore/Modules/XXX/DOMWindowXXX.idl
     
    183320As 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, we can implement the attributes and methods without modifying code of DOMWindow.{h,cpp,idl}.
    184321
    185 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 the [Supplemental] IDL.
     322If 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].
    186323
    187324=== * [Constructor](i), [ConstructorCallWith](i), [ConstructorRaisesException](i) ===