OLD | NEW |
1 // Copyright (c) 2013, the Dart project authors. Please see the AUTHORS file | 1 // Copyright (c) 2013, the Dart project authors. Please see the AUTHORS file |
2 // for details. All rights reserved. Use of this source code is governed by a | 2 // for details. All rights reserved. Use of this source code is governed by a |
3 // BSD-style license that can be found in the LICENSE file. | 3 // BSD-style license that can be found in the LICENSE file. |
4 | 4 |
5 /** | 5 /** |
6 * Support for interoperating with JavaScript. | 6 * Support for interoperating with JavaScript. |
7 * | 7 * |
8 * This library provides access to JavaScript objects from Dart, allowing | 8 * This library provides access to JavaScript objects from Dart, allowing |
9 * Dart code to get and set properties, and call methods of JavaScript objects | 9 * Dart code to get and set properties, and call methods of JavaScript objects |
10 * and invoke JavaScript functions. The library takes care of converting | 10 * and invoke JavaScript functions. The library takes care of converting |
11 * between Dart and JavaScript objects where possible, or providing proxies if | 11 * between Dart and JavaScript objects where possible, or providing proxies if |
12 * conversion isn't possible. | 12 * conversion isn't possible. |
13 * | 13 * |
14 * This library does not yet make Dart objects usable from JavaScript, their | 14 * This library does not yet make Dart objects usable from JavaScript, their |
15 * methods and proeprties are not accessible, though it does allow Dart | 15 * methods and proeprties are not accessible, though it does allow Dart |
16 * functions to be passed into and called from JavaScript. | 16 * functions to be passed into and called from JavaScript. |
17 * | 17 * |
18 * [JsObject] is the core type and represents a proxy of a JavaScript object. | 18 * [JsObject] is the core type and represents a proxy of a JavaScript object. |
19 * JsObject gives access to the underlying JavaScript objects properties and | 19 * JsObject gives access to the underlying JavaScript objects properties and |
20 * methods. `JsObject`s can be acquired by calls to JavaScript, or they can be | 20 * methods. `JsObject`s can be acquired by calls to JavaScript, or they can be |
21 * created from proxies to JavaScript constructors. | 21 * created from proxies to JavaScript constructors. |
22 * | 22 * |
23 * The top-level getter [context] provides a [JsObject] that represents the | 23 * The top-level getter [context] provides a [JsObject] that represents the |
24 * global object in JavaScript, usually `window`. | 24 * global object in JavaScript, usually `window`. |
25 * | 25 * |
26 * The following example shows an alert dialog via a JavaScript call to the | 26 * The following example shows an alert dialog via a JavaScript call to the |
27 * global function `alert()`: | 27 * global function `alert()`: |
28 * | 28 * |
29 * import 'dart:js'; | 29 * import 'dart:js'; |
30 * | 30 * |
31 * main() => context.callMethod('alert', ['Hello from Dart!']); | 31 * main() => context.callMethod('alert', ['Hello from Dart!']); |
32 * | 32 * |
33 * This example shows how to create a [JsObject] from a JavaScript constructor | 33 * This example shows how to create a [JsObject] from a JavaScript constructor |
34 * and access its properties: | 34 * and access its properties: |
35 * | 35 * |
36 * import 'dart:js'; | 36 * import 'dart:js'; |
37 * | 37 * |
38 * main() { | 38 * main() { |
39 * var object = new JsObject(context['Object']); | 39 * var object = new JsObject(context['Object']); |
40 * object['greeting'] = 'Hello'; | 40 * object['greeting'] = 'Hello'; |
41 * object['greet'] = (name) => "${object['greeting']} $name"; | 41 * object['greet'] = (name) => "${object['greeting']} $name"; |
42 * var message = object.callMethod('greet', ['JavaScript']); | 42 * var message = object.callMethod('greet', ['JavaScript']); |
43 * context['console'].callMethod('log', [message]); | 43 * context['console'].callMethod('log', [message]); |
44 * } | 44 * } |
45 * | 45 * |
46 * ## Proxying and automatic conversion | 46 * ## Proxying and automatic conversion |
47 * | 47 * |
48 * When setting properties on a JsObject or passing arguments to a Javascript | 48 * When setting properties on a JsObject or passing arguments to a Javascript |
49 * method or function, Dart objects are automatically converted or proxied to | 49 * method or function, Dart objects are automatically converted or proxied to |
50 * JavaScript objects. When accessing JavaScript properties, or when a Dart | 50 * JavaScript objects. When accessing JavaScript properties, or when a Dart |
51 * closure is invoked from JavaScript, the JavaScript objects are also | 51 * closure is invoked from JavaScript, the JavaScript objects are also |
52 * converted to Dart. | 52 * converted to Dart. |
53 * | 53 * |
54 * Functions and closures are proxied in such a way that they are callable. A | 54 * Functions and closures are proxied in such a way that they are callable. A |
55 * Dart closure assigned to a JavaScript property is proxied by a function in | 55 * Dart closure assigned to a JavaScript property is proxied by a function in |
56 * JavaScript. A JavaScript function accessed from Dart is proxied by a | 56 * JavaScript. A JavaScript function accessed from Dart is proxied by a |
57 * [JsFunction], which has a [apply] method to invoke it. | 57 * [JsFunction], which has a [apply] method to invoke it. |
(...skipping 15 matching lines...) Expand all Loading... |
73 * ## Converting collections with JsObject.jsify() | 73 * ## Converting collections with JsObject.jsify() |
74 * | 74 * |
75 * To create a JavaScript collection from a Dart collection use the | 75 * To create a JavaScript collection from a Dart collection use the |
76 * [JsObject.jsify] constructor, which converts Dart [Map]s and [Iterable]s | 76 * [JsObject.jsify] constructor, which converts Dart [Map]s and [Iterable]s |
77 * into JavaScript Objects and Arrays. | 77 * into JavaScript Objects and Arrays. |
78 * | 78 * |
79 * The following expression creats a new JavaScript object with the properties | 79 * The following expression creats a new JavaScript object with the properties |
80 * `a` and `b` defined: | 80 * `a` and `b` defined: |
81 * | 81 * |
82 * var jsMap = new JsObject.jsify({'a': 1, 'b': 2}); | 82 * var jsMap = new JsObject.jsify({'a': 1, 'b': 2}); |
83 * | 83 * |
84 * This expression creates a JavaScript array: | 84 * This expression creates a JavaScript array: |
85 * | 85 * |
86 * var jsArray = new JsObject.jsify([1, 2, 3]); | 86 * var jsArray = new JsObject.jsify([1, 2, 3]); |
87 */ | 87 */ |
88 library dart.js; | 88 library dart.js; |
89 | 89 |
90 import 'dart:collection' show ListMixin; | 90 import 'dart:collection' show ListMixin; |
91 import 'dart:nativewrappers'; | 91 import 'dart:nativewrappers'; |
92 import 'dart:math' as math; | 92 import 'dart:math' as math; |
93 import 'dart:mirrors' as mirrors; | 93 import 'dart:mirrors' as mirrors; |
(...skipping 391 matching lines...) Expand 10 before | Expand all | Expand 10 after Loading... |
485 * The properties of the JavaScript object are accessible via the `[]` and | 485 * The properties of the JavaScript object are accessible via the `[]` and |
486 * `[]=` operators. Methods are callable via [callMethod]. | 486 * `[]=` operators. Methods are callable via [callMethod]. |
487 */ | 487 */ |
488 class JsObject extends NativeFieldWrapperClass2 { | 488 class JsObject extends NativeFieldWrapperClass2 { |
489 JsObject.internal(); | 489 JsObject.internal(); |
490 | 490 |
491 /** | 491 /** |
492 * Constructs a new JavaScript object from [constructor] and returns a proxy | 492 * Constructs a new JavaScript object from [constructor] and returns a proxy |
493 * to it. | 493 * to it. |
494 */ | 494 */ |
495 factory JsObject(JsFunction constructor, [List arguments]) => | 495 factory JsObject(JsFunction constructor, [List arguments]) { |
496 _create(constructor, arguments); | 496 try { |
| 497 return _create(constructor, arguments); |
| 498 } catch (e) { |
| 499 // Re-throw any errors (returned as a string) as a DomException. |
| 500 throw new html.DomException.jsInterop(e); |
| 501 } |
| 502 } |
497 | 503 |
498 static JsObject _create( | 504 static JsObject _create( |
499 JsFunction constructor, arguments) native "JsObject_constructorCallback"; | 505 JsFunction constructor, arguments) native "JsObject_constructorCallback"; |
500 | 506 |
501 _buildArgs(Invocation invocation) { | 507 _buildArgs(Invocation invocation) { |
502 if (invocation.namedArguments.isEmpty) { | 508 if (invocation.namedArguments.isEmpty) { |
503 return invocation.positionalArguments; | 509 return invocation.positionalArguments; |
504 } else { | 510 } else { |
505 var varArgs = new Map<String, Object>(); | 511 var varArgs = new Map<String, Object>(); |
506 invocation.namedArguments.forEach((symbol, val) { | 512 invocation.namedArguments.forEach((symbol, val) { |
507 varArgs[mirrors.MirrorSystem.getName(symbol)] = val; | 513 varArgs[mirrors.MirrorSystem.getName(symbol)] = val; |
508 }); | 514 }); |
509 return invocation.positionalArguments.toList() | 515 return invocation.positionalArguments.toList() |
510 ..add(new JsObject.jsify(varArgs)); | 516 ..add(new JsObject.jsify(varArgs)); |
511 } | 517 } |
512 } | 518 } |
513 | 519 |
514 /** | 520 /** |
515 * Constructs a [JsObject] that proxies a native Dart object; _for expert use | 521 * Constructs a [JsObject] that proxies a native Dart object; _for expert use |
516 * only_. | 522 * only_. |
517 * | 523 * |
518 * Use this constructor only if you wish to get access to JavaScript | 524 * Use this constructor only if you wish to get access to JavaScript |
519 * properties attached to a browser host object, such as a Node or Blob, that | 525 * properties attached to a browser host object, such as a Node or Blob, that |
520 * is normally automatically converted into a native Dart object. | 526 * is normally automatically converted into a native Dart object. |
521 * | 527 * |
522 * An exception will be thrown if [object] either is `null` or has the type | 528 * An exception will be thrown if [object] either is `null` or has the type |
523 * `bool`, `num`, or `String`. | 529 * `bool`, `num`, or `String`. |
524 */ | 530 */ |
525 factory JsObject.fromBrowserObject(object) { | 531 factory JsObject.fromBrowserObject(object) { |
526 if (object is num || object is String || object is bool || object == null) { | 532 if (object is num || object is String || object is bool || object == null) { |
527 throw new ArgumentError("object cannot be a num, string, bool, or null"); | 533 throw new ArgumentError("object cannot be a num, string, bool, or null"); |
528 } | 534 } |
529 return _fromBrowserObject(object); | 535 return _fromBrowserObject(object); |
530 } | 536 } |
531 | 537 |
(...skipping 29 matching lines...) Expand all Loading... |
561 /** | 567 /** |
562 * Sets the value associated with [property] on the proxied JavaScript | 568 * Sets the value associated with [property] on the proxied JavaScript |
563 * object. | 569 * object. |
564 * | 570 * |
565 * The type of [property] must be either [String] or [num]. | 571 * The type of [property] must be either [String] or [num]. |
566 */ | 572 */ |
567 operator []=(property, value) { | 573 operator []=(property, value) { |
568 try { | 574 try { |
569 _operator_setter(property, value); | 575 _operator_setter(property, value); |
570 } catch (e) { | 576 } catch (e) { |
571 // Re-throw any errors (returned as a string) as a DomExcetion. | 577 // Re-throw any errors (returned as a string) as a DomException. |
572 throw new html.DomException.jsInterop(e); | 578 throw new html.DomException.jsInterop(e); |
573 } | 579 } |
574 } | 580 } |
575 _operator_setter(property, value) native "JsObject_[]="; | 581 _operator_setter(property, value) native "JsObject_[]="; |
576 | 582 |
577 int get hashCode native "JsObject_hashCode"; | 583 int get hashCode native "JsObject_hashCode"; |
578 | 584 |
579 operator ==(other) { | 585 operator ==(other) { |
580 var is_JsObject = other is JsObject; | 586 var is_JsObject = other is JsObject; |
581 if (!is_JsObject) { | 587 if (!is_JsObject) { |
(...skipping 268 matching lines...) Expand 10 before | Expand all | Expand 10 after Loading... |
850 | 856 |
851 /** | 857 /** |
852 * Returns a method that can be called with an arbitrary number (for n less | 858 * Returns a method that can be called with an arbitrary number (for n less |
853 * than 11) of arguments without violating Dart type checks. | 859 * than 11) of arguments without violating Dart type checks. |
854 */ | 860 */ |
855 Function _wrapAsDebuggerVarArgsFunction(JsFunction jsFunction) => | 861 Function _wrapAsDebuggerVarArgsFunction(JsFunction jsFunction) => |
856 ([a1 = _UNDEFINED, a2 = _UNDEFINED, a3 = _UNDEFINED, a4 = _UNDEFINED, | 862 ([a1 = _UNDEFINED, a2 = _UNDEFINED, a3 = _UNDEFINED, a4 = _UNDEFINED, |
857 a5 = _UNDEFINED, a6 = _UNDEFINED, a7 = _UNDEFINED, a8 = _UNDEFINED, | 863 a5 = _UNDEFINED, a6 = _UNDEFINED, a7 = _UNDEFINED, a8 = _UNDEFINED, |
858 a9 = _UNDEFINED, a10 = _UNDEFINED]) => jsFunction._applyDebuggerOnly( | 864 a9 = _UNDEFINED, a10 = _UNDEFINED]) => jsFunction._applyDebuggerOnly( |
859 _stripUndefinedArgs([a1, a2, a3, a4, a5, a6, a7, a8, a9, a10])); | 865 _stripUndefinedArgs([a1, a2, a3, a4, a5, a6, a7, a8, a9, a10])); |
OLD | NEW |