Merge pull request #1969 from AnalyticalGraphicsInc/timeline-doc

Add rudimentary Timeline documentation for 1.0
CesiumGS · Jul 28, 2014 · d3d4411 · d3d4411
2 parents 6b4030b + 5fdee66
commit d3d4411
Show file tree

Hide file tree

Showing 3 changed files with 76 additions and 10 deletions.
diff --git a/Source/Widgets/Timeline/Timeline.js b/Source/Widgets/Timeline/Timeline.js
@@ -73,7 +73,16 @@ define([
 
     var timelineMonthNames = ['Jan', 'Feb', 'Mar', 'Apr', 'May', 'Jun', 'Jul', 'Aug', 'Sep', 'Oct', 'Nov', 'Dec'];
 
-    function Timeline(container, clock) {
+
+    /**
+     * The Timeline is a widget for displaying and controlling the current scene time.
+     * @alias Timeline
+     * @constructor
+     *
+     * @param {Element} container The parent HTML container node for this widget.
+     * @param {Clock} clock The clock to use.
+     */
+    var Timeline = function(container, clock) {
         //>>includeStart('debug', pragmas.debug);
         if (!defined(container)) {
             throw new DeveloperError('container is required.');
@@ -156,20 +165,33 @@ define([
 
         clock.onTick.addEventListener(this.updateFromClock, this);
         this.updateFromClock();
-    }
+    };
 
+    /**
+     * @private
+     */
     Timeline.prototype.addEventListener = function(type, listener, useCapture) {
         this._topDiv.addEventListener(type, listener, useCapture);
     };
 
+    /**
+     * @private
+     */
     Timeline.prototype.removeEventListener = function(type, listener, useCapture) {
         this._topDiv.removeEventListener(type, listener, useCapture);
     };
 
+    /**
+     * @returns {Boolean} true if the object has been destroyed, false otherwise.
+     */
     Timeline.prototype.isDestroyed = function() {
         return false;
     };
 
+    /**
+     * Destroys the widget.  Should be called if permanently
+     * removing the widget from layout.
+     */
     Timeline.prototype.destroy = function() {
         this._clock.onTick.removeEventListener(this.updateFromClock, this);
 
@@ -187,13 +209,19 @@ define([
         destroyObject(this);
     };
 
+    /**
+     * @private
+     */
     Timeline.prototype.addHighlightRange = function(color, heightInPx, base) {
         var newHighlightRange = new TimelineHighlightRange(color, heightInPx, base);
         this._highlightRanges.push(newHighlightRange);
         this.resize();
         return newHighlightRange;
     };
 
+    /**
+     * @private
+     */
     Timeline.prototype.addTrack = function(interval, heightInPx, color, backgroundColor) {
         var newTrack = new TimelineTrack(interval, heightInPx, color, backgroundColor);
         this._trackList.push(newTrack);
@@ -202,17 +230,28 @@ define([
         return newTrack;
     };
 
-    Timeline.prototype.zoomTo = function(startJulianDate, endJulianDate) {
-        this._timeBarSecondsSpan = JulianDate.secondsDifference(endJulianDate, startJulianDate);
-
+    /**
+     * Sets the view to the provided times.
+     *
+     * @param {JulianDate} startTime The start time.
+     * @param {JulianDate} stopTime The stop time.
+     */
+    Timeline.prototype.zoomTo = function(startTime, stopTime) {
         //>>includeStart('debug', pragmas.debug);
-        if (this._timeBarSecondsSpan <= 0) {
+        if (!defined(startTime)) {
+            throw new DeveloperError('startTime is required.');
+        }
+        if (!defined(stopTime)) {
+            throw new DeveloperError('stopTime is required');
+        }
+        if (JulianDate.lessThanOrEquals(stopTime, startTime)) {
             throw new DeveloperError('Start time must come before end time.');
         }
         //>>includeEnd('debug');
 
-        this._startJulian = startJulianDate;
-        this._endJulian = endJulianDate;
+        this._startJulian = startTime;
+        this._endJulian = stopTime;
+        this._timeBarSecondsSpan = JulianDate.secondsDifference(stopTime, startTime);
 
         // If clock is not unbounded, clamp timeline range to clock.
         if (this._clock && (this._clock.clockRange !== ClockRange.UNBOUNDED)) {
@@ -252,6 +291,9 @@ define([
         this._topDiv.dispatchEvent(evt);
     };
 
+    /**
+     * @private
+     */
     Timeline.prototype.zoomFrom = function(amount) {
         var centerSec = JulianDate.secondsDifference(this._scrubJulian, this._startJulian);
         if ((amount > 1) || (centerSec < 0) || (centerSec > this._timeBarSecondsSpan)) {
@@ -267,8 +309,11 @@ define([
         return ((num < 10) ? ('0' + num.toString()) : num.toString());
     }
 
-    Timeline.prototype.makeLabel = function(julianDate) {
-        var gregorian = JulianDate.toGregorianDate(julianDate);
+    /**
+     * @private
+     */
+    Timeline.prototype.makeLabel = function(time) {
+        var gregorian = JulianDate.toGregorianDate(time);
         var millisecond = gregorian.millisecond, millisecondString = ' UTC';
         if ((millisecond > 0) && (this._timeBarSecondsSpan < 3600)) {
             millisecondString = Math.floor(millisecond).toString();
@@ -282,8 +327,14 @@ define([
             ':' + twoDigits(gregorian.minute) + ':' + twoDigits(gregorian.second) + millisecondString;
     };
 
+    /**
+     * @private
+     */
     Timeline.prototype.smallestTicInPixels = 7.0;
 
+    /**
+     * @private
+     */
     Timeline.prototype._makeTics = function() {
         var timeBar = this._timeBarEle;
 
@@ -498,6 +549,9 @@ define([
         });
     };
 
+    /**
+     * @private
+     */
     Timeline.prototype.updateFromClock = function() {
         this._scrubJulian = this._clock.currentTime;
         var scrubElement = this._scrubElement;
@@ -518,6 +572,9 @@ define([
         }
     };
 
+    /**
+     * @private
+     */
     Timeline.prototype._setTimeBarTime = function(xPos, seconds) {
         xPos = Math.round(xPos);
         this._scrubJulian = JulianDate.addSeconds(this._startJulian, seconds, new JulianDate());
@@ -705,6 +762,9 @@ define([
         };
     }
 
+    /**
+     * Resizes the widget to match the container size.
+     */
     Timeline.prototype.resize = function() {
         var width = this.container.clientWidth;
         var height = this.container.clientHeight;

diff --git a/Source/Widgets/Timeline/TimelineHighlightRange.js b/Source/Widgets/Timeline/TimelineHighlightRange.js
@@ -7,6 +7,9 @@ define([
         JulianDate) {
     "use strict";
 
+    /**
+     * @private
+     */
     function TimelineHighlightRange(color, heightInPx, base) {
         this._color = color;
         this._height = heightInPx;

diff --git a/Source/Widgets/Timeline/TimelineTrack.js b/Source/Widgets/Timeline/TimelineTrack.js
@@ -9,6 +9,9 @@ define([
         JulianDate) {
     "use strict";
 
+    /**
+     * @private
+     */
     function TimelineTrack(interval, pixelHeight, color, backgroundColor) {
         this.interval = interval;
         this.height = pixelHeight;