Changes between Version 18 and Version 19 of WebKitIDL


Ignore:
Timestamp:
Feb 13, 2012 1:22:24 AM (12 years ago)
Author:
haraken@chromium.org
Comment:

--

Legend:

Unmodified
Added
Removed
Modified

  • WebKitIDL

    v18 v19  
    2323== Basic naming rules ==
    2424
    25 == IDL attributes around operations, attributes and parameters ==
    26 
    27 In the following explanations, (i), (o), (a) and (p) means that the IDL attribute can be specified on interfaces, operations, attributes and parameters, respectively. For example, (a,p) means that the IDL attribute can be specified on attributes and parameters.
     25== IDL attributes around methods, attributes and parameters ==
     26
     27In 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.
    2828
    2929=== * [TreatNullAs](a,p), [TreatUndefinedAs](a,p) ===
    3030
    31  * [http://dev.w3.org/2006/webapi/WebIDL/#TreatNullAs The spec of [TreatNullAs\]] (Note: The WebKit IDL explained below behaves differently from the spec)
    32  * [http://dev.w3.org/2006/webapi/WebIDL/#TreatUndefinedAs The spec of [TreatUndefinedAs\]] (Note: The WebKit IDL explained below behaves differently from the spec)
     31 * [http://dev.w3.org/2006/webapi/WebIDL/#TreatNullAs The spec of [TreatNullAs]] (Note: The WebKit IDL explained below behaves differently from the spec)
     32 * [http://dev.w3.org/2006/webapi/WebIDL/#TreatUndefinedAs The spec of [TreatUndefinedAs]] (Note: The WebKit IDL explained below behaves differently from the spec)
     33
     34Summary: They control the behavior when a JavaScript null or undefined is passed to DOMString attributes/parameters.
    3335
    3436The possible usage is [TreatNullAs=NullString] or [TreatUndefinedAs=NullString].
    … …  
    4143
    4244[TreatNullAs=NullString] indicates that if a JavaScript null is passed to the attribute/parameter,
    43 then it is converted to a null string in WebKit, for which String::IsEmpty() and String::IsNull() will return true.
    44 Without [TreatNullAs=NullString], a JavaScript null is converted to a string "null" in WebKit.
     45then it is converted to a WebKit null string, for which String::IsEmpty() and String::IsNull() will return true.
     46Without [TreatNullAs=NullString], a JavaScript null is converted to a WebKit string "null".
    4547
    4648[TreatNullAs=NullString] corresponds to [TreatNullAs=EmptyString] in the Web IDL spec.
    … …  
    4850
    4951[TreatUndefinedAs=NullString] indicates that if a JavaScript undefined is passed to the attribute/parameter,
    50 then it is converted to a null string in WebKit, for which IsEmpty() and IsNull() will return true.
    51 Without [TreatUndefinedAs=NullString], a JavaScript undefined is converted to a string "undefined" in WebKit.
     52then it is converted to a WebKit null string, for which IsEmpty() and IsNull() will return true.
     53Without [TreatUndefinedAs=NullString], a JavaScript undefined is converted to a WebKit string "undefined".
    5254
    5355[TreatUndefinedAs=NullString] corresponds to [TreatUndefinedAs=EmptyString] in the Web IDL spec.
    … …  
    5759[TreatUndefinedAs=NullString] must be used with [TreatNullAs=NullString], i.e. [TreatNullAs=NullString, TreatUndefinedAs=NullString].
    5860
    59 === * [TreatReturnedNullStringAs](o,a) ===
     61=== * [TreatReturnedNullStringAs](m,a) ===
     62
     63Summary: It controls the behavior when a WebKit null string is returned.
    6064
    6165The possible usage is [TreatReturnedNullStringAs=Null], [TreatReturnedNullStringAs=Undefined] or [TreatReturnedNullStringAs=False].
    62 They can be specified on DOMString attributes or operations which return a DOMString value, like this:
     66They can be specified on DOMString attributes or methods which return a DOMString value, like this:
    6367
    6468{{{
    … …  
    6771}}}
    6872
    69 [TreatReturnedNullStringAs=Null] indicates that if the returned string is a null string in WebKit, the returned value is converted to a JavaScript null.
    70 
    71 [TreatReturnedNullStringAs=Undefined] indicates that if the returned string is a null string in WebKit, the returned value is converted to a JavaScript undefined.
    72 
    73 [TreatReturnedNullStringAs=False] indicates that if the returned string is a null string in WebKit, the returned value is converted to a JavaScript false.
    74 
    75 Without [TreatReturnedNullStringAs=...], if the returned string is a null string in WebKit, the returned value becomes a JavaScript empty string ''. Note that what should be specified depends on the spec of each attribute or operation.
     73[TreatReturnedNullStringAs=Null] indicates that if the returned string is a WebKit null string, the returned value is converted to a JavaScript null.
     74
     75[TreatReturnedNullStringAs=Undefined] indicates that if the returned string is a WebKit null string, the returned value is converted to a JavaScript undefined.
     76
     77[TreatReturnedNullStringAs=False] indicates that if the returned string is a WebKit null string, the returned value is converted to a JavaScript false.
     78
     79Without [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.
    7680
    7781=== * [Optional](p) ===
    7882
     83Summary: It allows method overloading for methods whose argument count are different with each other.
     84
     85The possible usage is [Optional], [Optional=DefaultIsUndefined] or [Optional=DefaultIsNullString].
     86[Optional] and [Optional=DefaultIsUndefined] can be specified on parameters.
     87[Optional=DefaultIsNullString] can be specified on DOMString parameters, like this:
     88
     89{{{
     90    interface HTMLFoo {
     91        void func1(in int a, in int b, in [Optional] int c, in [Optional] int d);
     92        void func2(in int a, in int b, in [Optional=DefaultIsUndefined] int c);
     93        void func3(in int a, in int b, in [Optional=DefaultIsUndefined] DOMString c, in [Optional=DefaultIsNullString] DOMString d);
     94    }
     95}}}
     96
     97The parameters marked with [Optional=...] are optional, and JavaScript can omit the parameters. Obviously, if parameter X is marked with [Optional=...], then all subsequent parameters of X must be marked with [Optional=...]. The difference between [Optional] and [Optional=DefaultIsUndefined] is whether your WebCore implementation has overloaded methods or not, as explained below.
     98
     99In case of func1(...), if JavaScript calls func1(100, 200), then HTMLFoo::func1(int a, int b) is called in WebCore.
     100If JavaScript calls func1(100, 200, 300), then HTMLFoo::func1(int a, int b, int c) is called in WebCore.
     101If 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 your WebCore implementation has overloaded methods, you can use [Optional].
     102
     103In case of func2(...), if JavaScript calls func2(100, 200), then it behaves as if JavaScript called func2(100, 200, undefined, undefined).
     104Consequently, HTMLFoo::func1(int a, int b, int c, int d) is called in WebCore.
     105100 is passed to a, 200 is passed to b, 0 is passed to c, and 0 is passed to d.
     106(A JavaScript undefined is converted to 0, following the value conversion rule in the Web IDL spec.)
     107In this way, WebCore needs to implement func2(int a, int b, int c, int d) only, and needs not to implement overloaded methods like func2(int a, int b) or func2(int a, int b, int c).
     108
     109The difference between [Optional=DefalutIsUndefined] and [Optional=DefaultIsNullString] appears only when the parameter type is DOMString.
     110While 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.
    79111
    80112
    81113=== * [Callback](i,p) ===
    82114
    83 === * [Custom](o,a), [JSCustom](o,a), [V8Custom](o,a), [CustomGetter](a), [JSCustomGetter](a), [V8CustomGetter](a), [CustomSetter](a), [JSCustomSetter](a), [V8CustomSetter](a) ===
    84 
    85 === * [CallWith](o,a) ===
    86 
    87 === * [CheckAccessToNode](o,a) ===
    88 
    89 === * [StrictTypeChecking](o,a) ===
    90 
    91 === * [ReturnNewObject](o,a) ===
    92 
    93 === * [ImplementedAs](o) ===
     115Summary: ???
     116
     117The possible usage is [Callback]. [Callback] can be specified on interfaces and parameters.
     118
     119FIXME: ADD EXPLANATIONS
     120
     121=== * [Custom](m,a), [JSCustom](m,a), [V8Custom](m,a), [CustomGetter](a), [JSCustomGetter](a), [V8CustomGetter](a), [CustomSetter](a), [JSCustomSetter](a), [V8CustomSetter](a) ===
     122
     123=== * [CallWith](m,a) ===
     124
     125=== * [CheckAccessToNode](m,a) ===
     126
     127=== * [StrictTypeChecking](m,a) ===
     128
     129=== * [ReturnNewObject](m,a) ===
     130
     131=== * [ImplementedAs](m) ===
    94132
    95133=== * [Reflect](a) ===
    … …  
    111149=== * [Supplemental](i) ===
    112150
    113  * [http://dev.w3.org/2006/webapi/WebIDL/#dfn-supplemental-interface The spec of [Supplemental\]]
     151 * [http://dev.w3.org/2006/webapi/WebIDL/#dfn-supplemental-interface The spec of [Supplemental]]
    114152
    115153 * [http://old.nabble.com/Things-missing-from-Web-IDL-for-HTML5-td24873773.html Easy explanation of [Supplemental\]]
    … …  
    155193=== * [CustomConstructor](i), [JSCustomConstructor](i), [V8CustomConstructor](i) ===
    156194
    157 === * [Conditional](i,o,a) ===
    158 
    159 === * [V8EnabledAtRuntime](i,o,a) ===
     195=== * [Conditional](i,m,a) ===
     196
     197=== * [V8EnabledAtRuntime](i,m,a) ===
    160198
    161199=== * [CustomToJSObject](i), [JSCustomToJSObject](i), [V8CustomToJSObject](i) ===
    162200
    163 === * [CheckDomainSecurity](i), [DoNotCheckDomainSecurity](o,a), [DoNotCheckDomainSecurityOnGetter](a), [DoNotCheckDomainSecurityOnSetter](a) ===
     201=== * [CheckDomainSecurity](i), [DoNotCheckDomainSecurity](m,a), [DoNotCheckDomainSecurityOnGetter](a), [DoNotCheckDomainSecurityOnSetter](a) ===
    164202
    165203=== * [IndexedGetter](i), [CustomIndexedGetter](i) ===
    … …  
    193231== IDL attributes used by ObjC, GObject and CPP bindings only ==
    194232
    195 === * [ObjCProtocol](i), [ObjCPolymorphic](i), [ObjCLegacyUnnamedParameters](o), [ObjCUseDefaultView](o), [ObjCImplementedAsUnsignedLongLong](a) ===
     233=== * [ObjCProtocol](i), [ObjCPolymorphic](i), [ObjCLegacyUnnamedParameters](m), [ObjCUseDefaultView](m), [ObjCImplementedAsUnsignedLongLong](a) ===
    196234
    197235Used by ObjC bindings only.