Rearrange scheduling library (#3388)

To be more consistent with other parts of the platform:

* put the binding in a binding.dart file.

* rearrange some members of the Scheduler class to be more close to
  execution order.

* factor out Priority class into its own file.

* add more dart docs.

packages/flutter/lib/scheduler.dart

@@ -11,5 +11,6 @@
 /// For example, an idle-task is only executed when no animation is running.
 library scheduler;
 
-export 'src/scheduler/scheduler.dart';
+export 'src/scheduler/binding.dart';
+export 'src/scheduler/priority.dart';
 export 'src/scheduler/ticker.dart';

packages/flutter/lib/src/scheduler/priority.dart

+// Copyright 2016 The Chromium Authors. All rights reserved.
+// Use of this source code is governed by a BSD-style license that can be
+// found in the LICENSE file.
+
+/// A task priority, as passed to [Scheduler.scheduleTask].
+class Priority {
+  const Priority._(this._value);
+
+  /// The integer that describes this Priority value.
+  int get value => _value;
+  final int _value;
+
+  /// A task to run after all other tasks, when no animations are running.
+  static const Priority idle = const Priority._(0);
+
+  /// A task to run even when animations are running.
+  static const Priority animation = const Priority._(100000);
+
+  /// A task to run even when the user is interacting with the device.
+  static const Priority touch = const Priority._(200000);
+
+  /// Maximum offset by which to clamp relative priorities.
+  ///
+  /// It is still possible to have priorities that are offset by more
+  /// than this amount by repeatedly taking relative offsets, but that
+  /// is generally discouraged.
+  static const int kMaxOffset = 10000;
+
+  /// Returns a priority relative to this priority.
+  ///
+  /// A positive [offset] indicates a higher priority.
+  ///
+  /// The parameter [offset] is clamped to ±[kMaxOffset].
+  Priority operator +(int offset) {
+    if (offset.abs() > kMaxOffset) {
+      // Clamp the input offset.
+      offset = kMaxOffset * offset.sign;
+    }
+    return new Priority._(_value + offset);
+  }
+
+  /// Returns a priority relative to this priority.
+  ///
+  /// A positive offset indicates a lower priority.
+  ///
+  /// The parameter [offset] is clamped to ±[kMaxOffset].
+  Priority operator -(int offset) => this + (-offset);
+}

packages/flutter/lib/src/scheduler/ticker.dart

@@ -4,14 +4,22 @@
 
 import 'dart:async';
 
-import 'scheduler.dart';
+import 'binding.dart';
 
 /// Signature for the [onTick] constructor argument of the [Ticker] class.
+///
+/// The argument is the time that the object had spent enabled so far
+/// at the time of the callback being invoked.
 typedef void TickerCallback(Duration elapsed);
 
 /// Calls its callback once per animation frame.
+///
+/// When created, a ticker is initially disabled. Call [start] to
+/// enable the ticker.
+///
+/// See also [Scheduler.scheduleFrameCallback].
 class Ticker {
-  /// Constructs a ticker that will call [onTick] once per frame while running.
+  /// Creates a ticker that will call [onTick] once per frame while running.
   Ticker(TickerCallback onTick) : _onTick = onTick;
 
   final TickerCallback _onTick;
@@ -20,7 +28,11 @@ class Ticker {
   int _animationId;
   Duration _startTime;
 
-  /// Starts calling onTick once per animation frame.
+  /// Whether this ticker has scheduled a call to invoke its callback
+  /// on the next frame.
+  bool get isTicking => _completer != null;
+
+  /// Starts calling the ticker's callback once per animation frame.
   ///
   /// The returned future resolves once the ticker stops ticking.
   Future<Null> start() {
@@ -31,7 +43,7 @@ class Ticker {
     return _completer.future;
   }
 
-  /// Stops calling onTick.
+  /// Stops calling the ticker's callback.
   ///
   /// Causes the future returned by [start] to resolve.
   void stop() {
@@ -54,9 +66,6 @@ class Ticker {
     localCompleter.complete();
   }
 
-  /// Whether this ticker has scheduled a call to onTick
-  bool get isTicking => _completer != null;
-
   void _tick(Duration timeStamp) {
     assert(isTicking);
     assert(_animationId != null);