Combine window.setTimeout/setInterval with Timer and Timer.repeating. Also

tools/dom/templates/html/impl/impl_Window.darttemplate

 // Copyright (c) 2012, the Dart project authors.  Please see the AUTHORS file
 // for details. All rights reserved. Use of this source code is governed by a
 // BSD-style license that can be found in the LICENSE file.
 
 part of $LIBRARYNAME;
 
+$if DART2JS
 $(ANNOTATIONS)class $CLASSNAME$EXTENDS$IMPLEMENTS native "@*DOMWindow" {
+$else
+$(ANNOTATIONS)class $CLASSNAME$EXTENDS$IMPLEMENTS$NATIVESPEC {
+$endif
 
+  /**
+   * Returns a Future that will complete when the immediate execution stack has
+   * completed. 
+   * 
+   * This differs from using Timer(const Duration(milliseconds: 0), callback)

[floitsch, 2013/02/13 10:03:07]

Timer.run

[Emily Fortuna, 2013/02/13 20:19:44]

Done.

+   * because Timer will run in about 4-15 milliseconds, depending on browser,
+   * depending on load. [immediate], in contrast, performs makes 
+   * browser-specific changes to attempt to run immediately after the current
+   * frame unwinds, causing the future to complete after all processing has
+   * completed for the current event, but before any subsequent events.
+   */
+  Future get immediate {

[blois, 2013/02/13 03:09:24]

Question for Florian-
What is the plan for Future.defer, or similar. Is this API redundant with
something in dart:async?

If this is still in-flight, could we remove this portion of the CL?

[floitsch, 2013/02/13 10:03:07]

Current plan is to have a top-level "defer" in dart:async.
The question is not, if we want to have something like it, but what the name and
location should be.
A top-level "defer" in async would make sense, but would mean that sub-classes
that need to access a super-class' "defer" method or field, would not get it.
(resolution finds top-level before super-class).
I'm still leaning towards adding it as top-level 'defer' (in dart:async), but I
could easily be convinced otherwise.

+    var completer = new Completer<int>();
+    _addMicrotaskCallback(() { completer.complete(); });
+    return completer.future;
+  }
+  /**
+   * Lookup a port by its [name].  Return null if no port is
+   * registered under [name].
+   */
+  SendPortSync lookupPort(String name) {
+    var port =
+        json.parse(document.documentElement.attributes['dart-port:$name']);
+    return _deserialize(port);
+  }
+
+  /**
+   * Register a [port] on this window under the given [name].  This
+   * port may be retrieved by any isolate (or JavaScript script)
+   * running in this window.
+   */
+  void registerPort(String name, var port) {
+    var serialized = _serialize(port);
+    document.documentElement.attributes['dart-port:$name'] =
+        json.stringify(serialized);
+  }
+
+  /**
+   * Returns a Future that completes just before the window is about to repaint
+   * so the user can draw an animation frame
+   *
+   * If you need to later cancel this animation, use [requestAnimationFrame]
+   * instead.
+   *
+   * Note: The code that runs when the future completes should call 
+   * [animationFrame] again for the animation to continue.
+   */
+  Future<int> get animationFrame {

[blois, 2013/02/13 03:09:24]

I believe this needs to be num, as it can be fractional.

[Emily Fortuna, 2013/02/13 20:19:44]

You're right. I was reading the MDN docs, in which case it doesn't matter for
JavaScript! 

+    var completer = new Completer<int>();
+    requestAnimationFrame((scheduledTime) {completer.complete(scheduledTime);});

[floitsch, 2013/02/13 10:03:07]

requestAnimationFrame(completer.complete);

(unless you want to transform the scheduledTime to an int).

[Emily Fortuna, 2013/02/13 20:19:44]

Done.

+    return completer.future;
+  }
+
+$if DART2JS
   Document get document => JS('Document', '#.document', this);
 
   WindowBase _open2(url, name) => JS('Window', '#.open(#,#)', this, url, name);
 
   WindowBase _open3(url, name, options) =>
       JS('Window', '#.open(#,#,#)', this, url, name, options);
 
   WindowBase open(String url, String name, [String options]) {
     if (options == null) {
       return _DOMWindowCrossFrame._createSafe(_open2(url, name));
@@ skipping 45 matching lines @@
     // On Firefox the code that implements 'is Location' fails to find the patch
     // stub on Object.prototype and throws an exception.
     try {
       return thing is Location;
     } catch (e) {
       return false;
     }
   }
 
   /**
-   * Executes a [callback] after the immediate execution stack has completed.
+   * Called to draw an animation frame and then request the window to repaint
+   * after [callback] has finished (creating the animation). 
    *
-   * This will cause the callback to be executed after all processing has
-   * completed for the current event, but before any subsequent events.
+   * Use this method only if you need to later call [cancelAnimationFrame]. If
+   * not, the preferred Dart idiom is to set animation frames by calling
+   * [animationFrame], which returns a Future.
+   *
+   * Returns a non-zero valued integer to represent the request id for this
+   * request. This value only needs to be saved if you intend to call
+   * [cancelAnimationFrame] so you can specify the particular animation to
+   * cancel.
+   *
+   * Note: The supplied [callback] needs to call [requestAnimationFrame] again
+   * for the animation to continue.
    */
-  void setImmediate(TimeoutHandler callback) {
-    _addMicrotaskCallback(callback);
-  }
-
   @DomName('DOMWindow.requestAnimationFrame')
   int requestAnimationFrame(RequestAnimationFrameCallback callback) {
     _ensureRequestAnimationFrame();
     return _requestAnimationFrame(callback);
   }
 
   void cancelAnimationFrame(id) {
     _ensureRequestAnimationFrame();
     _cancelAnimationFrame(id);
   }
@@ skipping 38 matching lines @@
    */
   @SupportedBrowser(SupportedBrowser.CHROME, '23.0')
   @SupportedBrowser(SupportedBrowser.FIREFOX, '15.0')
   @SupportedBrowser(SupportedBrowser.IE, '10.0')
   @Experimental
   IdbFactory get indexedDB =>
       JS('IdbFactory',
          '#.indexedDB || #.webkitIndexedDB || #.mozIndexedDB',
          this, this, this);
 
-  /**
-   * Lookup a port by its [name].  Return null if no port is
-   * registered under [name].
-   */
-  SendPortSync lookupPort(String name) {
-    var port = json.parse(document.documentElement.attributes['dart-port:$name']);
-    return _deserialize(port);
-  }
-
-  /**
-   * Register a [port] on this window under the given [name].  This
-   * port may be retrieved by any isolate (or JavaScript script)
-   * running in this window.
-   */
-  void registerPort(String name, var port) {
-    var serialized = _serialize(port);
-    document.documentElement.attributes['dart-port:$name'] = json.stringify(serialized);
-  }
-
   @DomName('Window.console')
   Console get console => Console.safeConsole;
 
   /// Checks if _setImmediate is supported.
   static bool get _supportsSetImmediate =>
       JS('bool', '!!(window.setImmediate)');
 
   // Set immediate implementation for IE
   void _setImmediate(void callback()) {
     JS('void', '#.setImmediate(#)', this, convertDartClosureToJS(callback, 0));
   }
+$else
+  /// Checks if _setImmediate is supported.
+  static bool get _supportsSetImmediate => false;
+
+  /// Dartium stub for IE's setImmediate.
+  void _setImmediate(void callback()) {
+    throw new UnsupportedError('setImmediate is not supported');
+  }
+$endif
 
 $!MEMBERS
 }