Changes between Version 30 and Version 31 of WebKitIDL


Ignore:
Timestamp:
Feb 15, 2012 6:23:10 PM (12 years ago)
Author:
haraken@chromium.org
Comment:

--

Legend:

Unmodified
Added
Removed
Modified
  • WebKitIDL

    v30 v31  
    132132}}}
    133133
    134 Before explaining the details, let us clarify the relationship of these IDLs.
     134Before explaining the details, let us clarify the relationship of these IDL attributes.
    135135
    136136 * [JSCustom] on a method indicates that you want to write JavaScriptCore custom bindings for the method.
     
    247247Note: ObjC, GObject and CPP bindings do not support custom bindings.
    248248
    249 === * [CallWith](m,a) ===
     249=== * [CallWith](i,m,a) ===
    250250
    251251Summary: It calls a WebCore method with additional information.
     
    263263    }
    264264}}}
     265[CallWith] can be specified on interfaces but it has a different meaning. Refer to the [Constructor] section for [CallWith] on interfaces.
    265266
    266267In case of func1(...), HTMLFoo::func1(ScriptExecutionContext* context, int a, int b) is called.
     
    495496=== * [JSWindowEventListener](a) ===
    496497
    497 Summary:
    498 
    499 Usage:
    500 
    501 
     498Summary: ADD SUMMARY
     499
     500Usage: [JSWindowEventListener] can be specified on EventListener attributes.
     501{{{
     502    attribute [JSWindowEventListener] EventListener onload;
     503}}}
     504
     505ADD EXPLANATIONS
    502506
    503507== IDL attributes around interfaces ==
     
    509513 * [http://old.nabble.com/Things-missing-from-Web-IDL-for-HTML5-td24873773.html Easy explanation of Supplemental]
    510514
    511 Summary: [Supplemental] helps WebKit modularization. The [Supplemental] IDL makes it possible to add XXX's APIs (e.g. XXX=WebAudio, WebSocket, Blob, GamePad, ...etc) without modifying code outside of WebCore/Modules/XXX/. This helps make XXX a "self-contained module".
     515Summary: [Supplemental] helps WebKit modularization. [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/. This helps make XXX a "self-contained module".
    512516
    513517Usage: The possible usage is
     
    519523Here is an example. Without [Supplemental], if we want to add XXX's attributes or methods to DOMWindow,
    520524
    521  * we need to modify WebCore/page/DOMWindow.idl to add the IDLs of the XXX's attributes or methods
     525 * we need to modify WebCore/page/DOMWindow.idl to add the XXX's attributes or methods
    522526
    523527 * we need to modify WebCore/page/DOMWindow.{h,cpp} to add the C++ implementation of the attribute getters and setters or the method callbacks.
     
    547551If you want to add APIs whose implementations are likely to be independent from WebCore, it is strongly recommended to put the APIs and .h/.cpp files into WebCore/Modules/XXX/ using [Supplemental].
    548552
    549 === * [Constructor](i), [ConstructorCallWith](i), [ConstructorRaisesException](i) ===
     553=== * [Constructor](i), [CallWith](i,m,a), [ConstructorRaisesException](i) ===
     554
     555 * [http://dev.w3.org/2006/webapi/WebIDL/#Constructor The spec of Constructor]
     556
     557Summary: It indicates that the interface should have constructor "new XXX()".
     558
     559Usage: [Constructor], [CallWith] and [ConstructorRaisesException] can be specified on interfaces:
     560{{{
     561    interface [
     562        Constructor(in float x, in float y, in DOMString str),
     563        ConstructorRaisesException,
     564        CallWith=ScriptExecutionContext|ScriptState
     565    ] XXX {
     566        ...;
     567    }
     568}}}
     569
     570[Constructor(in float x, in float y, in DOMString str)] means that the interface has constructor
     571and the constructor signature is (in float x, in float y, in DOMString str).
     572Specifically, JavaScript can generate a DOM object of XXX by the following code:
     573{{{
     574    var x = new XXX(1.0, 2.0, "hello");
     575}}}
     576Then XXX::create(float x, float y, String str) is called in WebCore.
     577Specifically, WebCore needs to implement the following method:
     578{{{
     579    PassRefPtr<XXX> XXX::create(float x, float y, String str)
     580    {
     581        ...;
     582    }
     583}}}
     584
     585[Constructor()] is equivalent to [Constructor].
     586
     587If the WebCore method can throw Exception, you can use [ConstructorRaisesException].
     588With [ConstructorRaisesException], an ExceptionCode argument is added to the tail argument of XXX::create(...).
     589{{{
     590    PassRefPtr<XXX> XXX::create(float x, float y, String str, ExceptionCode& ec)
     591    {
     592        ...;
     593        if (...) {
     594            ec = TYPE_MATCH_ERR;
     595            return 0;
     596        }
     597    }
     598}}}
     599
     600If the WebCore method needs additional information like ScriptExecutionContext and ScriptState,
     601you can specify it by [CallWith=ScriptExecutionContext|ScriptState].
     602Then the WebCore method can have the following signature:
     603{{{
     604    PassRefPtr<XXX> XXX::create(ScriptExecutionContext* context, ScriptState* state, float x, float y, String str)
     605    {
     606        ...;
     607    }
     608}}}
     609You can retrieve document or frame from ScriptExecutionContext.
     610Please see another [CallWith] section for more details.
     611
     612Note that [CallWith=...] arguments are added at the head of the WebCore method arguments,
     613and the ExceptionCode argument is added at the tail of the WebCore method arguments.
     614
     615Whether you should allow an interface to have constructor depends on the spec of the interface.
    550616
    551617=== * [ConstructorTemplate](i), [InitializedByEventConstructor](a) ===
    552618
     619Summary: They are used for Event constructors.
     620
     621Usage: The possible usage is [ConstructorTemplate=Event].
     622[ConstructorTemplate=Event] can be specified on Event interfaces.
     623[InitializedByEventConstructor] can be specified on attributes in the Event interfaces:
     624{{{
     625    interface [
     626        ConstructorTemplate=Event
     627    ] FooEvent {
     628        attribute DOMString str1;
     629        attribute [InitializedByEventConstructor] DOMString str2;
     630    }
     631}}}
     632
     633Since constructors for Event interfaces require special binding,
     634you need to use [ConstructorTemplate=Event] instead of normal [Constructor].
     635
     636If you specify [ConstructorTemplate=Event] on FooEvent,
     637JavaScript can make a DOM object of FooEvent in the following code:
     638{{{
     639    var e = new FooEvent("type", { bubbles: true, cancelable: true });
     640}}}
     641Then FooEvent::create(...) is called in WebCore.
     642Specifically, WebCore needs to implement the following method:
     643{{{
     644    PassRefPtr<FooEvent> FooEvent::create(const AtomicString& type, const ProgressEventInit& initializer)
     645    {
     646        ...;
     647    }
     648}}}
     649
     650[InitializedByEventConstructor] should be specified on all the attributes
     651which needs to be initialized by the constructor.
     652Which attributes needs initialization is defined in the spec.
     653For example, look at [http://dvcs.w3.org/hg/domcore/raw-file/tip/Overview.html#event the spec of Event].
     654EventInit dictionary has bubbles and cancelable, and thus bubbles and cancelable are the only attributes
     655that needs to be initialized by the Event constructor.
     656In other words, in case of Event, you should specify [InitializedByEventConstructor] on bubbles and cancelable.
     657
    553658=== * [NamedConstructor](i) ===
    554659