241 | | == `[Default]`(p) == #Default |
242 | | |
243 | | Summary: `[Default]` allows specifying the default values for optional parameters to simplify WebCore implementations which otherwise require overloads. |
244 | | |
245 | | Standard: In Web IDL, `[Default=NullString]` is written as `"type identifier = default"`, e.g. `optional DOMString? str = null` |
246 | | |
247 | | Usage: The possible usages are `[Default=Undefined]` or `[Default=NullString]`. `[Default=Undefined]` can be specified on any optional parameter. `[Default=NullString]` can be specified on DOMString parameters only: |
248 | | |
249 | | {{{ |
250 | | interface HTMLFoo { |
251 | | void func1(int a, int b, optional int c, optional int d); |
252 | | void func2(int a, int b, [Default=Undefined] optional int c); |
253 | | void func3(int a, int b, [Default=Undefined] optional DOMString c, [Default=NullString] optional DOMString d); |
254 | | }; |
255 | | }}} |
256 | | |
257 | | The parameters marked with the standard Web IDL optional qualifier are optional, and JavaScript can omit the parameters. Obviously, if parameter X is marked with optional then all subsequent parameters of X should be marked with optional. |
258 | | |
259 | | The difference between optional and `[Default=Undefined]` optional is whether the WebCore implementation has overloaded methods or not, as explained below. |
260 | | |
261 | | In case of `func1(...)`, if JavaScript calls `func1(100, 200)`, then `HTMLFoo::func1(int a, int b)` is called in WebCore. If JavaScript calls `func1(100, 200, 300)`, then `HTMLFoo::func1(int a, int b, int c)` is called in WebCore. If JavaScript calls `func1(100, 200, 300, 400)`, then `HTMLFoo::func1(int a, int b, int c, int d)` is called in WebCore. In other words, if the WebCore implementation has overloaded methods, you can use optional. |
262 | | |
263 | | In case of `func2(...)` which adds `[Default=Undefined]`, if JavaScript calls `func2(100, 200)`, then it behaves as if JavaScript called `func2(100, 200, undefined)`. Consequently, `HTMLFoo::func2(int a, int b, int c)` is called in WebCore. 100 is passed to a, 200 is passed to b, and 0 is passed to c. (A JavaScript undefined is converted to 0, following the value conversion rule in the Web IDL spec.) In this way, WebCore needs to just implement `func2(int a, int b, int c)` and needs not to implement both `func2(int a, int b)` and `func2(int a, int b, int c)`. |
264 | | |
265 | | The difference between `[Default=Undefined]` and `[Default=NullString]` appears only when the parameter type is DOMString. In `[Default=Undefined]` the "supplemented" JavaScript undefined is converted to a WebKit string "undefined". On the other hand, in `[Default=NullString]` the "supplemented" JavaScript undefined is converted to a WebKit null string. For example, if JavaScript calls `func3(100, 200)`, then `HTMLFoo::func3(int a, int b, String c, String d)` is called in WebCore. At this point, 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. d.IsEmpty() and d.IsNull() return true. |
266 | | |