Changes between Version 31 and Version 32 of WebKitIDL


Ignore:
Timestamp:
Feb 15, 2012 9:39:22 PM (10 years ago)
Author:
haraken@chromium.org
Comment:

--

Legend:

Unmodified
Added
Removed
Modified
  • WebKitIDL

    v31 v32  
    131131    attribute [CustomGetter, JSCustomSetter] DOMString str;
    132132}}}
     133
     134We should minimize the number of custom bindings as less as possible.
     135Before using [Custom], you should doubly consider if you really need custom bindings.
     136You are recommended to modify code generators to avoid using [Custom].
    133137
    134138Before explaining the details, let us clarify the relationship of these IDL attributes.
     
    243247Refer to WebCore/bindings/v8/custom/V8XXXCustom.cpp for more details.
    244248
    245 We should minimize the number of custom bindings as less as possible. Before using [Custom], you should doubly consider if you really need custom bindings.
    246 
    247249Note: ObjC, GObject and CPP bindings do not support custom bindings.
    248250
     
    564566        CallWith=ScriptExecutionContext|ScriptState
    565567    ] XXX {
    566         ...;
    567568    }
    568569}}}
     
    658659=== * [NamedConstructor](i) ===
    659660
    660 === * [CustomConstructor](i), [JSCustomConstructor](i), [V8CustomConstructor](i) ===
     661 * [http://dev.w3.org/2006/webapi/WebIDL/#NamedConstructor The spec of NamedConstructor]
     662
     663Summary: If the interface name XXX and "new YYY()" name are different (i.e. XXX != YYY), you can use [NamedConstructor].
     664
     665Usage: The possible usage of [NamedConstructor] is [NamedConstructor=YYY].
     666[NamedConstructor] can be specified on interfaces:
     667{{{
     668    interface [
     669        NamedConstructor=Audio()
     670    ] HTMLAudioElement {
     671    }
     672}}}
     673
     674The semantics is the same as [Constructor], except that JavaScript can make a DOM object not by "new HTMLAudioElement(...)" but by "Audio()".
     675
     676Whether you should allow an interface to have a named constructor depends on the spec of the interface.
     677
     678=== * [CustomConstructor](i), [JSCustomConstructor](i), [V8CustomConstructor](i), [ConstructorParameters](i) ===
     679
     680Summary: They allow to write custom bindings for constructors.
     681
     682Usage: They can specified on interfaces.
     683Regarding [ConstructorParameters], the possible usage is [ConstructorParameters=X], where X is the maximum number of arguments of the constructor:
     684{{{
     685    interface [
     686        CustomConstructor,
     687        ConstractorParameters=4
     688    ] XXX {
     689    }
     690}}}
     691
     692We should minimize the number of custom bindings as less as possible.
     693Before using [CustomConstructor], you should doubly consider if you really need custom bindings.
     694You are recommended to modify code generators to avoid using [Custom].
     695
     696Before explaining the details, let us clarify the relationship of these IDL attributes.
     697
     698 * [JSCustomConstructor] on an interface indicates that you want to write JavaScriptCore custom bindings for the constructor.
     699 * [V8CustomConstructor] on an interface indicates that you want to write V8 custom bindings for the constructor.
     700 * [CustomConstructor] is equivalent to [JSCustomConstructor] and [V8CustomConstructor].
     701
     702For example, if you specify [Constructor, JSCustomConstructor],
     703then the constructor is generated only for V8 and you need to write JavaScriptCore custom bindings for the constructor.
     704
     705How to write custom bindings are different between JavaScriptCore and V8.
     706
     707 * JavaScriptCore
     708Consider the following example:
     709{{{
     710    interface [
     711        CustomConstructor,
     712        ConstructorParameters=2
     713    ] XXX {
     714    }
     715}}}
     716You need to prepare WebCore/bindings/js/JSXXXCustom.cpp and write custom bindings:
     717{{{
     718    EncodedJSValue JSC_HOST_CALL JSXXXConstructor::constructJSSharedWorker(ExecState* exec)
     719    {
     720        ...;
     721    }
     722}}}
     723Refer to WebCore/bindings/js/JSXXXCustom.cpp for more details.
     724
     725 * V8
     726Consider the following example:
     727{{{
     728    interface [
     729        CustomConstructor,
     730        ConstructorParameters=2
     731    ] XXX {
     732    }
     733}}}
     734You need to prepare WebCore/bindings/v8/custom/V8XXXConstructor.cpp and write custom bindings:
     735{{{
     736    v8::Handle<v8::Value> V8XXX::constructorCallback(const v8::Arguments& args)
     737    {
     738        ...;
     739    }
     740}}}
     741Refer to WebCore/bindings/v8/custom/V8XXXConstructor.cpp for more details.
     742
     743X of [ConstructorParameters=X] is the maximum number of arguments, including optional arguments.
     744For example, if the constructor signature is [Constructor(in int a, in int b, in [Optional] int c, in [Optional] int d)], then X is 4.
     745You do not need to specify [ConstructorParameters] if the interface does not have any of [JSCustomConstructor], [V8CustomConstructor] or [CustomConstructor].
    661746
    662747=== * [Conditional](i,m,a) ===
    663748
     749Summary: It inserts "#if ENABLE(SOME_FLAG) ... #endif" into the generated code.
     750
     751Usage: It can be specified on interfaces, methods and attributes:
     752{{{
     753    interface [
     754        Conditional=INDEXED_DATABASE
     755    ] XXX {
     756    }
     757}}}
     758{{{
     759    interface XXX {
     760        attribute [Conditional=INDEXED_DATABASE] DOMString str;
     761        [Conditional=INDEXED_DATABASE] void open();
     762    }
     763}}}
     764
     765[Conditional] is used to enable/disable the generated code based on the flag.
     766If the flag is enabled, the generated code is compiled. Otherwise, the generated code is not compiled.
     767Whether a flag is enabled or disabled is controlled by Tools/Scripts/build-webkit.
     768
     769If [Conditional] is specified on an interface, it means that [Conditional] is specified on all attributes and methods on the interface.
     770
    664771=== * [V8EnabledAtRuntime](i,m,a) ===
    665772
     773Summary: In Chromium/V8, we can enable/disable a flag at runtime.
     774
     775Usage: The possible usage is [V8EnabledAtRuntime] or [V8EnabledAtRuntime=X],
     776where X is an arbitrary string which you want to use for identifying the flag getter.
     777It can be specified on interfaces, methods and attributes:
     778{{{
     779    interface [
     780        V8EnabledAtRuntime
     781    ] XXX {
     782    }
     783}}}
     784{{{
     785    interface XXX {
     786        attribute [V8EnabledAtRuntime] DOMString str1;
     787        attribute [V8EnabledAtRuntime=foo] DOMString str2;
     788        [V8EnabledAtRuntime] void open1();
     789        [V8EnabledAtRuntime=foo] void open2();
     790    }
     791}}}
     792
     793In Chromium/V8, we can enable/disable flags in the about:flags page.
     794To make interfaces/methods/attributes controllable through about:flags, you can specify [V8EnabledAtRuntime].
     795
     796If [V8EnabledAtRuntime] is specified on an interface,
     797it means that [V8EnabledAtRuntime] is specified on all attributes and methods on the interface....;
     798
     799If you add [V8EnabledAtRuntime], you need to write "flag-binding" code
     800in WebCore/bindings/generic/RuntimeEnabledFeatures.h, WebCore/bindings/generic/RuntimeEnabledFeatures.cpp
     801and WebKit/chromium/src/WebRuntimeFeatures.cpp.
     802
     803The method name of a flag getter in WebCore/bindings/generic/RuntimeEnabledFeatures.h
     804is determined by the name of interfaces/methods/attributes.
     805You can change the method name by using [V8EnabledAtRuntime=X].
     806Refer to WebCore/bindings/generic/RuntimeEnabledFeatures.h, WebCore/bindings/generic/RuntimeEnabledFeatures.cpp
     807and WebKit/chromium/src/WebRuntimeFeatures.cpp for more details.
     808
    666809=== * [CustomToJSObject](i), [JSCustomToJSObject](i), [V8CustomToJSObject](i) ===
    667810
     811Summary: It allows us to write custom
     812
     813Usage:
     814
    668815=== * [CheckDomainSecurity](i), [DoNotCheckDomainSecurity](m,a), [DoNotCheckDomainSecurityOnGetter](a), [DoNotCheckDomainSecurityOnSetter](a) ===
    669816
    670817=== * [IndexedGetter](i), [CustomIndexedGetter](i) ===
    671818
    672 === * [NamedGetter](i), [NamedCustomGetter](i), [NamedCustomSetter](i) ===
     819=== * [NamedGetter](i), [CustomNamedGetter](i), [CustomNamedSetter](i) ===
    673820
    674821=== * [EventTarget](i) ===
     
    682829=== * [IsWorkerContext](i) ===
    683830
     831Summary: It indicates that the interface is a WorkerContext-related interface.
     832
     833Usage: It can be specified on WorkerContext-related interfaces:
     834{{{
     835    interface [
     836        IsWorkerContext
     837    ] SharedWorkerContext {
     838        ...;
     839    }
     840}}}
     841
     842
    684843=== * [CustomCall](i) ===
    685844
     
    716875Might be deprecated. Discussion is on-going.
    717876
    718 === * [CustomGetOwnPropertySlot], [ConstructorParameters], [ReplaceableConstructor], [ExtendsDOMGlobalObject], [IsIndex], [V8DoNotCheckSignature], [NumericIndexedGetter] ===
     877=== * [CustomGetOwnPropertySlot], [ReplaceableConstructor], [ExtendsDOMGlobalObject], [IsIndex], [V8DoNotCheckSignature], [NumericIndexedGetter] ===
    719878
    720879Will be deprecated. Discussion is on-going.