Changes between Version 36 and Version 37 of WebKitIDL


Ignore:
Timestamp:
Feb 17, 2012 2:15:22 AM (10 years ago)
Author:
haraken@chromium.org
Comment:

--

Legend:

Unmodified
Added
Removed
Modified
  • WebKitIDL

    v36 v37  
    77= Basics of the IDL =
    88
    9 = How the IDL bindings work =
    10 
    11 By reading this document, you can know how IDL attributes work.
     9Here is an example of IDL files:
     10{{{
     11module core {
     12    interface [
     13        JSCustomHeader,
     14        CustomToObject
     15    ] Node {
     16        const unsigned short ELEMENT_NODE = 1;
     17        attribute Node parentNode;
     18        attribute [TreatReturnedNullStringAs=Null] DOMString nodeName;
     19        [Custom] Node appendChild(in [CustomReturn] Node newChild);
     20        void addEventListener(in DOMString type, in EventListener listener, in [Optional] boolean useCapture);
     21    };
     22}
     23}}}
     24
     25Let us introduce some terminologies:
     26
     27 * This is the IDL file of the Node ''''interface''''.
     28 * ELEMENT_NODE is a ''''constant'''' of the Node interface.
     29 * parentNode and nodeName are ''''attribute''''s of the Node interface.
     30 * appendChild(...) and addEventListener(...) are ''''method''''s of the Node interface.
     31 * type, listener and useCapture are ''''parameter''''s of the Node interface.
     32 * [JSCustomHeader], [CustomToObject], [TreatReturnedNullStringAs=Null], [Custom], [CustomReturn] and [Optional] are ''''IDL attribute''''s.
     33
     34Note: These terminologies are not aligned with the Web IDL spec.
     35A 'method' is called an 'operation' in the Web IDL spec.
     36There is no distinction between an 'attribute' and a 'parameter' (a 'parameter' is treated as an 'attribute').
     37
     38The key points are as follows:
     39
     40 * An IDL file controls how the bindings code between JavaScript engine (or ObjC, GObject, CPP) and the WebKit implementation is generated.
     41 * IDL attributes enable us to control the bindings code more in detail.
     42 * There are 90~ IDL attributes and their roles are explained in the subsequent section.
     43 * IDL attributes can be specified on interfaces, methods, attributes and parameters.
     44Where each IDL attribute can be specified on is defined per each IDL attribute.
     45This is also explained in the subsequent section.
     46
     47The template of an IDL file is as follows:
     48{{{
     49module MODULE_NAME {
     50    interface [
     51        IDL_ATTRIBUTE_ON_INTERFACE1,
     52        IDL_ATTRIBUTE_ON_INTERFACE2,
     53        ...;
     54    ] INTERFACE_NAME {
     55        const unsigned long value = 12345;
     56        attribute [IDL_ATTRIBUTE_ON_ATTRIBUTE1, IDL_ATTRIBUTE_ON_ATTRIBUTE2, ...] Node node;
     57        [IDL_ATTRIBUTE_ON_METHOD1, IDL_ATTRIBUTE_ON_METHOD2, ...] void func(in [IDL_ATTRIBUTE_ON_PARAMETER1, IDL_ATTRIBUTE_ON_PARAMETER2, ...] int param, ...);
     58    };
     59}
     60}}}
     61
     62If there is no IDL attributes on interfaces, the IDL file just looks like this:
     63{{{
     64module MODULE_NAME {
     65    interface INTERFACE_NAME {
     66        const unsigned long value = 12345;
     67        attribute [IDL_ATTRIBUTE_ON_ATTRIBUTE1, IDL_ATTRIBUTE_ON_ATTRIBUTE2, ...] Node node;
     68        [IDL_ATTRIBUTE_ON_METHOD1, IDL_ATTRIBUTE_ON_METHOD2, ...] void func(in [IDL_ATTRIBUTE_ON_PARAMETER1, IDL_ATTRIBUTE_ON_PARAMETER2, ...] int param, ...);
     69    };
     70}
     71}}}
     72
     73= Where is the bindings code? =
     74
     75By reading this document you can learn how IDL attributes work.
    1276However, the best practice to understand IDL attributes is to use some IDL attributes and watch the bindings code actually generated.
    1377
     
    2084 * JavaScriptCore: WebKitBuild/Release/DerivedSources/WebCore/JSXXX.h, WebKitBuild/Release/DerivedSources/WebCore/JSXXX.cpp
    2185 * V8: out/Release/obj/gen/webkit/bindings/V8XXX.h, out/Release/obj/gen/webcore/bindings/V8XXX.cpp
    22  * ObjC: WebKitBuild/Release/DerivedSources/WebCore/DOMXXX.h, WebKitBuild/Release/DerivedSources/WebCore/DOMXXX.cpp
     86 * ObjC: WebKitBuild/Release/DerivedSources/WebCore/DOMXXX.h, WebKitBuild/Release/DerivedSources/WebCore/DOMXXX.mm
    2387 * GObject: WebKitBuild/Release/DerivedSources/webkit/WebKitDOMXXX.h, WebKitBuild/Release/DerivedSources/webkit/WebKitDOMXXX.cpp
    24  * CPP:
     88 * CPP: WebKitBuild/Release/DerivedSources/WebCore/WebDOMXXX.h, WebKitBuild/Release/DerivedSources/WebCore/WebDOMXXX.cpp
     89
     90= Basic naming rules of IDL attribute =
     91
     92There are a few rules of IDL attribute naming:
     93
     94 * A name should be aligned with the Web IDL spec as much as possible.
     95 * JavaScriptCore specific IDL attributes are prefixed by "JS".
     96 * V8 specific IDL attributes are prefixed by "V8".
     97 * ObjC specific IDL attributes are prefixed by "ObjC".
     98 * GObject specific IDL attributes are prefixed by "GObject".
     99 * CPP specific IDL attributes are prefixed by "CPP".
     100 * IDL attributes for custom bindings are prefixed by "Custom".
     101
     102For example, [JSNoStaticTables], [CustomGetter], [V8CustomGetter], etc.
    25103
    26104= IDL attributes =
    27 
    28 == Basic naming rules ==
    29 
    30 == IDL attributes around methods, attributes and parameters ==
    31105
    32106In 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.