| 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. |
