| 133 | | === * [Reflect](a) === |
| | 146 | Summary: It specifies a method name in WebCore implementation, if the IDL method name and the WebCore method name are different. |
| | 147 | |
| | 148 | Usage: 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 | |
| | 153 | Basically, the WebCore method name should be equal to the IDL method name. |
| | 154 | That being said, sometimes you cannot use the same method name; e.g. "delete" is a C++ keyword. |
| | 155 | In such cases, you can explicitly specify the WebCore method name by [ImplementedAs]. |
| | 156 | You should avoid using [ImplementedAs] as much as possible though. |
| | 157 | |
| | 158 | === * [Reflect](a) FIXME === |
| | 159 | |
| | 160 | Summary: ADD SUMMARY |
| | 161 | |
| | 162 | Usage: [Reflect] can be specified on attributes. |
| | 163 | {{{ |
| | 164 | attribute [Reflect] DOMString str; |
| | 165 | }}} |
| | 166 | |
| | 167 | ADD EXPLANATIONS |
| | 173 | * [http://www.ecma-international.org/publications/files/ECMA-ST/Ecma-262.pdf The spec of [[Writable]], [[Enumerable]] and [[Configurable]] (8.6.1)] |
| | 174 | |
| | 175 | Summary: They control Writability, Enumerability and Configurability of attributes. |
| | 176 | |
| | 177 | Usage: 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 | |
| | 184 | By 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 | |
| 141 | | === * [V8Unforgeable](a), [V8OnInstance](a), [V8OnProto](a) === |
| | 190 | Summary: For performance optimization, it indicates to cache a wrapped object in a DOM object. |
| | 191 | |
| | 192 | Usage: 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 | |
| | 200 | Without [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 | |
| | 206 | In case where HTMLFoo::normalValue() and wrapping the result is weight, |
| | 207 | you can cache the wrapped object in the DOM object by using [CachedAttribute]. |
| | 208 | With [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 | |
| | 216 | In particular, [CachedAttribute] will be helpful for serialized values. |
| | 217 | Without [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 | |
| | 224 | In case where HTMLFoo::serializedValue(), deserializing and wrapping the result is weight, |
| | 225 | you can cache the wrapped object to the DOM object by specifying [CachedAttribute]. |
| | 226 | With [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 | |
| | 235 | Note that you should cache attributes if and only if it is really important for performance. |
| | 236 | Not only does caching increase the DOM object size, |
| | 237 | but 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 | |
| | 243 | Summary: They control where a given attribute getter/setter is defined. |
| | 244 | |
| | 245 | Usage: They can be specified on attributes, like this: |
| | 246 | {{{ |
| | 247 | attribute [V8Unforgeable] DOMString str1; |
| | 248 | attribute [V8OnProto] DOMString str2; |
| | 249 | }}} |
| | 250 | |
| | 251 | By 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 | |
| | 254 | If you want to explicitly control where an attribute getter/setter or a method is defined in V8, |
| | 255 | you can use [V8Unforgeable] or [V8OnProto]. |
| | 256 | [V8Unforgeable] indicates that the attribute getter/setter or the method should be defined on a DOM object. |
| | 257 | On the other hand, [V8OnProto] indicates that the attribute getter/setter or the method should be defined on a chain. |
| | 258 | |
| | 259 | Note: As explained above, the current implementation of JSC and V8 is wrong to the Web IDL spec, |
| | 260 | and [V8Unforgeable] and [V8OnProto] are used for hack. |
| | 261 | You should not use them unless you have a strong reason to use them. |
| 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, |
| | 286 | Summary: [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 | |
| | 288 | Usage: The possible usage is |
| | 289 | {{{ |
| | 290 | interface [Supplemental=YYY] XXX { ... } |
| | 291 | }}} |
| | 292 | where XXX implements YYY. [Supplemental] can be specified on interfaces. |
| | 293 | |
| | 294 | Here is an example. Without [Supplemental], if we want to add XXX's attributes or methods to DOMWindow, |
