| 791 | | == [Supplemental](i) == #Supplemental |
| 792 | | |
| 793 | | * [http://dev.w3.org/2006/webapi/WebIDL/#dfn-supplemental-interface The spec of Supplemental] |
| 794 | | |
| 795 | | * [http://old.nabble.com/Things-missing-from-Web-IDL-for-HTML5-td24873773.html Easy explanation of Supplemental] |
| 796 | | |
| 797 | | Summary: [Supplemental] helps WebKit modularization. |
| 798 | | [Supplemental] makes it possible to add XXX's APIs (e.g. XXX=WebAudio, WebSocket, Blob, GamePad, ...etc) without modifying code outside of WebCore/Modules/XXX/. |
| 799 | | This helps make XXX a "self-contained module". |
| 800 | | |
| 801 | | Usage: The possible usage is |
| 802 | | {{{ |
| 803 | | interface [ |
| 804 | | Supplemental=YYY |
| 805 | | ] XXX { |
| 806 | | }; |
| 807 | | }}} |
| 808 | | where XXX implements YYY. |
| 809 | | [Supplemental] can be specified on interfaces. |
| 810 | | |
| 811 | | Without [Supplemental], if you want to add XXX's attributes or methods to DOMWindow, |
| 812 | | |
| 813 | | * you need to modify WebCore/page/DOMWindow.idl to add the XXX's attributes or methods |
| 814 | | |
| 815 | | * you need to modify WebCore/page/DOMWindow.{h,cpp} to add the WebCore implementation of the attribute getters and setters or the method callbacks. |
| 816 | | |
| 817 | | On the other hand, in the modularized world with [Supplemental], you just need to modify the code under WebCore/Modules/XXX/: |
| 818 | | |
| 819 | | * WebCore/Modules/XXX/DOMWindowXXX.idl |
| 820 | | |
| 821 | | {{{ |
| 822 | | interface [ |
| 823 | | Conditional=XXX, |
| 824 | | Supplemental=DOMWindow // The attributes and methods of this interface are exposed as those of DOMWindow. |
| 825 | | ] DOMWindowXXX { |
| 826 | | attribute int foo; |
| 827 | | void bar(); |
| 828 | | }; |
| 829 | | }}} |
| 830 | | |
| 831 | | * WebCore/Modules/XXX/DOMWindowXXX.h |
| 832 | | |
| 833 | | {{{ |
| 834 | | DOMWindowXXX::foo(...) { ... } // The WebCore implementation of the foo attribute getter. |
| 835 | | DOMWindowXXX::setFoo(...) { ... } // The WebCore implementation of the foo attribute setter. |
| 836 | | DOMWindowXXX::bar(...) { ... } // The WebCore implementation of the bar() method callback. |
| 837 | | }}} |
| 838 | | |
| 839 | | As shown above, [Supplemental=DOMWindow] indicates that all the attributes and methods of DOMWindowXXX should be exposed on DOMWindow, |
| 840 | | but should be implemented in DOMWindowXXX. |
| 841 | | In this way, you can implement the attributes and methods without modifying code of DOMWindow.{h,cpp,idl}. |
| 842 | | |
| 843 | | If you want to add APIs whose implementations are likely to be independent from WebCore, |
| 844 | | it is strongly recommended to put the APIs and .h/.cpp files into WebCore/Modules/XXX/ using [Supplemental]. |
| 845 | | On the other hand, if the implementations need to touch WebCore much, |
| 846 | | the APIs might not be good candidates for [Supplemental]. |
| 847 | | |
