9 | | = How the IDL bindings work = |
10 | | |
11 | | By reading this document, you can know how IDL attributes work. |
| 9 | Here is an example of IDL files: |
| 10 | {{{ |
| 11 | module 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 | |
| 25 | Let 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 | |
| 34 | Note: These terminologies are not aligned with the Web IDL spec. |
| 35 | A 'method' is called an 'operation' in the Web IDL spec. |
| 36 | There is no distinction between an 'attribute' and a 'parameter' (a 'parameter' is treated as an 'attribute'). |
| 37 | |
| 38 | The 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. |
| 44 | Where each IDL attribute can be specified on is defined per each IDL attribute. |
| 45 | This is also explained in the subsequent section. |
| 46 | |
| 47 | The template of an IDL file is as follows: |
| 48 | {{{ |
| 49 | module 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 | |
| 62 | If there is no IDL attributes on interfaces, the IDL file just looks like this: |
| 63 | {{{ |
| 64 | module 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 | |
| 75 | By reading this document you can learn how IDL attributes work. |
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 | |
| 92 | There 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 | |
| 102 | For example, [JSNoStaticTables], [CustomGetter], [V8CustomGetter], etc. |