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 | |
| 557 | Summary: It indicates that the interface should have constructor "new XXX()". |
| 558 | |
| 559 | Usage: [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 |
| 571 | and the constructor signature is (in float x, in float y, in DOMString str). |
| 572 | Specifically, JavaScript can generate a DOM object of XXX by the following code: |
| 573 | {{{ |
| 574 | var x = new XXX(1.0, 2.0, "hello"); |
| 575 | }}} |
| 576 | Then XXX::create(float x, float y, String str) is called in WebCore. |
| 577 | Specifically, 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 | |
| 587 | If the WebCore method can throw Exception, you can use [ConstructorRaisesException]. |
| 588 | With [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 | |
| 600 | If the WebCore method needs additional information like ScriptExecutionContext and ScriptState, |
| 601 | you can specify it by [CallWith=ScriptExecutionContext|ScriptState]. |
| 602 | Then 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 | }}} |
| 609 | You can retrieve document or frame from ScriptExecutionContext. |
| 610 | Please see another [CallWith] section for more details. |
| 611 | |
| 612 | Note that [CallWith=...] arguments are added at the head of the WebCore method arguments, |
| 613 | and the ExceptionCode argument is added at the tail of the WebCore method arguments. |
| 614 | |
| 615 | Whether you should allow an interface to have constructor depends on the spec of the interface. |
| 619 | Summary: They are used for Event constructors. |
| 620 | |
| 621 | Usage: 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 | |
| 633 | Since constructors for Event interfaces require special binding, |
| 634 | you need to use [ConstructorTemplate=Event] instead of normal [Constructor]. |
| 635 | |
| 636 | If you specify [ConstructorTemplate=Event] on FooEvent, |
| 637 | JavaScript can make a DOM object of FooEvent in the following code: |
| 638 | {{{ |
| 639 | var e = new FooEvent("type", { bubbles: true, cancelable: true }); |
| 640 | }}} |
| 641 | Then FooEvent::create(...) is called in WebCore. |
| 642 | Specifically, 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 |
| 651 | which needs to be initialized by the constructor. |
| 652 | Which attributes needs initialization is defined in the spec. |
| 653 | For example, look at [http://dvcs.w3.org/hg/domcore/raw-file/tip/Overview.html#event the spec of Event]. |
| 654 | EventInit dictionary has bubbles and cancelable, and thus bubbles and cancelable are the only attributes |
| 655 | that needs to be initialized by the Event constructor. |
| 656 | In other words, in case of Event, you should specify [InitializedByEventConstructor] on bubbles and cancelable. |
| 657 | |